@gleapai/kai-bridge 0.10.2 → 0.11.0

package/README.md

@@ -6,7 +6,7 @@ Claude Code / Codex login, and local dev-server previews.
 ```bash
 npm i -g @gleapai/kai-bridge   # one install, so the background service has a stable path
 kai-bridge login             # pair this machine with your Gleap account
-kai-bridge install           # run at login (launchd / systemd / Task Scheduler)
+kai-bridge service install   # run at login (launchd / systemd / Task Scheduler)
 kai-bridge status
 kai-bridge ps                # sessions running on this machine, with dashboard links (--json for tooling)
 ```
@@ -44,23 +44,38 @@ kai-bridge run --task "Explain the auth flow in this repo" --cwd ~/code/my-app
 `npm run sync-runner` copies the ACP runner from a sibling `gleap_code_analyzer` checkout;
 `npm test` runs the unit suite (uses real `git`).
 
+### Trying CLI changes locally
+
+```bash
+npm run cli -- status          # any kai-bridge command, run from this checkout
+npm run cli -- login --name "dev laptop"
+npm run cli -- start           # foreground daemon; Ctrl-C stops it
+npm run test:cli               # fast CLI regression suite (test/cli.test.mjs)
+```
+
+`npm run cli` (scripts/dev-cli.mjs) uses `<repo>/.kai-dev` as `KAI_HOME` and turns
+self-update off, so it never touches `~/.kai` or the background service running the
+released version. Export `KAI_API_BASE` / `KAI_APP_BASE` to point it at a local server.
+Don't `npm link` the package: the login service runs the global install by absolute
+path, and a link would swap that for this checkout.
+
 
 ### Computers and your own servers
 
 Kai Code offers **Kai Code Cloud** (Gleap's managed execution, using AI credits) or **Kai Code Bridge** (your coding agents on your computer or a server you manage, using your own AI subscriptions).
 
-Run `npm i -g @gleapai/kai-bridge && kai-bridge` in a local terminal or over SSH. The guided setup pairs the device, installs its background service and helps sign in to coding agents. Node.js 20+ and Git are required. On a Linux server, keep the user service running after logout using your system's service configuration; `kai-bridge doctor` reports service status.
+Run `npm i -g @gleapai/kai-bridge && kai-bridge` in a local terminal or over SSH. The guided setup pairs the device, installs its background service and helps sign in to coding agents. Node.js 20+ and Git are required. On a Linux server, keep the user service running after logout using your system's service configuration; `kai-bridge service status` and `kai-bridge service logs --follow` show what it is doing.
 
 Codex and Claude Code ship with Kai Code Bridge. Missing agents can be installed or repaired, and existing agents can be updated independently:
 
 ```sh
 kai-bridge harness install codex
 kai-bridge harness update codex
-kai-bridge harness login codex --device-auth
+kai-bridge profile login codex --device-auth
 
 kai-bridge harness install claude
 kai-bridge harness update claude
-kai-bridge harness login claude
+kai-bridge profile login claude
 ```
 
 Updates install into `~/.kai/harnesses`, verify the new executable, then select it for subsequent sessions. A failed download or startup leaves the previous version selected. Existing versions are retained for running sessions; your global CLI installations and agent logins are not overwritten. `--version <version>` selects a specific package version (for Claude, the Claude Agent SDK package version).

package/bin/kai-bridge.mjs

@@ -1,23 +1,10 @@
 #!/usr/bin/env node
 // kai-bridge — run Gleap Kai Code on this machine.
-//
-//   kai-bridge setup                 guided onboarding: pair · background service · harness sign-ins
-//                                    (a bare `kai-bridge` on an unpaired machine runs it too)
-//   kai-bridge login | logout        pair this device with your Gleap account / disconnect it
-//   kai-bridge install | uninstall   run at login (launchd / systemd / Task Scheduler)
-//   kai-bridge start                 run in the foreground (what the service runs)
-//   kai-bridge status                device, service, profiles, repos
-//   kai-bridge ps [--json]           what runs right now: daemon, turns, dev servers — with dashboard links
-//   kai-bridge harness list|install <id>|update <id>|login <id> [--device-auth]      Claude Code + Codex are bundled; Cursor is downloaded
-//   kai-bridge profile list|add <id> --harness claude|codex|cursor [--label …]|login <id>|remove <id>
-//   kai-bridge repo scan|roots [add <dir>|remove <dir>]|primary <repoKey> <path>
-//   kai-bridge run --task "…" [--model …] [--profile …] [--cwd …]   (local turn, no server)
-//   kai-bridge doctor
+// The command reference lives in src/help.mjs (`kai-bridge help`).
 
 import { spawn } from "node:child_process";
-import { mkdtempSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { dirname, join, resolve } from "node:path";
+import { platform } from "node:os";
+import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { KAI_HOME, loadConfig, saveConfig } from "../src/config.mjs";
@@ -26,13 +13,38 @@ import { BridgeDaemon, createLogger, resolveProfiles } from "../src/daemon.mjs";
 import { runTurn } from "../src/executor.mjs";
 import { HARNESSES, createManagedProfile, describeProfiles, findBinary, loginCommand } from "../src/profiles.mjs";
 import { defaultRoots, groupByRepo, scanRoots, toDeviceRepoReport } from "../src/repos.mjs";
-import { install, isInstalled, uninstall, isEphemeralBinPath } from "../src/service.mjs";
+import { install, isInstalled, uninstall, isEphemeralBinPath, servicePaths } from "../src/service.mjs";
+import { followFile, tailFile } from "../src/logs.mjs";
 import { HARNESS_INFO, describeHarnesses, installHarness } from "../src/harnesses.mjs";
 import { fetchLatestVersion, installVersion, installedVersion, isNewer } from "../src/selfupdate.mjs";
-import { collectProcessList, formatProcessList } from "../src/ps.mjs";
+import { collectProcessList, formatAge, formatProcessList } from "../src/ps.mjs";
+import { renderCommandHelp, renderHelp, suggestCommand } from "../src/help.mjs";
+import { palette } from "../src/tui.mjs";
 
 const BIN = fileURLToPath(import.meta.url);
+// `npm i -g` only warns on an old Node; the first run would die with a
+// SyntaxError instead. Say what is needed.
+{
+  const major = Number(process.versions.node.split(".")[0]);
+  if (major < 20) {
+    process.stderr.write(`error: kai-bridge needs Node.js 20 or newer (this is ${process.versions.node}). Install a current Node from https://nodejs.org and run it again.\n`);
+    process.exit(1);
+  }
+}
+// `kai-bridge help | head` closes our stdout early: end quietly, not with a stack.
+process.stdout.on("error", (err) => {
+  if (err?.code === "EPIPE") process.exit(0);
+  throw err;
+});
 const argv = process.argv.slice(2);
+// `--version`/`-v` and `--help`/`-h` are flags people type before or after the
+// command; normalise them into the `version` and `help` commands.
+if (argv.includes("--version") || argv.includes("-v") || argv[0] === "version") {
+  process.stdout.write(`${installedVersion()}\n`);
+  process.exit(0);
+}
+if (argv[0] === "--help" || argv[0] === "-h") argv[0] = "help";
+else if (argv.includes("--help") || argv.includes("-h")) argv.splice(0, argv.length, "help", argv[0]);
 const cmd = argv[0];
 const flags = {};
 const positional = [];
@@ -52,14 +64,18 @@ const fail = (s) => {
 async function login() {
   const config = loadConfig();
   await pairDevice({ config, name: flags.name, print: out });
-  out(`Next: \`kai-bridge install\` keeps it running at login. \`kai-bridge start\` runs it right now.`);
+  out(`Next: \`kai-bridge service install\` keeps it running at login (\`kai-bridge start\` runs it right now), then \`kai-bridge profile login claude\` (or codex/cursor) to sign in your coding agent. \`kai-bridge\` does all of this in one go.`);
 }
 
 async function status() {
   const config = loadConfig();
+  out(`node:     ${process.version} (${process.execPath})`);
+  out(`git:      ${findBinary("git") ?? "not found"}`);
+  out(`claude:   ${findBinary("claude") ?? "not on PATH (bundled copy is used)"}`);
+  out(`codex:    ${findBinary("codex") ?? "not on PATH (bundled copy is used)"}`);
   out(`home:     ${KAI_HOME}`);
   out(`device:   ${config.device ? `${config.device.name} (${config.device.id})` : "not paired — run `kai-bridge login`"}`);
-  out(`service:  ${isInstalled() ? "installed" : "not installed — run `kai-bridge install`"}`);
+  out(`service:  ${isInstalled() ? "installed" : "not installed — run `kai-bridge service install`"}`);
   out("harnesses:");
   for (const h of describeHarnesses(KAI_HOME)) out(`  ${h.id.padEnd(8)} ${h.installed ? `installed ${h.version ?? ""}` : "not installed — kai-bridge harness install " + h.id}${h.bundled ? " (bundled)" : ""}`);
   const profiles = await describeProfiles(resolveProfiles(config));
@@ -95,8 +111,10 @@ async function profile() {
     return;
   }
   if (sub === "login") {
-    const p = resolveProfiles(config).find((x) => x.id === positional[1]);
-    if (!p) fail("unknown profile");
+    // A harness name means the machine's own login for it.
+    const wanted = HARNESS_INFO[positional[1]] ? `${positional[1]}-ambient` : positional[1];
+    const p = resolveProfiles(config).find((x) => x.id === wanted);
+    if (!p) fail(`unknown profile ${positional[1] ?? ""} — \`kai-bridge profile list\` shows them; \`profile login claude|codex|cursor\` signs in the machine's own agent.`);
     await installHarness(p.harness, { kaiHome: KAI_HOME, onLog: out });
     const c = loginCommand(p.harness, p.configDir, KAI_HOME, flags["device-auth"] ? { deviceAuth: true } : undefined);
     if (!c) fail(`${p.harness} is not installed`);
@@ -110,7 +128,7 @@ async function profile() {
     out("removed (the login dir is kept under ~/.kai/accounts)");
     return;
   }
-  fail("usage: profile list|add|login|remove");
+  fail("usage: profile list | login <id> [--device-auth] | add <id> --harness <claude|codex|cursor> [--label …] | remove <id>");
 }
 
 async function harness() {
@@ -120,25 +138,22 @@ async function harness() {
     return;
   }
   const id = positional[1];
-  if (!HARNESS_INFO[id]) fail("usage: harness list|install <id>|update <id>|login <id> (claude|codex|cursor)");
+  if (!HARNESS_INFO[id]) fail("usage: harness list | install <id> | update <id>   (claude|codex|cursor — sign in with `profile login <id>`)");
   if (sub === "install" || sub === "update") {
     const res = await installHarness(id, { kaiHome: KAI_HOME, onLog: out, update: sub === "update", version: typeof flags.version === "string" ? flags.version : undefined });
     if (!res.ok) fail(`${id} is not usable`);
     out(`${HARNESS_INFO[id].label} ${res.version} → ${res.binary}`);
     return;
   }
-  if (sub === "login") {
-    positional[1] = `${id}-ambient`;
-    positional[0] = "login";
-    return profile();
-  }
-  fail("usage: harness list|install <id>|update <id>|login <id> [--device-auth]");
+  if (sub === "login") return profile(); // old spelling of `profile login <id>`
+  fail("usage: harness list | install <id> | update <id>");
 }
 
 async function repo() {
   const config = loadConfig();
-  const sub = positional[0] || "scan";
+  const sub = positional[0] || "roots";
   if (sub === "scan") {
+    // Undocumented: `status` shows the same list.
     const groups = groupByRepo(scanRoots([...defaultRoots(), ...(config.roots || [])]), config.primaryOverrides);
     for (const r of toDeviceRepoReport(groups)) out(`${r.key}\t${r.primaryPath}\t${r.branch}`);
     return;
@@ -160,7 +175,7 @@ async function repo() {
     out("ok");
     return;
   }
-  fail("usage: repo scan|roots [add|remove <dir>]|primary <repoKey> <path>");
+  fail("usage: repo roots [add <dir> | remove <dir>] | primary <repoKey> <path>   (`kai-bridge status` lists the checkouts)");
 }
 
 async function runLocal() {
@@ -187,13 +202,54 @@ async function runLocal() {
   process.exit(res.code ?? 0);
 }
 
-async function doctor() {
-  out(`node:    ${process.version}`);
-  out(`claude:  ${findBinary("claude") ?? "not found (npm i -g @anthropic-ai/claude-code)"}`);
-  out(`codex:   ${findBinary("codex") ?? "not found (npm i -g @openai/codex)"}`);
-  out(`git:     ${findBinary("git") ?? "not found"}`);
-  out(`home:    ${KAI_HOME}`);
-  await status();
+/** `kai-bridge service …` — the login service and its logs. */
+async function service() {
+  const sub = positional[0] || "status";
+  if (sub === "install") {
+    if (isEphemeralBinPath(BIN)) {
+      fail(
+        "Running from npx, so there's no stable path to install from.\n" +
+          "Install it once, then this works:\n\n" +
+          "  npm i -g @gleapai/kai-bridge\n  kai-bridge service install\n",
+      );
+    }
+    const res = install({ binPath: BIN, logDir: join(KAI_HOME, "logs") });
+    out(`Installed (${res.kind}): ${res.path}. It runs at login and restarts if it crashes.`);
+    return;
+  }
+  if (sub === "uninstall") {
+    out(uninstall() ? "Removed." : "Nothing to remove.");
+    return;
+  }
+  if (sub === "restart") {
+    if (!isInstalled()) fail("The background service is not installed — run `kai-bridge service install`.");
+    const res = install({ binPath: BIN, logDir: join(KAI_HOME, "logs") });
+    out(`Restarted (${res.kind}).`);
+    return;
+  }
+  if (sub === "status") {
+    const paths = servicePaths();
+    const unit = platform() === "darwin" ? paths.launchdPlist : platform() === "linux" ? paths.systemdUnit : "Task Scheduler: GleapKaiBridge";
+    const d = collectProcessList().daemon;
+    out(`service:  ${isInstalled() ? `installed · ${unit}` : "not installed — run `kai-bridge service install`"}`);
+    out(`daemon:   ${d.running ? `running · pid ${d.pid} · up ${formatAge(d.startedAt)} · v${d.version}` : `not running${d.pid ? ` (stale lock, pid ${d.pid})` : ""}`}`);
+    out(`logs:     ${join(KAI_HOME, "logs", "bridge.log")}`);
+    return;
+  }
+  if (sub === "logs") {
+    const file = join(KAI_HOME, "logs", flags.service ? "service.err.log" : "bridge.log");
+    const n = Number(flags.lines) || 50;
+    const last = tailFile(file, n);
+    if (last) out(last);
+    else if (!flags.follow) out(`(no log yet at ${file})`);
+    if (flags.follow) {
+      const ctrl = new AbortController();
+      process.on("SIGINT", () => ctrl.abort());
+      await followFile(file, { signal: ctrl.signal });
+    }
+    return;
+  }
+  fail("usage: service install | uninstall | restart | status | logs [--lines <n>] [--follow] [--service]");
 }
 
 try {
@@ -207,20 +263,14 @@ try {
     case "logout":
       await logout();
       break;
-    case "install": {
-      if (isEphemeralBinPath(BIN)) {
-        fail(
-          "Running from npx, so there's no stable path to install from.\n" +
-            "Install it once, then this works:\n\n" +
-            "  npm i -g @gleapai/kai-bridge\n  kai-bridge install\n",
-        );
-      }
-      const res = install({ binPath: BIN, logDir: join(KAI_HOME, "logs") });
-      out(`Installed (${res.kind}): ${res.path}. It runs at login and restarts if it crashes.`);
+    case "service":
+      await service();
       break;
-    }
+    case "install":
     case "uninstall":
-      out(uninstall() ? "Removed." : "Nothing to remove.");
+      // Old spellings, kept working.
+      positional.unshift(cmd);
+      await service();
       break;
     case "start": {
       process.env.KAI_BRIDGE_FOREGROUND = process.stdout.isTTY ? "1" : "0";
@@ -255,7 +305,7 @@ try {
       await runLocal();
       break;
     case "doctor":
-      await doctor();
+      await status();
       break;
     case "update": {
       // Manual update: ignores autoUpdate and a previous failed attempt.
@@ -288,14 +338,20 @@ try {
         await runSetup({ binPath: BIN });
         break;
       }
-      out(`kai-bridge — run Gleap Kai Code on this machine
-
-  setup                            guided onboarding (pair · service · sign-ins)
-  login | logout | install | uninstall | start | status | ps | doctor | update
-  harness list|install <id>|update <id>|login <id> [--device-auth]
-  profile list|add <id> --harness claude|codex|cursor|login <id>|remove <id>
-  repo scan|roots [add|remove <dir>]|primary <repoKey> <path>
-  run --task "…" [--model …] [--profile …] [--cwd …]`);
+      if (cmd === "help" || !cmd) {
+        const topic = positional[0];
+        if (topic) {
+          const lines = renderCommandHelp(topic, { paint: palette() });
+          if (!lines) fail(`unknown command: ${topic}${suggestCommand(topic) ? ` (did you mean \`${suggestCommand(topic)}\`?)` : ""}\nRun \`kai-bridge help\` to list the commands.`);
+          for (const l of lines) out(l);
+        } else {
+          for (const l of renderHelp({ paint: palette(), version: installedVersion() })) out(l);
+        }
+        break;
+      }
+      // Not a command at all. A close match is almost always a typo.
+      const near = suggestCommand(cmd);
+      fail(`unknown command: ${cmd}${near ? ` (did you mean \`${near}\`?)` : ""}\nRun \`kai-bridge help\` to list the commands.`);
     }
   }
 } catch (err) {

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@gleapai/kai-bridge",
-  "version": "0.10.2",
+  "version": "0.11.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@gleapai/kai-bridge",
-      "version": "0.10.2",
+      "version": "0.11.0",
       "hasInstallScript": true,
       "license": "MIT",
       "dependencies": {
@@ -134,9 +134,6 @@
       "cpu": [
         "arm64"
       ],
-      "libc": [
-        "glibc"
-      ],
       "license": "SEE LICENSE IN LICENSE.md",
       "optional": true,
       "os": [
@@ -150,9 +147,6 @@
       "cpu": [
         "arm64"
       ],
-      "libc": [
-        "musl"
-      ],
       "license": "SEE LICENSE IN LICENSE.md",
       "optional": true,
       "os": [
@@ -166,9 +160,6 @@
       "cpu": [
         "x64"
       ],
-      "libc": [
-        "glibc"
-      ],
       "license": "SEE LICENSE IN LICENSE.md",
       "optional": true,
       "os": [
@@ -182,9 +173,6 @@
       "cpu": [
         "x64"
       ],
-      "libc": [
-        "musl"
-      ],
       "license": "SEE LICENSE IN LICENSE.md",
       "optional": true,
       "os": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gleapai/kai-bridge",
-  "version": "0.10.2",
+  "version": "0.11.0",
   "description": "Kai Code Bridge runs Kai Code on your computer or server with your own coding subscriptions and local previews.",
   "type": "module",
   "license": "MIT",
@@ -25,7 +25,9 @@
     "postinstall": "node scripts/postinstall.mjs",
     "runtime:check": "node scripts/runtime-smoke.mjs",
     "prepack": "node scripts/prepare-release.mjs",
-    "postpack": "node scripts/prepare-release.mjs --clean"
+    "postpack": "node scripts/prepare-release.mjs --clean",
+    "cli": "node scripts/dev-cli.mjs",
+    "test:cli": "node --test test/cli.test.mjs"
   },
   "dependencies": {
     "@agentclientprotocol/claude-agent-acp": "0.81.1",

package/src/config.mjs

@@ -31,6 +31,7 @@ export function defaultConfig() {
     appBase: DEFAULT_APP_BASE,
     realtime: DEFAULT_REALTIME,
     device: null, // { id, name, token, organisationId, userId }
+    machineId: null, // stable per-install id; re-pairing keeps the same device row
     roots: [], // extra scan roots
     profiles: [
       { id: "claude-ambient", harness: "claude", kind: "ambient", label: "Claude (this machine)" },

package/src/help.mjs

@@ -0,0 +1,115 @@
+// The command reference: one table drives `kai-bridge help`, `help <command>`,
+// the "unknown command" hint and the usage lines the commands print themselves.
+
+import { palette } from "./tui.mjs";
+
+export const COMMANDS = [
+  // ── setup and account ──
+  { name: "setup", group: "Setup and account", usage: "setup", summary: "guided onboarding: pair, service, agent sign-ins",
+    details: ["Re-run it any time: it shows the machine's state and offers what is left to do."] },
+  { name: "login", group: "Setup and account", usage: "login [--name <device name>]", brief: "login [--name …]", summary: "pair this machine with your Gleap account",
+    details: ["Opens a link to approve in the dashboard. `--name` sets how the machine appears there."] },
+  { name: "logout", group: "Setup and account", usage: "logout", summary: "disconnect this machine, remove its service",
+    details: ["Your Claude Code / Codex / Cursor logins stay on the machine."] },
+  // ── service ──
+  { name: "service", group: "Background service", usage: "service install | uninstall | restart | status | logs [--lines <n>] [--follow]", brief: "service <action>",
+    summary: "the bridge that runs at login and restarts after crashes",
+    details: [
+      "install    add it (launchd on macOS, systemd --user on Linux, Task Scheduler on Windows) and start it",
+      "uninstall  stop and remove it",
+      "restart    reload it — after a manual `npm i -g`, or when it looks stuck",
+      "status     installed? running? since when? where are the logs?",
+      "logs       the last 50 lines of the bridge log; `--follow` keeps streaming, `--lines 200` shows more",
+    ],
+    examples: ["kai-bridge service logs --follow", "kai-bridge service restart"] },
+  { name: "start", group: "Background service", usage: "start", summary: "run in the foreground (what the service runs)",
+    details: ["Ctrl-C stops it. Only one bridge runs per machine: stop the service first, or use `kai-bridge service install`."] },
+  { name: "install", hidden: true, aliasOf: "service", usage: "install", summary: "same as `service install`" },
+  { name: "uninstall", hidden: true, aliasOf: "service", usage: "uninstall", summary: "same as `service uninstall`" },
+  // ── inspect ──
+  { name: "status", group: "Inspect", usage: "status", summary: "tools, device, service, agents, profiles, repos",
+    details: ["Node, git and agent binaries first, then the machine's pairing, service, sign-ins and the repos Kai can see."] },
+  { name: "ps", group: "Inspect", usage: "ps [--json]", summary: "running turns and dev servers, with links" },
+  { name: "doctor", hidden: true, aliasOf: "status", usage: "doctor", summary: "same as `status`" },
+  // ── agents ──
+  { name: "harness", group: "Coding agents", usage: "harness list | install <id> | update <id>", brief: "harness <action> [id]",
+    summary: "install or update Claude Code, Codex and Cursor",
+    details: ["<id> is claude, codex or cursor. Claude Code and Codex ship bundled; Cursor is downloaded on install.", "Signing in is `kai-bridge profile login <id>`."],
+    examples: ["kai-bridge harness update codex", "kai-bridge harness install cursor"] },
+  { name: "profile", group: "Coding agents", usage: "profile list | login <id> [--device-auth] | add <id> --harness <claude|codex|cursor> [--label …] | remove <id>", brief: "profile <action> [id]",
+    summary: "sign in to agents, and keep extra logins apart",
+    details: [
+      "`login claude` (or codex, cursor) signs in the machine's own agent. `--device-auth` uses a code instead of a browser (servers, SSH).",
+      "`add` creates a second, separate login — another Claude account, a shared team Codex — that sessions can pick.",
+    ],
+    examples: ["kai-bridge profile login codex --device-auth", "kai-bridge profile add work --harness claude --label \"Claude (work)\"", "kai-bridge profile login work"] },
+  // ── repos ──
+  { name: "repo", group: "Repositories", usage: "repo roots [add <dir> | remove <dir>] | primary <repoKey> <path>", brief: "repo <action> […]",
+    summary: "where Kai looks for checkouts, and the primary per repo",
+    details: ["Roots are scanned for git checkouts (`kai-bridge status` lists what was found). `primary` picks the checkout used when a repo appears more than once."],
+    examples: ["kai-bridge repo roots add ~/work", "kai-bridge repo primary github.com/acme/app ~/work/app"] },
+  // ── other ──
+  { name: "update", group: "Advanced", usage: "update", summary: "install the latest version now",
+    details: ["The background service updates itself; this forces it, also after a failed attempt."] },
+  { name: "help", group: "Advanced", usage: "help [command]", summary: "this list, or one command in detail" },
+  { name: "run", hidden: true, usage: "run --task \"…\" [--model <id>] [--profile <id>] [--cwd <dir>]", summary: "one local turn without the server (for development)",
+    examples: ["kai-bridge run --task \"Explain the auth flow\" --cwd ~/code/app"] },
+];
+
+export const findCommand = (name) => COMMANDS.find((c) => c.name === name) ?? null;
+
+/** `kai-bridge help` — grouped, one line per command. */
+export function renderHelp({ paint = palette(), version } = {}) {
+  const p = paint;
+  const lines = [`${p.bold("kai-bridge")}${version ? p.dim(` v${version}`) : ""} ${p.dim("— run Gleap Kai Code on this machine")}`, ""];
+  const shown = COMMANDS.filter((c) => !c.hidden);
+  const groups = [...new Set(shown.map((c) => c.group))];
+  const brief = (c) => c.brief ?? c.usage;
+  const w = Math.max(...shown.map((c) => brief(c).length)) + 2;
+  for (const g of groups) {
+    lines.push(p.dim(g));
+    for (const c of shown.filter((c) => c.group === g)) {
+      const args = brief(c).slice(c.name.length);
+      lines.push(`  ${p.magenta(c.name)}${p.dim(args)}${" ".repeat(w - brief(c).length)}${c.summary}`);
+    }
+    lines.push("");
+  }
+  lines.push(p.dim("kai-bridge help <command> shows details · --version prints the version"));
+  return lines;
+}
+
+/** `kai-bridge help <command>`. Null when the command does not exist. */
+export function renderCommandHelp(name, { paint = palette() } = {}) {
+  let c = findCommand(name);
+  if (!c) return null;
+  const p = paint;
+  const lines = [];
+  if (c.aliasOf) {
+    lines.push(p.dim(`\`kai-bridge ${c.usage}\` is ${c.summary.replace(/^same as /, "the same as ")}.`), "");
+    c = findCommand(c.aliasOf);
+  }
+  lines.push(`${p.bold(`kai-bridge ${c.usage}`)}`, "", `  ${c.summary}`);
+  if (c.details?.length) {
+    lines.push("");
+    for (const d of c.details) lines.push(`  ${d}`);
+  }
+  if (c.examples?.length) {
+    lines.push("", p.dim("  Examples"));
+    for (const e of c.examples) lines.push(`    ${e}`);
+  }
+  return lines;
+}
+
+/** The closest known command for a typo, or null when nothing is close. */
+export function suggestCommand(input) {
+  const s = String(input || "").toLowerCase();
+  if (!s) return null;
+  const dist = (a, b) => {
+    const d = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
+    for (let j = 1; j <= b.length; j += 1) d[0][j] = j;
+    for (let i = 1; i <= a.length; i += 1) for (let j = 1; j <= b.length; j += 1) d[i][j] = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+    return d[a.length][b.length];
+  };
+  const best = COMMANDS.filter((c) => !c.hidden).map((c) => ({ name: c.name, d: dist(s, c.name) })).sort((a, b) => a.d - b.d)[0];
+  return best && (best.d <= 2 || best.name.startsWith(s)) ? best.name : null;
+}

package/src/logs.mjs

@@ -0,0 +1,62 @@
+// `kai-bridge service logs`: the last lines of a log file, optionally
+// followed. Plain fs — the daemon appends lines, nothing rotates them.
+
+import { closeSync, existsSync, openSync, readSync, statSync, watchFile, unwatchFile } from "node:fs";
+
+/** The last `lines` lines of `path` ("" when the file is missing or empty). */
+export function tailFile(path, lines = 50) {
+  if (!existsSync(path)) return "";
+  const size = statSync(path).size;
+  if (size === 0) return "";
+  const fd = openSync(path, "r");
+  try {
+    // Read backwards in chunks until enough newlines are in hand.
+    const chunk = 64 * 1024;
+    let pos = size;
+    let buf = "";
+    while (pos > 0 && buf.split("\n").length <= lines + 1) {
+      const len = Math.min(chunk, pos);
+      pos -= len;
+      const b = Buffer.alloc(len);
+      readSync(fd, b, 0, len, pos);
+      buf = b.toString("utf8") + buf;
+    }
+    const all = buf.replace(/\n$/, "").split("\n");
+    return all.slice(-lines).join("\n");
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/**
+ * Print `path` as it grows. Resolves only when `signal` aborts (Ctrl-C).
+ * Polls via fs.watchFile: works on every platform and for files that do
+ * not exist yet (the daemon may start after `logs --follow`).
+ */
+export function followFile(path, { write = (s) => process.stdout.write(s), signal, intervalMs = 500 } = {}) {
+  let pos = existsSync(path) ? statSync(path).size : 0;
+  const drain = () => {
+    if (!existsSync(path)) return;
+    const size = statSync(path).size;
+    if (size < pos) pos = 0; // truncated or replaced
+    if (size === pos) return;
+    const fd = openSync(path, "r");
+    try {
+      const b = Buffer.alloc(size - pos);
+      readSync(fd, b, 0, b.length, pos);
+      write(b.toString("utf8"));
+      pos = size;
+    } finally {
+      closeSync(fd);
+    }
+  };
+  return new Promise((resolve) => {
+    watchFile(path, { interval: intervalMs }, drain);
+    const stop = () => {
+      unwatchFile(path, drain);
+      resolve();
+    };
+    if (signal?.aborted) stop();
+    else signal?.addEventListener("abort", stop, { once: true });
+  });
+}

package/src/ps.mjs

@@ -133,7 +133,7 @@ export function formatProcessList(list, { now = Date.now() } = {}) {
   lines.push(
     d.running
       ? `daemon:   running · pid ${d.pid}${d.version ? ` · v${d.version}` : ""} · up ${formatUptime(d.startedAt, now)}`
-      : `daemon:   not running${d.pid ? ` (stale lock, pid ${d.pid})` : ""} — run \`kai-bridge start\` or \`kai-bridge install\``,
+      : `daemon:   not running${d.pid ? ` (stale lock, pid ${d.pid})` : ""} — run \`kai-bridge start\` or \`kai-bridge service install\``,
   );
   if (!list.sessions.length) {
     lines.push("", "nothing running on this machine");

package/src/service.mjs

@@ -1,6 +1,6 @@
 // Login-item service: launchd (macOS) / systemd --user (Linux) /
 // Task Scheduler (Windows). Runs `kai-bridge start` at login, restarts
-// on crash, logs under ~/.kai/logs. `kai-bridge install` / `uninstall`.
+// on crash, logs under ~/.kai/logs. `kai-bridge service install|uninstall|restart|status|logs`.
 
 import { execFileSync } from "node:child_process";
 import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";