diggylab 0.1.42 → 0.1.44

package/README.md

@@ -56,16 +56,29 @@ npm publish apps/desktop-agent/dist-npm --access public
 
 | Command | What it does |
 | --- | --- |
-| `pair --code <code> [--name <device name>] [--api <origin>]` | Pairs the server as a device. Create the code on `/settings/desktop-agent` in the web app. |
+| `pair [--code <code>] [--name <device name>]` | Pairs the server as a device. Create the code on `/settings/desktop-agent` in the web app; leave `--code` out and the command asks for it. |
 | `login` | Opens Facebook's real login page in a browser window when the machine has a screen. On a server without one it asks for `facebook.com` cookies pasted from your own browser, and the session is stored encrypted. |
+| `logout` | Removes the stored Facebook session from this server (the device pairing stays). |
+| `rename [--name <new name>]` | Renames the device shown in the web app; leave `--name` out and the command asks for it. |
 | `run` | Connects the WebSocket worker, receives assigned scans, scans headlessly, uploads results. |
 | `status` | Shows the config directory, API origin, paired device, and Facebook session state. |
 | `install-browser` | Downloads the Chromium build Playwright needs (~150 MB). It also runs during `npm install`, so you only need it if that download failed. |
+| `install-service` | On a Linux server with systemd, writes the unit for `run`, enables it, and starts it now and on every boot. |
+| `uninstall-service` | Stops that service and removes the unit. |
 | `unpair` | Removes device credentials, the Facebook session, and pending scans. |
 
 Useful options: `--api <origin>` (default `https://api.diggylab.com`), `--cookies <file>` to import
 cookies directly.
 
+`pair` and `login` finish by printing what is still missing, so you do not need to run `status`
+between steps:
+
+```
+Paired:   "DiggyLab" (device-1)
+Facebook: missing
+Next: run `diggylab login` — on a server without a screen it asks you to paste cookies.
+```
+
 ## How `login` works
 
 Two paths, depending on the machine:
@@ -98,8 +111,12 @@ The equivalents: `diggylab login --cookies 'name=value; ...'` for a quoted one-l
 `diggylab login --cookies cookies.json` for a saved file.
 
 Only `name` and `value` are required; the agent fills in the rest (`.facebook.com`, `/`, session
-expiry). Every `facebook.com` cookie is kept, and at least `c_user` plus `xs` must be present — those
-two carry the session, and `datr` is worth keeping too.
+expiry). Every `facebook.com` cookie is kept. The export must contain `c_user` (the agent rejects it
+otherwise) and `xs`, which carries the session — without `xs` Facebook refuses the session during the
+check, and `datr` is worth keeping too.
+
+If you paste cookies, prefer the file form or `--cookies -` over `--cookies '...'`: a value on the
+command line stays in your shell history, and pasted text stays in the terminal scrollback.
 
 Do not use `document.cookie` from the Console: Facebook's `c_user` and `xs` are HttpOnly, so they
 never appear there. The DevTools cookie table and the extension do show them.
@@ -111,6 +128,21 @@ instead of failing during a scan.
 Note: Facebook sometimes asks for a security check when a session moves to a server's IP. If that
 happens the command says so — approve the login from your phone and import again.
 
+## Troubleshooting
+
+- `socket closed: 1005` followed by `session: ONLINE` about every 14 minutes is **normal**: the access
+  token lives 15 minutes, so the worker refreshes it one minute early and reconnects with the new one
+  (the disconnect lasts a second or two, and a running scan keeps going).
+- `socket closed: 4009` right after `session: ONLINE` means **two workers use the same device** — for
+  example the systemd service plus a manual `diggylab run`. The worker that connected last keeps the
+  device and the older one stops with a message. Check `pgrep -af "diggylab run"` and
+  `systemctl status diggylab --no-pager`, then keep only one.
+- `socket error:` plus `socket closed: 1006` and `RECONNECTING (NETWORK_ERROR)` is a dropped
+  connection; the worker retries with backoff. If it never settles, check `curl -sS -o /dev/null -w
+  '%{http_code}\n' https://api.diggylab.com/health` and that the machine clock is right (`date -u`),
+  because a clock off by more than five minutes makes the server's messages look stale.
+- `Facebook: missing` after a login means the session did not survive; run `diggylab login` again.
+
 ## Security notes
 
 - `~/.diggylab/key` (mode `600`) encrypts device credentials, the Facebook session, and the
@@ -121,22 +153,40 @@ happens the command says so — approve the login from your phone and import aga
 
 ## Run as a service
 
+On a Linux server with systemd, let the CLI write the unit for you:
+
+```bash
+diggylab install-service      # writes /etc/systemd/system/diggylab.service, enables + starts it
+diggylab uninstall-service    # stops it and removes the unit
+journalctl -u diggylab -f     # follow the worker log
+```
+
+The unit keeps the same state directory and API origin you are using, restarts the worker if it
+crashes, and starts it on boot. It points at npm's `diggylab` symlink, so upgrading the package is
+enough — no need to reinstall the service. Run it as root (or with `sudo`) to write the unit.
+
+<details>
+<summary>Equivalent unit, if you prefer to write it yourself</summary>
+
 ```ini
 [Unit]
-Description=DiggyLab Desktop Agent CLI
+Description=DiggyLab Desktop Agent
 After=network-online.target
+Wants=network-online.target
 
 [Service]
-User=diggylab
-WorkingDirectory=/opt/diggylab
-ExecStart=/usr/bin/node /opt/diggylab/dist-cli/cli/cli.js run
-Restart=always
-Environment=DIGGYLAB_API_URL=https://api.diggylab.com
+ExecStart=/usr/local/bin/diggylab run
+Environment="DIGGYLAB_AGENT_DIR=/root/.diggylab"
+Environment="DIGGYLAB_API_URL=https://api.diggylab.com"
+Restart=on-failure
+RestartSec=10
 
 [Install]
 WantedBy=multi-user.target
 ```
 
+</details>
+
 ## Docker
 
 ```bash

package/cli.js

@@ -3,7 +3,7 @@
 // src/cli/cli.ts
 import { randomUUID as randomUUID3 } from "node:crypto";
 import { spawn } from "node:child_process";
-import { existsSync as existsSync2, readFileSync as readFileSync2, realpathSync } from "node:fs";
+import { existsSync as existsSync2, readFileSync as readFileSync2, realpathSync, rmSync, writeFileSync as writeFileSync2 } from "node:fs";
 import { hostname, homedir } from "node:os";
 import { dirname as dirname3, join as join3 } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -727,6 +727,16 @@ var DeviceCredentialManager = class {
     });
     return this.refreshPromise;
   }
+  /** Renames the device on the server and in the stored session, so `status` and the web agree. */
+  async rename(name) {
+    const access = this.access ?? await this.refresh();
+    const device = await this.http.rename(access.accessToken, name);
+    const session = { ...access.session, device };
+    await this.store.save(session);
+    this.stored = session;
+    this.access = { ...access, session };
+    return device;
+  }
   getStoredSession() {
     return this.stored;
   }
@@ -816,6 +826,15 @@ var DesktopAgentHttpClient = class {
     if (!isDeviceSummary(value)) throw new DesktopAgentClientError("DESKTOP_RESPONSE_INVALID");
     return value;
   }
+  async rename(accessToken, name) {
+    const value = await this.request("/desktop-agent-auth/me", {
+      body: JSON.stringify({ name }),
+      headers: { authorization: `Bearer ${accessToken}`, "content-type": "application/json" },
+      method: "PATCH"
+    });
+    if (!isDeviceSummary(value)) throw new DesktopAgentClientError("DESKTOP_RESPONSE_INVALID");
+    return value;
+  }
   async requestCredential(path, body) {
     const value = await this.request(path, {
       body: JSON.stringify(body),
@@ -1031,13 +1050,13 @@ var DesktopAgentSession = class {
     this.socket = socket;
     socket.on("message", (data) => this.handleMessage(socket, data, access, generation));
     socket.on("error", () => this.handleDisconnect(socket, access.session, generation));
-    socket.on("close", () => this.handleDisconnect(socket, access.session, generation));
+    socket.on("close", (code) => this.handleDisconnect(socket, access.session, generation, typeof code === "number" ? code : void 0));
   }
   handleMessage(socket, data, access, generation) {
     if (generation !== this.generation || socket !== this.socket) return;
     const envelope = parseServerEnvelope(data);
     if (!envelope || envelope.deviceId !== access.session.device.id || envelope.protocolVersion !== DESKTOP_AGENT_PROTOCOL_VERSION || Math.abs(Date.now() - Date.parse(envelope.sentAt)) > MESSAGE_FRESHNESS_MS || this.replayIds.has(envelope.messageId)) {
-      this.protocolFailure(socket, access.session, generation);
+      this.protocolFailure(socket, access.session, generation, describeEnvelopeProblem(envelope, access.session.device.id, this.replayIds));
       return;
     }
     this.rememberMessage(envelope.messageId);
@@ -1147,19 +1166,23 @@ var DesktopAgentSession = class {
       void this.start(false);
     }, delay);
   }
-  handleDisconnect(socket, stored, generation) {
+  handleDisconnect(socket, stored, generation, code) {
     if (generation !== this.generation || socket !== this.socket) return;
     this.socket = null;
     this.clearHeartbeat();
     this.clearAccessRefresh();
+    if (code === 4009) {
+      this.update(snapshotForSession("RECONNECTING", stored, "CONNECTION_REPLACED"));
+      return;
+    }
     this.scheduleReconnect(stored, generation, "NETWORK_ERROR");
   }
-  protocolFailure(socket, stored, generation) {
+  protocolFailure(socket, stored, generation, reason = "malformed message") {
     if (socket === this.socket) this.socket = null;
     socket.close();
     this.clearHeartbeat();
     this.clearAccessRefresh();
-    this.scheduleReconnect(stored, generation, "PROTOCOL_VIOLATION");
+    this.scheduleReconnect(stored, generation, `PROTOCOL_VIOLATION: ${reason}`);
   }
   scheduleReconnect(stored, generation, errorCode) {
     if (generation !== this.generation || this.reconnectTimer) return;
@@ -1248,6 +1271,15 @@ function parseServerEnvelope(data) {
     return null;
   }
 }
+function describeEnvelopeProblem(envelope, deviceId, replayIds) {
+  if (!envelope) return "unreadable message";
+  if (envelope.deviceId !== deviceId) return `wrong device ${envelope.deviceId}`;
+  if (envelope.protocolVersion !== DESKTOP_AGENT_PROTOCOL_VERSION) return `protocol version ${envelope.protocolVersion}`;
+  const offsetMs = Date.now() - Date.parse(envelope.sentAt);
+  if (Math.abs(offsetMs) > MESSAGE_FRESHNESS_MS) return `stale message (sentAt ${envelope.sentAt}, offset ${Math.round(offsetMs / 1e3)}s)`;
+  if (replayIds.has(envelope.messageId)) return `replayed message ${envelope.messageId}`;
+  return "unknown";
+}
 function emptySnapshot(state) {
   return {
     state,
@@ -2402,11 +2434,10 @@ function parseCookieTable(input) {
   const cookies = [];
   for (const line of input.split("\n")) {
     const columns = line.split("	");
-    if (columns.length < 2) return [];
-    const name = columns[0].trim();
+    const name = columns[0]?.trim() ?? "";
     const value = columns[1];
-    if (!name || name === "Name" || !value) continue;
-    cookies.push({ name, value });
+    if (!value || !name || name === "Name") continue;
+    cookies.push({ domain: columns[2]?.trim(), name, value });
   }
   return cookies;
 }
@@ -2493,17 +2524,45 @@ function createFileCrypto(keyPath) {
   };
 }
 
+// src/cli/systemd.ts
+var SERVICE_NAME = "diggylab";
+var SERVICE_PATH = `/etc/systemd/system/${SERVICE_NAME}.service`;
+function quote(value) {
+  return /\s/.test(value) ? `"${value.replace(/"/g, '\\"')}"` : value;
+}
+function buildSystemdUnit(options) {
+  return `[Unit]
+Description=DiggyLab Desktop Agent
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+ExecStart=${options.execStart.map(quote).join(" ")} run
+Environment="DIGGYLAB_AGENT_DIR=${options.configDirectory}"
+Environment="DIGGYLAB_API_URL=${options.apiOrigin}"
+Restart=on-failure
+RestartSec=10
+
+[Install]
+WantedBy=multi-user.target
+`;
+}
+
 // src/cli/cli.ts
 var LOGIN_TIMEOUT_MS = 10 * 60 * 1e3;
 var CONFIG_DIRECTORY = ".diggylab";
 var USAGE = `DiggyLab Desktop Agent CLI
 
 Usage:
-  diggylab pair --code <code> [--name <device name>] [--api <https://api.diggylab.com>]
+  diggylab pair [--code <code>] [--name <device name>]   (asks for the code when you leave it out)
   diggylab login                          (opens a browser window when the machine has a screen)
   diggylab login cookies                  (no screen: paste facebook.com cookies when asked)
   diggylab login --cookies <file>         (or --cookies 'name=value; ...')
+  diggylab logout
+  diggylab rename [--name <new name>]        (asks for the name when you leave it out)
   diggylab run
+  diggylab install-service                   (systemd: start "run" on boot)
+  diggylab uninstall-service
   diggylab status
   diggylab install-browser
   diggylab unpair
@@ -2552,6 +2611,17 @@ function createRuntime(options) {
   const manager = new DeviceCredentialManager(sessions, http, createDeviceIdentity);
   return { activity, browserType: createBrowserLauncher(chromium), directory, endpoint, facebook, manager, sessions, spool };
 }
+function stamp() {
+  return `[${(/* @__PURE__ */ new Date()).toTimeString().slice(0, 8)}]`;
+}
+function describeSocketError(error) {
+  if (error instanceof Error) {
+    const code = error.code;
+    return `${error.message || error.name}${typeof code === "string" ? ` (${code})` : ""}`;
+  }
+  if (error && typeof error === "object" && "type" in error) return `event ${String(error.type)}`;
+  return String(error);
+}
 function waitForFacebookLogin(login, timeoutMs) {
   return new Promise((resolve, reject) => {
     const timer = setTimeout(() => {
@@ -2596,9 +2666,9 @@ function pairErrorMessage(error, origin) {
   }
 }
 async function commandPair(runtime, options, io) {
-  const code = options.code?.trim();
+  const code = options.code?.trim() || await promptForPairingCode(io);
   if (!code) {
-    io.error("Missing --code <pairing code>. Create one on the Desktop Agent page of the web app.");
+    io.error("No pairing code entered. Create one in the web app: Settings \u2192 Desktop Agent \u2192 Create pairing code.");
     return 2;
   }
   try {
@@ -2609,13 +2679,72 @@ async function commandPair(runtime, options, io) {
       platform: resolvePlatform()
     });
     io.log(`Paired as "${access.session.device.name}".`);
-    io.log("Next: run `diggylab login` to connect a Facebook account.");
+    await printReadiness(runtime, io);
     return 0;
   } catch (error) {
     io.error(pairErrorMessage(error, runtime.endpoint.httpOrigin));
     return 1;
   }
 }
+async function promptForPairingCode(io) {
+  if (process.stdin.isTTY) {
+    io.log("Create a pairing code in the web app: Settings \u2192 Desktop Agent \u2192 Create pairing code.");
+    io.log("It works once and expires after 10 minutes.");
+    io.log("Paste the code here, then press Enter.");
+  }
+  return (await readAnswer()).trim();
+}
+async function printReadiness(runtime, io) {
+  const stored = await runtime.sessions.load();
+  const facebook = await runtime.facebook.load();
+  const hasUser = Boolean(facebook?.cookies?.some((cookie) => cookie.name === "c_user" && cookie.value));
+  io.log(`Paired:   ${stored ? `"${stored.device.name}" (${stored.device.id})` : "no"}`);
+  io.log(`Facebook: ${hasUser ? "connected" : "missing"}`);
+  if (!stored) {
+    io.log("Next: create a pairing code in the web app, then run `diggylab pair`.");
+  } else if (!hasUser) {
+    io.log("Next: run `diggylab login` \u2014 on a server without a screen it asks you to paste cookies.");
+  } else {
+    io.log("Ready: start the worker with `diggylab run`.");
+  }
+}
+async function commandLogout(runtime, io) {
+  await runtime.facebook.clear();
+  io.log("Facebook session removed from this server.");
+  await printReadiness(runtime, io);
+  return 0;
+}
+async function commandRename(runtime, options, io) {
+  const stored = await runtime.manager.load();
+  if (!stored) {
+    io.error("This server is not paired yet. Run `diggylab pair` first.");
+    return 1;
+  }
+  const requested = options.name?.trim() || await promptForName(io);
+  if (!requested) {
+    io.error('A device name is required, for example `diggylab rename --name "VPS H\xE0 N\u1ED9i"`.');
+    return 2;
+  }
+  const name = sanitizeDeviceName(requested);
+  try {
+    const device = await runtime.manager.rename(name);
+    io.log(`Renamed to "${device.name}".`);
+    await printReadiness(runtime, io);
+    return 0;
+  } catch (error) {
+    if (error instanceof DesktopAgentClientError && error.code === "DESKTOP_RESPONSE_INVALID") {
+      io.error("The API answered the rename with something unexpected \u2014 usually an API that does not have this endpoint yet.");
+      io.error(`Deploy the API, then check it with: curl -s -o /dev/null -w '%{http_code}\\n' -X PATCH https://api.diggylab.com/desktop-agent-auth/me -H 'content-type: application/json' -d '{"name":"x"}'  (401 = the endpoint exists)`);
+      return 1;
+    }
+    io.error(`Could not rename this device: ${error instanceof Error ? error.message : String(error)}`);
+    return 1;
+  }
+}
+async function promptForName(io) {
+  if (process.stdin.isTTY) io.log("Type the new device name, then press Enter.");
+  return (await readAnswer()).trim();
+}
 async function commandLogin(runtime, options, io) {
   if (options.cookies !== void 0) return importFacebookCookies(runtime, options.cookies || "-", io);
   if (process.platform === "linux" && !process.env.DISPLAY) {
@@ -2643,6 +2772,7 @@ async function commandLogin(runtime, options, io) {
     io.log(process.env.DISPLAY ? `Opening the Facebook login page on display ${process.env.DISPLAY}.` : "Opening the Facebook login page in a browser window.");
     await waitForFacebookLogin(login, LOGIN_TIMEOUT_MS + 6e4);
     io.log("Facebook session saved.");
+    await printReadiness(runtime, io);
     return 0;
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
@@ -2683,8 +2813,10 @@ async function importFacebookCookies(runtime, source, io) {
     io.error("Open facebook.com in your browser, make sure you are logged in, then copy the `cookie:` request header again.");
     return 1;
   }
+  let saved = false;
   try {
     const accountId = await runtime.facebook.save(state);
+    saved = true;
     io.log(`Facebook session saved for account ${accountId}. Asking Facebook to confirm it...`);
     const condition = await validateImportedSession(runtime, state);
     if (condition !== "READY") {
@@ -2694,6 +2826,7 @@ async function importFacebookCookies(runtime, source, io) {
     }
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
+    if (saved) await runtime.facebook.clear();
     if (/Executable doesn't exist|playwright install/i.test(message)) {
       io.error(MISSING_BROWSER_HINT);
     } else if (message === "FACEBOOK_SESSION_INVALID") {
@@ -2704,6 +2837,7 @@ async function importFacebookCookies(runtime, source, io) {
     return 1;
   }
   io.log("Facebook session saved.");
+  await printReadiness(runtime, io);
   return 0;
 }
 async function validateImportedSession(runtime, state) {
@@ -2729,9 +2863,12 @@ function readStdin() {
   });
 }
 function readPastedCookies(io) {
-  if (!process.stdin.isTTY) return readStdin();
   io.log("Paste the facebook.com cookies here, then press Enter.");
   io.log("In your browser: F12 \u2192 Network \u2192 click any facebook.com request \u2192 copy the whole `cookie:` value.");
+  return readAnswer({ until: (value) => value.includes("c_user") });
+}
+function readAnswer(options = {}) {
+  if (!process.stdin.isTTY) return readStdin();
   return new Promise((resolve) => {
     let value = "";
     let idle;
@@ -2743,12 +2880,14 @@ function readPastedCookies(io) {
     };
     const handleData = (chunk) => {
       value += chunk;
-      if (idle) clearTimeout(idle);
-      if (value.includes("\n") && value.includes("c_user")) {
+      if (value.includes("\n") && (!options.until || options.until(value))) {
         finish();
         return;
       }
-      idle = setTimeout(finish, 350);
+      if (idle) clearTimeout(idle);
+      idle = setTimeout(() => {
+        if (!options.until || options.until(value)) finish();
+      }, 350);
     };
     process.stdin.setEncoding("utf8");
     process.stdin.on("data", handleData);
@@ -2776,10 +2915,14 @@ async function commandInstallBrowser(io) {
     child.once("exit", (value) => resolve(value ?? 1));
   });
   let code = 1;
-  for (const [index, args] of browserInstallCommands(process.platform).entries()) {
-    if (index > 0) io.log("Installing the system libraries failed; downloading the browser only...");
-    code = await run(args);
-    if (code === 0) break;
+  try {
+    for (const [index, args] of browserInstallCommands(process.platform).entries()) {
+      if (index > 0) io.log("Installing the system libraries failed; downloading the browser only...");
+      code = await run(args);
+      if (code === 0) break;
+    }
+  } catch {
+    code = 1;
   }
   if (code !== 0) {
     io.error(soft ? "Chromium download failed. Run `diggylab install-browser` later." : "Chromium download failed. Check the network and try again.");
@@ -2806,8 +2949,9 @@ async function commandRun(runtime, io) {
         headers: { authorization: `Bearer ${accessToken}` },
         maxPayload: 16 * 1024
       });
+      socket.on("error", (error) => io.log(`${stamp()} socket error: ${describeSocketError(error)}`));
       socket.on("close", (code, reason) => {
-        io.log(`socket closed: ${code}${reason?.length ? ` (${reason.toString()})` : ""}`);
+        io.log(`${stamp()} socket closed: ${code}${reason?.length ? ` (${reason.toString()})` : ""}`);
       });
       return socket;
     },
@@ -2851,9 +2995,18 @@ async function commandRun(runtime, io) {
     spool: runtime.spool,
     wait: abortableDelay
   });
+  let onReplaced = () => void 0;
+  const replaced = new Promise((resolve) => {
+    onReplaced = resolve;
+  });
   session.subscribe((snapshot) => {
-    io.log(`session: ${snapshot.state}`);
+    io.log(`${stamp()} session: ${snapshot.state}${snapshot.errorCode ? ` (${snapshot.errorCode})` : ""}`);
     recordActivity(`Session state changed to ${snapshot.state}.`, snapshot.state);
+    if (snapshot.errorCode === "CONNECTION_REPLACED") {
+      io.error("Another worker is already running with this device, so this one stopped.");
+      io.error("Stop the other worker (for example: systemctl stop diggylab), then start this one again.");
+      onReplaced();
+    }
   });
   scanRunner.subscribe((snapshot) => {
     io.log(`scanner: ${snapshot.state}${snapshot.jobId ? ` (job ${snapshot.jobId})` : ""}`);
@@ -2862,13 +3015,16 @@ async function commandRun(runtime, io) {
   scanRunner.start();
   await scanRunner.recover();
   await session.start();
-  io.log(`Worker running as "${stored.device.name}". Press Ctrl+C to stop.`);
+  io.log(`Worker running as "${stored.device.name}" (API ${runtime.endpoint.httpOrigin}). Press Ctrl+C to stop.`);
   const keepAlive = setInterval(() => void 0, 6e4);
   try {
-    await new Promise((resolve) => {
-      process.once("SIGINT", resolve);
-      process.once("SIGTERM", resolve);
-    });
+    await Promise.race([
+      new Promise((resolve) => {
+        process.once("SIGINT", resolve);
+        process.once("SIGTERM", resolve);
+      }),
+      replaced
+    ]);
   } finally {
     clearInterval(keepAlive);
     session.stop();
@@ -2894,6 +3050,71 @@ async function commandUnpair(runtime, io) {
   io.log("Device unpaired; local credentials, Facebook session, and pending scans were removed.");
   return 0;
 }
+function runCommand(command, args) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { stdio: "inherit" });
+    child.once("error", reject);
+    child.once("exit", (value) => resolve(value ?? 1));
+  });
+}
+function resolveServiceExecStart() {
+  const candidates = [join3(dirname3(process.execPath), "diggylab"), "/usr/local/bin/diggylab", "/usr/bin/diggylab"];
+  const link = candidates.find((candidate) => existsSync2(candidate));
+  return link ? [link] : [process.execPath, fileURLToPath(import.meta.url)];
+}
+async function commandInstallService(runtime, io) {
+  if (process.platform !== "linux") {
+    io.error("Automatic service setup supports Linux (systemd). Use the Docker image or your platform's service manager.");
+    return 1;
+  }
+  if (!existsSync2("/usr/bin/systemctl") && !existsSync2("/bin/systemctl")) {
+    io.error("systemd is not available on this machine.");
+    return 1;
+  }
+  const unit = buildSystemdUnit({
+    apiOrigin: runtime.endpoint.httpOrigin,
+    configDirectory: runtime.directory,
+    execStart: resolveServiceExecStart()
+  });
+  try {
+    writeFileSync2(SERVICE_PATH, unit, { mode: 420 });
+  } catch {
+    io.error(`Could not write ${SERVICE_PATH}. Run this command as root (or with sudo).`);
+    return 1;
+  }
+  io.log(`Wrote ${SERVICE_PATH}.`);
+  io.log(`State directory: ${runtime.directory}`);
+  if (process.env.SUDO_USER && process.env.SUDO_USER !== "root" && runtime.directory === join3(homedir(), CONFIG_DIRECTORY)) {
+    io.error(`Heads up: this ran as root, so the service will use ${runtime.directory} (root's home).`);
+    io.error(`If you paired as "${process.env.SUDO_USER}", pass --config to point at that user's ~/${CONFIG_DIRECTORY} instead.`);
+  }
+  await runCommand("systemctl", ["daemon-reload"]).catch(() => 1);
+  const code = await runCommand("systemctl", ["enable", "--now", SERVICE_NAME]);
+  if (code !== 0) {
+    io.error(`systemctl could not enable the service. Check it with: systemctl status ${SERVICE_NAME}`);
+    return code;
+  }
+  io.log(`Service ${SERVICE_NAME} is enabled: it runs now and after every reboot.`);
+  io.log(`Follow its log with: journalctl -u ${SERVICE_NAME} -f`);
+  await printReadiness(runtime, io);
+  return 0;
+}
+async function commandUninstallService(io) {
+  if (process.platform !== "linux") {
+    io.error("Automatic service setup supports Linux (systemd).");
+    return 1;
+  }
+  await runCommand("systemctl", ["disable", "--now", SERVICE_NAME]).catch(() => 1);
+  try {
+    rmSync(SERVICE_PATH, { force: true });
+  } catch {
+    io.error(`Could not remove ${SERVICE_PATH}. Run this command as root (or with sudo).`);
+    return 1;
+  }
+  await runCommand("systemctl", ["daemon-reload"]).catch(() => 1);
+  io.log(`Service ${SERVICE_NAME} removed.`);
+  return 0;
+}
 async function main(argv, io = console) {
   if (argv.includes("--help") || argv.includes("-h")) {
     io.log(USAGE);
@@ -2910,7 +3131,7 @@ async function main(argv, io = console) {
     io.log(USAGE);
     return 0;
   }
-  if (!["install-browser", "login", "pair", "run", "status", "unpair"].includes(command)) {
+  if (!["install-browser", "install-service", "login", "logout", "pair", "rename", "run", "status", "uninstall-service", "unpair"].includes(command)) {
     io.error(`Unknown command "${command}".`);
     io.error(USAGE);
     return 2;
@@ -2922,12 +3143,24 @@ async function main(argv, io = console) {
       return commandPair(runtime, parsed.options, io);
     case "login":
       return commandLogin(runtime, parsed.options, io);
+    case "logout":
+      return commandLogout(runtime, io);
+    case "rename":
+      return commandRename(runtime, parsed.options, io);
+    case "install-service":
+      return commandInstallService(runtime, io);
+    case "uninstall-service":
+      return commandUninstallService(io);
     case "run":
       return commandRun(runtime, io);
     case "status":
       return commandStatus(runtime, io);
-    default:
+    case "unpair":
       return commandUnpair(runtime, io);
+    default:
+      io.error(`Unknown command "${command}".`);
+      io.error(USAGE);
+      return 2;
   }
 }
 function isEntryPoint() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "diggylab",
-  "version": "0.1.42",
+  "version": "0.1.44",
   "description": "DiggyLab Desktop Agent collects posts and information from Facebook Groups on a paired computer. (headless CLI)",
   "type": "module",
   "bin": {