@vincentt-xr/cli 0.1.5 → 0.3.0

package/dist/cli/index.js

@@ -5,20 +5,37 @@
 //
 // Verb groups:
 //   auth        login · logout · whoami
-//   dev loop    create · publish · preview
+//   project     init · create · link · unlink
+//   dev loop    publish · preview
 //   diagnostics logs · network · trace
 //   reverse     feedback (--wait | --watch)
 //   servers     relay · mcp
 import os from "node:os";
 import path from "node:path";
-import { runLogin } from "../login/login.js";
+import { runPkceLogin } from "../login/pkceLogin.js";
+import { httpAuthBackend } from "../login/authBackend.js";
+import { loginCommand } from "../login/loginCommand.js";
 import { ensureLoggedIn } from "../login/ensure.js";
-import { clearMachineToken, clearProjectBinding, loadMachineConfig, } from "../shared/config.js";
-import { getMe } from "../lib/backend.js";
-import { diagQuery, diagRead, previewStart, previewStop, previewStopSignal, projectCreate, projectPublish, } from "../lib/lifecycle.js";
-import { writeQrPage } from "../preview/qrPage.js";
+import { clearMachineToken, loadMachineConfig, locateProjectBinding, resolveConfig, MACHINE_CONFIG_PATH, } from "../shared/config.js";
+import { getMe, ProjectUnreachableError } from "../lib/backend.js";
+import { initCommand } from "../lib/initCommand.js";
+import { linkCommand, printUnreachable, unlinkCommand } from "../lib/projects.js";
+import { whoamiCommand } from "../lib/whoami.js";
+import { diagQuery, diagRead, previewStart, previewStop, previewStopSignal, projectCreate, } from "../lib/lifecycle.js";
+import { publishCommand } from "../publish/command.js";
+import { stdinConfirm } from "../publish/prompt.js";
+import { consoleVerbCommand, isConsoleOnlyVerb } from "../publish/consoleVerbs.js";
+import { PreviewUi } from "../preview/command.js";
+import { httpRelayClient } from "../lib/diagnostics.js";
+import { readLivePreview } from "../lib/relayInfo.js";
+import { mintRateLimited, notSignedIn, previewConflict, startBlock, } from "../preview/copy.js";
+import { renderTerminalQr, shouldRenderQr } from "../preview/qr.js";
+import { PreviewConflictError, PreviewRateLimitedError } from "../preview/api.js";
 import { fetchNext, readCursor, writeCursor } from "../lib/feedback.js";
-const DEFAULT_EDITOR_URL = "https://editor.vincentt.studio";
+import { isHelpInvocation, positionalArgs, refusedFlag } from "./args.js";
+// The console origin serves /cli-auth (the browser target for `vincentt login`). VINCENTT_
+// CONSOLE_URL overrides for dev/dogfood; VINCENTT_EDITOR_URL is honored as a legacy alias.
+const DEFAULT_CONSOLE_URL = "https://vincentt.app";
 const DEFAULT_API_URL = "https://api.vincentt.studio";
 // ---- arg helpers ------------------------------------------------------------
 const argv = process.argv.slice(2);
@@ -37,20 +54,54 @@ function projectDir() {
     const dir = flag("--dir");
     return dir ? path.resolve(dir) : process.cwd();
 }
+/** The nth bare argument (`vincentt link <id>`), skipping flags and their values. */
+function positional(n) {
+    return positionalArgs(argv)[n];
+}
 // ---- auth -------------------------------------------------------------------
-async function login() {
-    const editorUrl = flag("--editor") ?? process.env.VINCENTT_EDITOR_URL ?? DEFAULT_EDITOR_URL;
+function resolveAuthUrls() {
+    const consoleUrl = flag("--console") ??
+        flag("--editor") ??
+        process.env.VINCENTT_CONSOLE_URL ??
+        process.env.VINCENTT_EDITOR_URL ??
+        DEFAULT_CONSOLE_URL;
     const apiUrl = flag("--api") ?? process.env.VINCENTT_API_URL ?? DEFAULT_API_URL;
-    const tokenName = flag("--name") ?? `Vincentt CLI (${os.hostname()})`;
-    console.log("Opening your browser to authorize this device…");
-    const { apiUrl: saved, configPath } = await runLogin({
-        editorUrl,
+    return { consoleUrl, apiUrl };
+}
+/** The PKCE loopback + code-exchange login (f1). The raw PAT never rides a redirect query. */
+async function runLoginFlow() {
+    const { consoleUrl, apiUrl } = resolveAuthUrls();
+    return runPkceLogin({
+        consoleUrl,
         apiUrl,
-        tokenName,
-        onUrl: (url) => console.log(`\nIf your browser didn't open, visit:\n  ${url}\n`),
+        onProgress: (line) => console.log(line),
     });
-    console.log(`\n✓ Signed in. Access token saved to ${configPath}`);
-    console.log(`  API: ${saved}`);
+}
+/** `vincentt login` [--force] — the L1/L2/L4 transcripts. */
+async function login() {
+    const { apiUrl } = resolveAuthUrls();
+    const code = await loginCommand({
+        print: (line) => console.log(line),
+        currentToken,
+        whoAmI: async () => {
+            const pat = await currentToken();
+            if (!pat)
+                return undefined;
+            try {
+                return await httpAuthBackend(apiUrl).me(pat);
+            }
+            catch {
+                return undefined;
+            }
+        },
+        runLogin: runLoginFlow,
+        clearToken: async () => {
+            await clearMachineToken();
+        },
+        home: os.homedir(),
+        configPath: MACHINE_CONFIG_PATH,
+    }, { force: has("--force") });
+    process.exitCode = code;
 }
 /** The token that would authenticate a machine call, if any (env wins over file). */
 async function currentToken() {
@@ -68,41 +119,47 @@ async function logout() {
     const { path: p, hadToken } = await clearMachineToken();
     console.log(hadToken ? `✓ Signed out. Token removed from ${p}` : "Already signed out.");
 }
+/**
+ * `whoami` reads the MACHINE config's API host, never the folder's binding — it
+ * answers "who am I", and reading the binding would make it answer a question
+ * about the folder instead.
+ */
 async function whoami() {
     const machine = await loadMachineConfig();
-    const apiUrl = process.env.VINCENTT_API_URL ?? machine.apiUrl ?? DEFAULT_API_URL;
-    const pat = process.env.VINCENTT_PAT ?? machine.pat;
-    if (!pat) {
-        console.log("Not signed in. Run `vincentt login`.");
-        process.exitCode = 1;
-        return;
-    }
-    const cfg = { apiUrl: apiUrl.replace(/\/$/, ""), pat };
-    try {
-        const me = await getMe(cfg);
-        const who = me.email ?? me.name ?? me.id ?? "(unknown account)";
-        console.log(`Signed in as ${who}`);
-        console.log(`  API: ${cfg.apiUrl}`);
-    }
-    catch (err) {
-        // Degrade: offline or a backend without /me still confirms a token is present.
-        console.log(`API: ${cfg.apiUrl}`);
-        console.log(`Token present but unverified (${err instanceof Error ? err.message : String(err)}).`);
-    }
+    process.exitCode = await whoamiCommand({
+        print: (l) => console.log(l),
+        config: async () => {
+            const apiUrl = process.env.VINCENTT_API_URL ?? machine.apiUrl ?? DEFAULT_API_URL;
+            const pat = process.env.VINCENTT_PAT ?? machine.pat;
+            if (!pat)
+                return undefined;
+            const cfg = { apiUrl: apiUrl.replace(/\/$/, ""), pat };
+            return cfg;
+        },
+        getMe,
+        org: {
+            flag: flag("--org"),
+            env: process.env.VINCENTT_ORG,
+            config: machine.activeOrg,
+        },
+    });
+}
+// ---- project ----------------------------------------------------------------
+async function init() {
+    process.exitCode = await initCommand({ print: (l) => console.log(l), cwd: process.cwd() }, { dir: positional(1), skipInstall: has("--no-install") });
 }
-// ---- dev loop ---------------------------------------------------------------
 async function create() {
     await requireLogin();
     const result = await projectCreate(projectDir(), {
         name: flag("--name"),
         slug: flag("--slug"),
-        scaffold: has("--no-scaffold") ? false : undefined,
+        org: flag("--org"),
         force: has("--force"),
-        onProgress: (m) => console.error(`  ${m}`),
+        allowCustomApi: has("--allow-custom-api"),
+        onLine: (l) => console.log(l),
     });
-    console.log(result.message);
-    if (result.alreadyBound) {
-        process.exitCode = 1;
+    if (result.exitCode !== 0) {
+        process.exitCode = result.exitCode;
         return;
     }
     // Chain straight into the dev loop when asked.
@@ -111,68 +168,301 @@ async function create() {
         await preview();
     }
 }
-async function unbind() {
-    const { path: p, hadBinding } = await clearProjectBinding(projectDir());
-    console.log(hadBinding ? `✓ Unbound. Removed ${p}` : "This directory has no project binding.");
-}
-async function publish() {
+async function link() {
     await requireLogin();
-    const result = await projectPublish(projectDir(), {
-        distDir: flag("--dist"),
-        note: flag("--note"),
+    const cwd = projectDir();
+    process.exitCode = await linkCommand({
+        print: (l) => console.log(l),
+        cwd,
+        config: () => resolveConfig(cwd, {
+            allowCustomApi: has("--allow-custom-api"),
+            warn: (l) => console.log(l),
+        }),
+    }, positional(1));
+}
+async function unlink() {
+    const cwd = projectDir();
+    process.exitCode = await unlinkCommand({
+        print: (l) => console.log(l),
+        cwd,
+        // unlink makes no server call, so this is never invoked.
+        config: () => resolveConfig(cwd),
     });
-    console.log(result.message);
-    if (result.notBound)
+}
+/**
+ * `vincentt publish` — Flows L22-L31.
+ *
+ * The whole gate lives here: the checklist, the permanence disclosure, the
+ * confirmation, the upload and the live URL. There is no browser step in
+ * publishing, not on the first publish, not ever.
+ */
+async function publish() {
+    const refused = refusedFlag(argv);
+    if (refused) {
+        console.log(`✗ There's no \`${refused}\` option.`);
+        console.log("");
+        console.log("  The link-preview check reports what it found; it never edits your");
+        console.log("  source. Fix the tags in your own files, rebuild, then publish again.");
         process.exitCode = 1;
+        return;
+    }
+    const cwd = projectDir();
+    process.exitCode = await publishCommand({
+        print: (l) => console.log(l),
+        write: (s) => process.stdout.write(s),
+        confirm: stdinConfirm(),
+        cwd,
+        config: () => resolveConfig(cwd, {
+            allowCustomApi: has("--allow-custom-api"),
+            warn: (l) => console.log(l),
+        }),
+        binding: async () => {
+            const located = await locateProjectBinding(cwd);
+            return located
+                ? { projectId: located.binding.projectId, slug: located.binding.slug }
+                : undefined;
+        },
+        token: currentToken,
+        isTTY: Boolean(process.stdout.isTTY) && Boolean(process.stdin.isTTY),
+        now: () => Date.now(),
+        sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+        orgName: activeOrgName,
+    }, { distDir: flag("--dist"), note: flag("--note"), yes: has("--yes") });
 }
+/** Flow L30 — the six verbs that are console actions, answered rather than rejected. */
+async function consoleOnly(verb) {
+    const cwd = projectDir();
+    process.exitCode = await consoleVerbCommand({
+        print: (l) => console.log(l),
+        projectId: async () => (await locateProjectBinding(cwd))?.binding.projectId,
+        consoleUrl: flag("--console") ?? process.env.VINCENTT_CONSOLE_URL,
+    }, verb);
+}
+/**
+ * `vincentt preview` — Flows L13-L21.
+ *
+ * The verb does something a creator could easily misread, so the FOLLOW path
+ * says what it is doing in its first line: in a folder with a live preview,
+ * `vincentt preview` ATTACHES to it and follows. It does not mint, does not
+ * print a QR, and does not supersede. A second preview for the same tree is
+ * created only when the working tree differs.
+ */
 async function preview() {
-    // `--stop` reaps a preview started by another process (e.g. a backgrounded run)
-    // via its pidfile — no need to hunt for the cloudflared pid by hand.
+    const cwd = projectDir();
     if (has("--stop")) {
-        const { message } = await previewStopSignal(projectDir());
+        const { message } = await previewStopSignal(cwd);
         console.log(message);
         return;
     }
-    await requireLogin();
-    const { preview: p, started } = await previewStart(projectDir(), (m) => console.error(`[preview] ${m}`));
-    if (!started) {
-        console.log(`A preview is already running:\n${p.url}`);
+    // The gate is LOCAL and NOTHING IS ATTEMPTED: no spinner, no partial mint, no
+    // session left in `pending`. The command stops before it touches the network.
+    if (!(await currentToken())) {
+        for (const l of notSignedIn())
+            console.log(l);
+        process.exitCode = 1;
+        return;
+    }
+    const filterViewer = flag("--viewer");
+    const filterTester = flag("--tester");
+    const color = Boolean(process.stdout.isTTY) && process.env.NO_COLOR === undefined;
+    const ui = new PreviewUi({
+        print: (l) => console.log(l),
+        now: () => Date.now(),
+        targetUrl: `http://localhost:${numFlag("--port") ?? 5173}`,
+        color,
+        filterTester,
+        filterViewer,
+    });
+    // A preview already running for this folder — in ANOTHER process — is
+    // FOLLOWED, not superseded. `vincentt preview` in a folder with a live
+    // preview attaches to it: it does not mint, does not print a QR, and does not
+    // take the link away from whoever is holding a phone.
+    //
+    // The marker is VALIDATED first. It only ever proved a preview was STARTED,
+    // and a crashed CLI, a kill -9 or a reboot all leave it behind — an unvalidated
+    // one short-circuited the mint into a dead end whose only cure was deleting a
+    // dotfile the creator does not know exists. A stale marker is cleared and
+    // treated as absent, which lands on the mint the creator actually asked for.
+    const existing = await readLivePreview(cwd);
+    if (existing !== undefined) {
+        await followPreview(existing, ui, filterTester, filterViewer);
         return;
     }
-    console.log("\nLive preview:");
-    console.log(`  Open on your phone:  ${p.url}`);
-    // A scannable QR in the terminal is unreliable across emulators, so hand back a
-    // desktop QR page to open and scan instead. Best-effort — a preview is still
-    // usable via the URL above if writing the page fails.
+    let ending = null;
+    let resolveDone;
+    const done = new Promise((r) => {
+        resolveDone = r;
+    });
+    let running;
     try {
-        const qrUrl = await writeQrPage(projectDir(), p.url);
-        console.log(`  Show QR (desktop):   ${qrUrl}`);
+        const started = await previewStart(cwd, (m) => console.error(`[preview] ${m}`), {
+            appPort: numFlag("--port"),
+            appStdio: has("--verbose") ? "inherit" : "ignore",
+            onViewer: (label, uaClass) => ui.viewerSeen(label, uaClass),
+            onViewerGone: (label) => ui.viewerGone(label),
+            onEvents: (events, tags) => ui.events(events, tags),
+            onCapReached: () => ui.capReached(),
+            onTunnelState: (state) => ui.tunnel(state),
+            onOriginError: () => ui.originError(),
+            onOriginRecovered: () => ui.originRecovered(),
+            onExpiring: () => ui.checkHardMax(running?.expiresAt ?? ""),
+            onEnded: (reason) => {
+                ending = reason;
+                resolveDone?.();
+            },
+        });
+        running = started.preview;
+        if (!started.started) {
+            // Already running IN THIS PROCESS. The mint path never reaches here.
+            console.log(`A preview is already running:\n${running.url}`);
+            return;
+        }
+    }
+    catch (err) {
+        for (const l of previewFailureLines(err))
+            console.log(l);
+        process.exitCode = 1;
+        return;
+    }
+    const qr = shouldRenderQr({
+        isTTY: Boolean(process.stdout.isTTY),
+        noQr: has("--no-qr"),
+        columns: process.stdout.columns,
+    })
+        ? await renderTerminalQr(running.url).catch(() => undefined)
+        : undefined;
+    for (const l of startBlock({
+        projectName: await projectDisplayName(cwd),
+        orgName: await activeOrgName(),
+        targetUrl: `http://localhost:${running.appPort}`,
+        url: running.url,
+        qr,
+        expiresInHours: 12,
+    })) {
+        console.log(l);
+    }
+    // The hard-max warning is checked on a slow tick rather than scheduled at a
+    // fixed offset: a laptop that slept through the scheduled instant would never
+    // fire a one-shot timer, and the 30-minute warning is the one the creator
+    // plans a demo around.
+    const ceiling = setInterval(() => ui.checkHardMax(running.expiresAt), 60_000);
+    ceiling.unref?.();
+    const stop = () => {
+        ui.stopping();
+        void previewStop().then(() => {
+            ui.stopped();
+            resolveDone?.();
+        });
+    };
+    process.on("SIGINT", stop);
+    process.on("SIGTERM", stop);
+    await done;
+    clearInterval(ceiling);
+    if (ending !== null) {
+        ui.endedBy(ending, (await activeOrgName()) || "your organization");
+        await previewStop();
+        process.exitCode = 1;
     }
-    catch {
-        /* non-fatal: the URL above is enough to preview */
+}
+/**
+ * Flow L16 — follow a preview running in another terminal.
+ *
+ * It says what it is doing in its FIRST line, because this is the one flow
+ * where the CLI's verb does something the creator could easily misread. It
+ * polls the relay rather than opening a second tunnel: a second tunnel would be
+ * a second session, which is the "two live URLs, one stale" the design forbids.
+ */
+async function followPreview(info, ui, filterTester, filterViewer) {
+    console.log("→ Attaching to the preview running in this folder");
+    const following = filterTester ?? filterViewer;
+    if (following !== undefined) {
+        console.log(`✓ Following ${following}`);
     }
-    console.log("\nDiagnostics: vincentt logs | network | trace");
-    console.log("Feedback:    vincentt feedback --wait");
-    console.log("\nStop: vincentt preview --stop (or Ctrl-C here).");
-    if (!p.appReady) {
-        console.log(`\nNote: the app on :${p.appPort} isn't responding yet — the URL may be blank until its build finishes.`);
+    else {
+        console.log("✓ Following this preview");
     }
-    // Keep the process alive until interrupted; reap the tunnel/dev-server on exit.
-    await new Promise((resolve) => {
-        const stop = async () => {
-            console.error("\nStopping preview…");
-            await previewStop();
-            resolve();
-        };
-        process.on("SIGINT", stop);
-        process.on("SIGTERM", stop);
+    console.log("");
+    const relay = httpRelayClient(`http://localhost:${info.relayPort}`);
+    let since = -1;
+    let warnedMissing = false;
+    let stop = false;
+    process.on("SIGINT", () => {
+        stop = true;
     });
+    while (!stop) {
+        try {
+            const result = await relay.query({ since, tester: filterTester, viewer: filterViewer });
+            // An unknown id is a FACT, not an error — and the remedy goes on the same
+            // line. Said once rather than on every poll, or a two-second loop becomes
+            // a wall of identical advisories.
+            if (!warnedMissing &&
+                filterTester !== undefined &&
+                result.testers.length > 0 &&
+                !result.testers.includes(filterTester)) {
+                warnedMissing = true;
+                console.log(`  ! No ${filterTester} on this preview right now. Connected: ${result.testers.join(", ")}.`);
+            }
+            // Both tags ride ALONGSIDE the events, index-parallel, so an unattributed
+            // event is dropped from the terminal rather than printed under an
+            // invented id that would read as a real tester.
+            result.events.forEach((e, i) => ui.events([e], { tester: result.eventTesters?.[i], viewer: result.eventViewers?.[i] }, { attribute: false }));
+            if (result.latestSeq > since)
+                since = result.latestSeq;
+        }
+        catch {
+            // The preview stopped, or its relay is gone. Either way the follower has
+            // nothing left to follow.
+            console.log("");
+            console.log("✓ The preview is no longer running.");
+            return;
+        }
+        await new Promise((r) => setTimeout(r, 1000));
+    }
+    console.log("");
+    console.log("  Ctrl-C to stop following. The preview keeps running.");
+}
+/**
+ * The org the creator is acting in, by the same precedence every other verb
+ * uses — flag, then env, then the machine config. Reading only the machine
+ * config would print a different org from the one the command acted in.
+ */
+async function activeOrgName() {
+    return (flag("--org") ??
+        process.env.VINCENTT_ORG ??
+        (await loadMachineConfig()).activeOrg ??
+        "");
+}
+/** The binding's name is a HINT for display only; the API is the authority. */
+async function projectDisplayName(cwd) {
+    const located = await locateProjectBinding(cwd);
+    return located?.binding.slug ?? path.basename(cwd);
+}
+/**
+ * Map a mint failure to its screen. Each cause has a DISTINCT first line so the
+ * creator never has to read a second, and none of them names the edge, the API
+ * or an outage — a creator cannot act on that.
+ */
+function previewFailureLines(err) {
+    if (err instanceof PreviewRateLimitedError)
+        return mintRateLimited(err.retryAfterSec);
+    if (err instanceof PreviewConflictError)
+        return previewConflict();
+    if (err instanceof ProjectUnreachableError) {
+        const out = [];
+        printUnreachable((l) => out.push(l), err.message);
+        return ["", ...out, ""];
+    }
+    return ["", `✗ ${err instanceof Error ? err.message : String(err)}`, ""];
 }
 // ---- diagnostics ------------------------------------------------------------
 async function diag(kind) {
     const cwd = projectDir();
+    // There is NO `--session`. It filtered on the raw client-supplied key, which
+    // made it the one surface that would teach a creator that key exists — and it
+    // was the same value the terminal was printing back. `--tester` replaces it.
     const opts = {
-        sessionId: flag("--session"),
+        tester: flag("--tester"),
+        viewer: flag("--viewer"),
         since: numFlag("--since"),
         limit: numFlag("--limit"),
         errorsOnly: has("--errors"),
@@ -227,31 +517,53 @@ async function relay() {
 function usage() {
     console.log(`Vincentt CLI — local-first AR dev loop\n\n` +
         `Usage: vincentt <command> [options]\n\n` +
+        `Getting started (building a new app with a coding agent)\n` +
+        `  1. Confirm a project name with the developer first.\n` +
+        `  2. Scaffold:  vincentt init <dir>     (no account needed)\n` +
+        `  3. Register:  vincentt create --name "<name>"\n` +
+        `  4. Read AGENTS.md, confirm it is ready, and stop — do NOT invent an app.\n` +
+        `     Wait for the developer to describe what to build.\n` +
+        `  Full guide: npm view @vincentt-xr/cli readme\n\n` +
         `Auth\n` +
         `  login              Sign in; save an access token to ~/.vincentt/config.json\n` +
         `  logout             Remove the saved access token\n` +
-        `  whoami             Show the signed-in account (via GET /network/me)\n\n` +
+        `  whoami             Show the signed-in account\n\n` +
+        `Project\n` +
+        `  init [dir]         Scaffold a Vincentt XR app — no account needed\n` +
+        `                       [--no-install]\n` +
+        `  create             Register a project and reserve its address\n` +
+        `                       [--name <s>] [--slug <s>] [--org <s>] [--preview] [--force]\n` +
+        `  link <project-id>  Link this folder to an existing project\n` +
+        `  unlink             Disconnect this folder from its project\n\n` +
         `Dev loop\n` +
-        `  create             Scaffold + bind a project (empty dir → full starter)\n` +
-        `                       [--name <s>] [--slug <s>] [--preview] [--force]\n` +
-        `  unbind             Detach this directory from its project\n` +
         `  publish            Upload the built dist; go live at <slug>.vincentt.app\n` +
-        `  preview            Serve + tunnel the app for on-device preview\n` +
-        `                       (prints a desktop QR page to scan) [--stop]\n\n` +
+        `                       [--dist <path>] [--note <s>] [--yes]\n` +
+        `  preview            Serve the app at an https link a phone can open\n` +
+        `                       [--port <n>] [--tester <id>] [--no-qr] [--stop]\n\n` +
         `Diagnostics (need a running preview)\n` +
-        `  logs [--errors]    Console logs from the device   [--json]\n` +
-        `  network            fetch/XHR requests              [--json]\n` +
-        `  trace              Performance samples             [--json]\n\n` +
+        `  logs [--errors]    Console logs from the device    [--json] [--tester <id>]\n` +
+        `  network            fetch/XHR requests              [--json] [--tester <id>]\n` +
+        `  trace              Performance samples             [--json] [--tester <id>]\n` +
+        `                       --tester t1 filters to one tester (one tab, across\n` +
+        `                       its refreshes). --viewer <label> filters to a single\n` +
+        `                       connection; one tab opens several.\n\n` +
         `Reverse channel\n` +
         `  feedback --wait    Block for the next phone annotation, print it, exit\n` +
         `  feedback --watch   Stream annotations as they arrive\n\n` +
         `Servers\n` +
         `  relay              Run the diagnostics/annotation relay\n` +
         `  mcp                Run the MCP adapter (for hosts without a shell)\n\n` +
-        `Common options: --dir <path> (project dir, default cwd)\n`);
+        `Common options: --dir <path> (project dir, default cwd)\n` +
+        `                --allow-custom-api  honor a binding's apiUrl override\n`);
 }
 async function main() {
     const cmd = argv[0];
+    // `--help`/`-h` anywhere means "explain, don't act" — never let it fall through to
+    // a verb. Otherwise `login --help` runs login, `create --help` scaffolds, etc.
+    if (isHelpInvocation(argv)) {
+        usage();
+        return;
+    }
     switch (cmd) {
         case "login":
             return login();
@@ -259,10 +571,14 @@ async function main() {
             return logout();
         case "whoami":
             return whoami();
+        case "init":
+            return init();
         case "create":
             return create();
-        case "unbind":
-            return unbind();
+        case "link":
+            return link();
+        case "unlink":
+            return unlink();
         case "publish":
             return publish();
         case "preview":
@@ -279,12 +595,12 @@ async function main() {
             return mcp();
         case "relay":
             return relay();
-        case undefined:
-        case "-h":
-        case "--help":
-            usage();
-            return;
         default:
+            // Flow L30: rolling back and taking an address offline are console
+            // actions, and a bare "unknown command" here would be the product failing
+            // to answer a question it knows the answer to.
+            if (cmd !== undefined && isConsoleOnlyVerb(cmd))
+                return consoleOnly(cmd);
             console.error(`Unknown command: ${cmd}\n`);
             usage();
             process.exitCode = 1;