@linzumi/cli 0.0.34-beta → 0.0.35-beta

package/README.md

@@ -50,10 +50,61 @@ real dotfiles, and your real branches. No "works in the sandbox VM,
 breaks in your repo" surprises. The chat side runs in your browser;
 the work side runs locally. This npm package is the local half.
 
+## What you'll have in three minutes
+
+- A Linzumi workspace in your browser.
+- A local Commander connected to one trusted project folder.
+- A live Coding agent thread your team can watch and steer.
+- Optional browser editor and preview forwarding for the running app.
+
+## Manual Runner Setup
+
+Install the CLI or run it with `npx`:
+
 ```bash
+npm install -g @linzumi/cli@latest
+npx -y @linzumi/cli@0.0.35-beta --version
 linzumi --version
 ```
 
+Start a local runner from a trusted folder:
+
+```bash
+linzumi paths add ~/code/my-app
+linzumi start ~/code/my-app
+```
+
+For explicit runner roots, pass a comma-separated allowlist:
+
+```bash
+linzumi start ~/code/my-app --allowed-cwd <paths>
+```
+
+## Agent-first launch path
+
+The fastest path is still the `codex` prompt above. It uses the npm CLI
+to sign in, trust a demo project, connect the Commander, and start the
+first visible Coding agent thread.
+
+## What just happened
+
+Linzumi keeps the browser/chat surface separate from the local work
+surface. The CLI authenticates your local Commander, publishes runner
+capabilities, and lets Kandan ask that Commander to start Codex inside
+trusted folders only.
+
+## Three things to try first
+
+- Ask the Coding agent to make a small UI change and watch the thread.
+- Open the browser editor from the thread controls.
+- Share the preview URL with a teammate or your phone.
+
+## Working as a team
+
+Use the Linzumi thread as the shared source of truth. Humans can reply,
+steer, interrupt, or inspect output while the actual commands still run
+on the trusted local machine.
+
 ## Trusted folders
 
 Linzumi only edits inside folders you've explicitly trusted.
@@ -65,6 +116,13 @@ linzumi paths add ~/code/my-app
 The trust list lives at `~/.linzumi/config.json`. The bootstrap agent
 adds `/tmp/hello_linzumi` for you on first run.
 
+## When something looks wrong
+
+Run `linzumi --help` or reconnect with `linzumi start ~/code/my-app`.
+If the browser says no runner is connected, check that the terminal
+running the Commander is still open and that the folder is listed in
+`~/.linzumi/config.json`.
+
 ---
 
 *Slack-shaped on the surface. A multiplayer compiler underneath.*

package/dist/index.js

@@ -5680,7 +5680,7 @@ function kandanHttpBaseUrl(kandanUrl) {
     case "https:":
       break;
     default:
-      throw new Error("--kandan-url must be ws://, wss://, http://, or https://");
+      throw new Error("--linzumi-url must be ws://, wss://, http://, or https://");
   }
   parsed.pathname = "";
   parsed.search = "";
@@ -9354,6 +9354,7 @@ async function waitForFileChangeOrTimeout(path, deadline, now, ready2 = () => fa
 // src/index.ts
 var flagDefinitions = new Map([
   ["version", { kind: "boolean" }],
+  ["linzumi-url", { kind: "value" }],
   ["kandan-url", { kind: "value" }],
   ["token", { kind: "value" }],
   ["runner-id", { kind: "value" }],
@@ -9363,6 +9364,7 @@ var flagDefinitions = new Map([
   ["launch-tui", { kind: "boolean" }],
   ["workspace", { kind: "value" }],
   ["channel", { kind: "value" }],
+  ["linzumi-thread-id", { kind: "value" }],
   ["kandan-thread-id", { kind: "value" }],
   ["listen-user", { kind: "value" }],
   ["model", { kind: "value" }],
@@ -9382,6 +9384,10 @@ var flagDefinitions = new Map([
   ["oauth-callback-host", { kind: "value" }],
   ["help", { kind: "boolean" }]
 ]);
+var flagAliases = new Map([
+  ["kandan-url", "linzumi-url"],
+  ["kandan-thread-id", "linzumi-thread-id"]
+]);
 var helloFlagDefinitions = new Map([
   ["dir", { kind: "value" }],
   ["parent-dir", { kind: "value" }],
@@ -9415,7 +9421,7 @@ async function main(args) {
       process.stdout.write(connectGuideText());
       return;
     case "version":
-      process.stdout.write(`linzumi 0.0.34-beta
+      process.stdout.write(`linzumi 0.0.35-beta
 `);
       return;
     case "auth":
@@ -9661,7 +9667,7 @@ async function runAuthCommand(args) {
     process.stdout.write(helpText());
     return;
   }
-  const kandanUrl = required(values, "kandan-url");
+  const kandanUrl = required(values, "linzumi-url");
   const target = parseOptionalChannelTarget(values);
   const token = await acquireLocalRunnerTokenDetails({
     kandanUrl,
@@ -9675,7 +9681,7 @@ async function runAuthCommand(args) {
     expiresInSeconds: token.expiresInSeconds,
     authFilePath: stringValue3(values, "auth-file")
   });
-  process.stdout.write(`Saved Kandan local runner auth for ${cached.kandanBaseUrl}
+  process.stdout.write(`Saved Linzumi local runner auth for ${cached.kandanBaseUrl}
 `);
 }
 async function parseStartRunnerArgs(args, deps = {
@@ -9692,7 +9698,7 @@ async function parseStartRunnerArgs(args, deps = {
     process.exit(0);
   }
   rejectStartTargetingFlags(values);
-  const kandanUrl = stringValue3(values, "kandan-url") ?? defaultLinzumiWebSocketUrl;
+  const kandanUrl = stringValue3(values, "linzumi-url") ?? defaultLinzumiWebSocketUrl;
   const requestedCwd = resolveUserPath(cwdArg ?? process.cwd());
   const cwd = assertConfiguredAllowedCwds([requestedCwd])[0] ?? requestedCwd;
   const explicitAllowedCwds = values.has("allowed-cwd") ? assertConfiguredAllowedCwds(parseAllowedCwdList(stringValue3(values, "allowed-cwd"))) : [];
@@ -9709,7 +9715,7 @@ async function parseStartRunnerArgs(args, deps = {
   const authFilePath = stringValue3(values, "auth-file");
   const callbackHost = stringValue3(values, "oauth-callback-host");
   const reportRejectedCachedToken = () => {
-    process.stderr.write(`Cached Kandan local runner auth was rejected; starting OAuth.
+    process.stderr.write(`Cached Linzumi local runner auth was rejected; starting OAuth.
 `);
   };
   const token = await deps.resolveToken({
@@ -9768,7 +9774,7 @@ async function parseStartRunnerArgs(args, deps = {
     channelSession: {
       workspaceSlug: target.workspaceSlug,
       channelSlug: target.channelSlug,
-      kandanThreadId: stringValue3(values, "kandan-thread-id"),
+      kandanThreadId: stringValue3(values, "linzumi-thread-id"),
       listenUser: stringValue3(values, "listen-user") ?? defaultListenUserFromToken(targetToken),
       model: stringValue3(values, "model"),
       reasoningEffort: stringValue3(values, "reasoning-effort"),
@@ -9797,7 +9803,7 @@ async function parseAgentRunnerArgs(args, deps = {
   const tokenFile = readStoredAgentTokenFile(tokenFilePath, deps.readTextFile);
   const channelSlug = requiredStoredAgentChannel(tokenFile.channelId);
   const listenUser = stringValue3(values, "listen-user") ?? requiredStoredOwnerUsername(tokenFile.ownerUsername);
-  const kandanUrl = stringValue3(values, "kandan-url") ?? agentApiUrlToKandanUrl(tokenFile.apiUrl);
+  const kandanUrl = stringValue3(values, "linzumi-url") ?? agentApiUrlToKandanUrl(tokenFile.apiUrl);
   const requestedCwdValue = cwdArg ?? stringValue3(values, "cwd");
   const requestedCwd = resolveUserPath(requestedCwdValue ?? process.cwd());
   const allowedCwds = values.has("allowed-cwd") ? assertConfiguredAllowedCwds(parseAllowedCwdList(stringValue3(values, "allowed-cwd"))) : requestedCwdValue === undefined ? readConfiguredAllowedCwds() : assertConfiguredAllowedCwds([requestedCwd]);
@@ -9842,7 +9848,7 @@ async function parseAgentRunnerArgs(args, deps = {
     channelSession: {
       workspaceSlug: tokenFile.workspaceId,
       channelSlug,
-      kandanThreadId: stringValue3(values, "kandan-thread-id"),
+      kandanThreadId: stringValue3(values, "linzumi-thread-id"),
       listenUser,
       model: stringValue3(values, "model"),
       reasoningEffort: stringValue3(values, "reasoning-effort"),
@@ -9929,12 +9935,12 @@ async function parseRunnerArgs(args, deps = {
     process.exit(0);
   }
   if (values.get("version") === true) {
-    process.stdout.write(`linzumi 0.0.34-beta
+    process.stdout.write(`linzumi 0.0.35-beta
 `);
     process.exit(0);
   }
   const channelTarget = parseChannelSessionTarget(values);
-  const kandanUrl = required(values, "kandan-url");
+  const kandanUrl = required(values, "linzumi-url");
   const cwd = stringValue3(values, "cwd") ?? process.cwd();
   const codexBin = stringValue3(values, "codex-bin") ?? "codex";
   const customCodeServerBin = stringValue3(values, "code-server-bin");
@@ -9947,7 +9953,7 @@ async function parseRunnerArgs(args, deps = {
     authFilePath: stringValue3(values, "auth-file"),
     callbackHost: stringValue3(values, "oauth-callback-host"),
     reportRejectedCachedToken: () => {
-      process.stderr.write(`Cached Kandan local runner auth was rejected; starting OAuth.
+      process.stderr.write(`Cached Linzumi local runner auth was rejected; starting OAuth.
 `);
     }
   });
@@ -9991,18 +9997,19 @@ function strictFlagValues(args, definitions = flagDefinitions) {
     if (arg === undefined || !arg.startsWith("--")) {
       throw new Error(`invalid argument: ${arg ?? ""}`);
     }
-    const key = arg.slice(2);
-    const definition = definitions.get(key);
+    const rawKey = arg.slice(2);
+    const definition = definitions.get(rawKey);
     if (definition === undefined) {
-      throw new Error(`invalid flag: --${key}`);
+      throw new Error(`invalid flag: --${rawKey}`);
     }
+    const key = flagAliases.get(rawKey) ?? rawKey;
     if (definition.kind === "boolean") {
       values.set(key, true);
       continue;
     }
     const next = args[index + 1];
     if (next === undefined || next.startsWith("--")) {
-      throw new Error(`missing value for --${key}`);
+      throw new Error(`missing value for --${rawKey}`);
     }
     values.set(key, next);
     index += 1;
@@ -10089,7 +10096,7 @@ function parseChannelSession(values, token, target) {
   return {
     workspaceSlug: target.workspaceSlug,
     channelSlug: target.channelSlug,
-    kandanThreadId: stringValue3(values, "kandan-thread-id"),
+    kandanThreadId: stringValue3(values, "linzumi-thread-id"),
     listenUser,
     model: stringValue3(values, "model"),
     reasoningEffort: stringValue3(values, "reasoning-effort"),
@@ -10185,11 +10192,12 @@ Usage:
   linzumi commander <folder> [options]
   linzumi start <folder> [options]
   linzumi paths list|add|remove [path]
-  linzumi connect --kandan-url <ws-url> --workspace <slug> --channel <slug> [options]
-  linzumi auth --kandan-url <ws-url> [--workspace <slug> --channel <slug>]
+  linzumi connect --linzumi-url <ws-url> --workspace <slug> --channel <slug> [options]
+  linzumi auth --linzumi-url <ws-url> [--workspace <slug> --channel <slug>]
 
 Required:
-  --kandan-url <ws-url>       Linzumi backend URL, default ${defaultLinzumiWebSocketUrl}
+  --linzumi-url <ws-url>      Linzumi backend URL, default ${defaultLinzumiWebSocketUrl}
+                                (deprecated alias: --kandan-url)
   --token <jwt>               Optional override token. Otherwise ~/.linzumi/auth.json is validated or OAuth opens.
   --auth-file <path>          Auth cache path, default ~/.linzumi/auth.json
   --oauth-callback-host <ip>  Callback host reachable by your browser
@@ -10197,7 +10205,8 @@ Required:
 Channel binding:
   --workspace <slug>          Workspace slug
   --channel <slug|w/c>        Channel slug, or workspace/channel
-  --kandan-thread-id <uuid>   Resume an existing Linzumi thread instead of announcing a new root
+  --linzumi-thread-id <uuid>  Resume an existing Linzumi thread instead of announcing a new root
+                                (deprecated alias: --kandan-thread-id)
   --listen-user <user|all>    User whose replies are accepted, default authenticated user
 
 Codex:
@@ -10326,7 +10335,8 @@ What it does:
   previews, and the browser VS Code editor.
 
 Options:
-  --kandan-url <ws-url>       Linzumi backend URL, default ${defaultLinzumiWebSocketUrl}
+  --linzumi-url <ws-url>      Linzumi backend URL, default ${defaultLinzumiWebSocketUrl}
+                                (deprecated alias: --kandan-url)
   --token <jwt>               Optional scoped local-runner token override
   --auth-file <path>          Auth cache path, default ~/.linzumi/auth.json
   --oauth-callback-host <ip>  Callback host reachable by your browser
@@ -10366,23 +10376,24 @@ What it does:
 
 Options:
   --agent-token-file <path>   Agent token cache, default ~/.linzumi/agent-token.json
-  --kandan-url <ws-url>       Kandan websocket base URL. Defaults deterministically from the stored apiUrl.
+  --linzumi-url <ws-url>      Linzumi websocket base URL. Defaults deterministically from the stored apiUrl.
+                                (deprecated alias: --kandan-url)
   --runner-id <id>            Stable Commander id
   --codex-bin <path>          Codex executable, default codex
-  --code-server-bin <path>    Custom development code-server executable. By default Kandan installs the approved editor runtime.
+  --code-server-bin <path>    Custom development code-server executable. By default Linzumi installs the approved editor runtime.
   --listen-user <user>        Human whose replies Codex may accept, default owner from claim
   --model <name>              Model requested for Codex sessions
   --reasoning-effort <value>  Reasoning effort requested for Codex sessions
-  --sandbox <value>           Sandbox metadata shown in Kandan
-  --approval-policy <value>   Approval-policy metadata shown in Kandan
-  --forward-port <ports>      Comma-separated local TCP ports Kandan may expose as previews
+  --sandbox <value>           Sandbox metadata shown in Linzumi
+  --approval-policy <value>   Approval-policy metadata shown in Linzumi
+  --forward-port <ports>      Comma-separated local TCP ports Linzumi may expose as previews
   --allowed-cwd <paths>       Override ~/.linzumi/config.json or selected folder with comma-separated trusted roots
   --fast                      Mark this Commander as low-latency/fast in Linzumi
 
 Examples:
   linzumi paths add "$PWD"
   linzumi commander daemon --runner-id hello-world-commander
-  linzumi commander ~/code/my-app --kandan-url ws://127.0.0.1:4162 --runner-id local-qa-commander
+  linzumi commander ~/code/my-app --linzumi-url ws://127.0.0.1:4162 --runner-id local-qa-commander
 `;
 }
 function connectGuideText() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linzumi/cli",
-  "version": "0.0.34-beta",
+  "version": "0.0.35-beta",
   "description": "Linzumi CLI — point a Codex agent at the real code on your laptop, with your team watching and steering from shared threads.",
   "type": "module",
   "bin": {