zoodealio 0.2.0 → 0.3.0-dev.1603

package/README.md

@@ -2,8 +2,8 @@
 
 `zoodealio` is a command line wrapper over the partner API (`/openapi`). It prints JSON,
 takes JSON bodies, and describes itself, so people, scripts and AI agents can drive the
-same contract as the Zoodealio MCP server (`Mcp/OpenApiMcpTools.cs`) and the
-[Zapier app](../zapier/README.md). It adds no API surface: every command is one
+same contract as the Zoodealio MCP server and the Zoodealio Zapier app. It adds no API
+surface: every command is one
 documented `/openapi` request, and bodies pass through unchanged.
 
 It has no runtime dependencies and needs Node 22 or newer.
@@ -17,8 +17,7 @@ zoodealio whoami
 ```
 
 or run it without installing: `npx zoodealio whoami` (after a `zoodealio login` elsewhere, or with
-`ZOODEALIO_API_KEY` set). From a checkout of this repo, `node integrations/cli/bin/zoodealio.js`
-runs the working copy.
+`ZOODEALIO_API_KEY` set).
 
 ## Authenticate
 
@@ -31,15 +30,19 @@ zoodealio login --name work-laptop   # device name shown at sign-in (default: th
 zoodealio logout           # revokes this machine's key and forgets it
 ```
 
-`login` binds a loopback port, sends you to Zoodealio AI to approve, and exchanges the one-time
-code (with PKCE) for a personal API key named `CLI – <device>`. It waits up to 5 minutes. It prints
-`{ok, email, name, keyPrefix, origin}` and never the key.
+`login` opens your browser on the sign-in page, explains the steps and prints the link. In a
+terminal, press **Enter** to open it again, **c** to copy the link, or **q** to cancel; the link also
+works pasted into any browser, on this or another device. Sign in the way you usually do and click **Authorize**; the terminal
+finishes by itself and suggests what to run next. Run by a script or an agent (no terminal), it
+opens the browser the same way and prints the link, without the key prompt. All of this goes to stderr.
+
+Under the hood it binds a loopback port, sends you to Zoodealio AI to approve, and exchanges the
+one-time code (with PKCE) for a personal API key named `CLI – <device>`. It waits up to 5 minutes.
+It prints `{ok, email, name, keyPrefix, origin}` on stdout and never the key.
 
 The key is stored per API origin in `$XDG_CONFIG_HOME/zoodealio/credentials.json`
 (default `~/.config/zoodealio/credentials.json`; `%APPDATA%\zoodealio\credentials.json` on Windows),
-written atomically with mode `0600` in a `0700` directory. Keys are per environment:
-`zoodealio login --env dev` stores a separate login. `ZOODEALIO_WEB_URL` overrides the sign-in
-page origin the way `ZOODEALIO_API_URL` overrides the API origin.
+written atomically with mode `0600` in a `0700` directory.
 
 ### API key for CI and servers
 
@@ -90,17 +93,6 @@ Cursor (`.cursor/mcp.json`) or VS Code (`.vscode/mcp.json`, under `servers`):
 Run `zoodealio login` first (or put `ZOODEALIO_API_KEY` in the client's `env`). Stdout carries only
 JSON-RPC; logs go to stderr.
 
-## Environments
-
-| Selection | API origin |
-| --- | --- |
-| default | `https://api.zoodealio.ai` |
-| `--env dev` | `https://dev.api.zoodealio.ai` |
-| `ZOODEALIO_API_URL=http://localhost:5256` | that origin (overrides both) |
-
-Keys are per environment. Use a local API URL only for a local API; the port above is an
-example, use whichever yours runs on.
-
 ## Output and errors
 
 stdout carries JSON and nothing else: pretty-printed on a terminal, compact when piped
@@ -132,7 +124,6 @@ Route IDs are GUIDs and are checked before any request is made.
 
 | Flag | Effect |
 | --- | --- |
-| `--env prod\|dev` | Pick the environment (default `prod`) |
 | `--pretty` | Pretty-print JSON even when piped |
 | `--dry-run` | Print `{method, url, headers, body}` with the key redacted and send nothing; works without a key |
 | `--yes` | Confirm a destructive command (not needed with `--dry-run`) |
@@ -151,7 +142,7 @@ concurrency on `properties update`, `offers accept` and `offers request-details`
 | --- | --- | --- |
 | `properties list` | GET Properties | `--search`, `--state` |
 | `properties get <id>` | GET Properties/{id} | |
-| `properties create` | POST Properties | `--body` |
+| `properties create` | POST Properties | `--body`; `--agent <id>` assigns a team member or a pending invite |
 | `properties update <id>` | PUT Properties/{id} | `--body`, `--if-match`; replaces wholesale |
 | `properties photos list\|add\|delete` | photos | `add`: `--url` (repeatable) or `--body`; `delete <id> <photoId>` needs `--yes` |
 | `properties documents list\|add\|delete` | documents | same shape as photos |
@@ -163,7 +154,7 @@ concurrency on `properties update`, `offers accept` and `offers request-details`
 | `transactions get <id>` | GET Transactions/{id} | |
 | `transactions active` | GET Transactions/active | `--property` required |
 | `comping status <transactionId>` | GET Transactions/{id}/comping | |
-| `team members`, `team get <id>`, `teams list` | GET Team | `--search` |
+| `team members`, `team get <id>`, `teams list` | GET Team | `--search`; `team members` also lists pending invites (`kind: "invite"`) |
 | `team invite` | POST Team/members | `--email` (+ `--first-name`, `--last-name`, `--team`, `--admin-team`) or `--body` |
 | `team remove <id>` | DELETE Team/members/{id} | `--yes` required |
 | `webhooks event-types\|list\|deliveries` | GET Webhooks | `deliveries`: `--subscription`, `--status` |
@@ -225,8 +216,8 @@ zoodealio api GET Properties --query pageSize=5
   destructive action (accepting an offer, removing a member, deleting or rotating a
   webhook); do not add it to make an error go away.
 - For request body shapes run `zoodealio openapi`, which prints the partner OpenAPI document.
-- Prefer webhooks, or polling `comping status` and `import-status`, to long waits. See
-  [OPEN_API_WEBHOOKS.md](../../docs/OPEN_API_WEBHOOKS.md) for events, signatures and delivery.
+- Prefer webhooks, or polling `comping status` and `import-status`, to long waits. The
+  [developer docs](https://zoodealio.ai/developers#webhooks) cover events, signatures and delivery.
 
 ## Limits
 
@@ -235,25 +226,3 @@ zoodealio api GET Properties --query pageSize=5
 - No keychain or interactive prompts. Credentials are `ZOODEALIO_API_KEY` or the
   `credentials.json` written by `zoodealio login`.
 
-## Development
-
-```sh
-cd integrations/cli
-npm install
-npm run check   # eslint, tsc --noEmit (checkJs), node --test
-```
-
-## Releasing
-
-npm no longer lets a token that bypasses 2FA publish directly, so releases are staged and then
-approved by a maintainer with 2FA:
-
-```sh
-cd integrations/cli
-npm version <patch|minor|major> --no-git-tag-version   # in a PR, then merge
-npm run check
-npm stage publish --userconfig ~/.config/zoodealio/npm-publish.npmrc
-```
-
-Then approve it on npmjs.com (avatar → Staged Packages → Approve). A version with a `-` suffix
-(`0.2.0-beta.1`) is staged with `--tag next` so `latest` stays stable.

package/bin/zoodealio.js

@@ -1,11 +1,34 @@
 #!/usr/bin/env node
 const { run } = require('../src/cli');
 
+/**
+ * Single keypresses from the terminal while `login` waits; the returned function hands the terminal back.
+ * @param {(key: string) => void} handler
+ */
+function onKey(handler) {
+    const stdin = process.stdin;
+    stdin.setRawMode(true);
+    stdin.setEncoding('utf8');
+    stdin.resume();
+    const listener = (/** @type {string} */ data) => {
+        for (const key of data) handler(key);
+    };
+    stdin.on('data', listener);
+    return () => {
+        stdin.off('data', listener);
+        stdin.setRawMode(false);
+        stdin.pause();
+    };
+}
+
 run(process.argv.slice(2), {
     env: process.env,
     stdout: process.stdout,
     stderr: process.stderr,
     stdin: process.stdin,
+    // Someone is at a terminal: prompt for keys. Agents and scripts never get a prompt.
+    interactive: !!process.stdin.isTTY && !!process.stderr.isTTY,
+    onKey,
 }).then((code) => {
     process.exitCode = code;
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zoodealio",
-  "version": "0.2.0",
+  "version": "0.3.0-dev.1603",
   "description": "Zoodealio command line tool: the partner API as JSON, built for people, scripts and AI agents",
   "license": "UNLICENSED",
   "repository": {

package/src/args.js

@@ -29,7 +29,7 @@ function parse(argv) {
     }
     const { values, positionals } = parsed;
     if (values.help) return { help: helpText(positionals) };
-    if (positionals.length === 0) throw usage('missing command; run `zoodealio --help`');
+    if (positionals.length === 0) return { help: helpText([]) };
 
     let command;
     for (const c of COMMANDS) {

package/src/cli.js

@@ -2,15 +2,17 @@ const { CliError, usage } = require('./errors');
 const { parse, normalizeApiPath, METHODS } = require('./args');
 const { catalogue } = require('./commands');
 const { resolveBody } = require('./input');
-const { USER_AGENT, redactKey, scrubKeys, resolveOrigin, buildUrl, send } = require('./http');
+const { DEFAULT_ENV, USER_AGENT, redactKey, scrubKeys, resolveOrigin, buildUrl, send } = require('./http');
 const { readCredential, saveCredential, removeCredential } = require('./credentials');
 const { browserLogin, resolveWebOrigin, defaultDevice } = require('./login');
 const { bridge } = require('./mcp');
+const { createUi } = require('./ui');
 
 /**
  * @typedef {{env: Record<string, string | undefined>, stdout: {write(s: string): unknown, isTTY?: boolean},
  *   stderr: {write(s: string): unknown}, stdin: AsyncIterable<string | Buffer>, fetch?: typeof fetch,
- *   openBrowser?: (url: string) => Promise<void>, loginTimeoutMs?: number}} Io
+ *   openBrowser?: (url: string) => Promise<void>, copy?: (text: string) => Promise<void>, loginTimeoutMs?: number,
+ *   interactive?: boolean, onKey?: (handler: (key: string) => void) => () => void}} Io
  */
 
 /**
@@ -55,7 +57,8 @@ async function execute(argv, io, envKey, secrets) {
 
     if (command.name === 'commands') return emit(catalogue());
 
-    const origin = resolveOrigin(io.env, flags.env);
+    const envName = flags.env || DEFAULT_ENV;
+    const origin = resolveOrigin(io.env, envName);
     const stored = readCredential(io.env, origin);
     if (stored) secrets.add(stored.key);
     const source = envKey ? 'env' : stored ? 'login' : undefined;
@@ -64,12 +67,35 @@ async function execute(argv, io, envKey, secrets) {
     if (['login', 'logout', 'mcp'].includes(command.name)) {
         if (flags['dry-run']) throw usage(`--dry-run is not supported for \`${command.name}\``);
         if (command.name === 'login') {
+            const ui = createUi(io.stderr, { fancy: !!io.interactive && !io.env.NO_COLOR });
             const result = await browserLogin({
-                apiOrigin: origin, webOrigin: resolveWebOrigin(io.env, flags.env), device: (flags.name?.trim() || defaultDevice()).slice(0, 64),
-                noBrowser: !!flags['no-browser'], openBrowser: io.openBrowser, timeoutMs: io.loginTimeoutMs, stderr: io.stderr, fetch: io.fetch,
+                apiOrigin: origin, webOrigin: resolveWebOrigin(io.env, envName), device: (flags.name?.trim() || defaultDevice()).slice(0, 64),
+                envName, noBrowser: !!flags['no-browser'], openBrowser: io.openBrowser, copy: io.copy,
+                interactive: io.interactive, onKey: io.onKey, timeoutMs: io.loginTimeoutMs, ui, fetch: io.fetch,
             });
             secrets.add(result.key);
-            saveCredential(io.env, origin, { key: result.key, keyId: result.keyId, email: result.email, name: result.name });
+            const file = saveCredential(io.env, origin, { key: result.key, keyId: result.keyId, email: result.email, name: result.name });
+            // The hints run without --env only where that reaches the environment just signed in to.
+            const dev = envName === DEFAULT_ENV ? '' : ` --env ${envName}`;
+            const home = io.env.HOME || io.env.USERPROFILE;
+            const where = home && file.startsWith(home) ? `~${file.slice(home.length)}` : file;
+            const { style } = ui;
+            const next = [
+                [`zoodealio whoami${dev}`, 'check who you\'re signed in as'],
+                [`zoodealio properties list${dev}`, 'your first call'],
+                [`zoodealio mcp --help`, 'connect an AI client'],
+                ['zoodealio logout', 'sign this computer out'],
+            ];
+            const width = Math.max(...next.map(([c]) => c.length)) + 3;
+            ui.say();
+            ui.say(`${style.green('✓')} Signed in as ${style.bold(result.email)}${envName === 'prod' ? '' : ` ${style.dim(`(${envName})`)}`}`);
+            ui.say(`  ${style.dim(`Key "${result.name}" saved to ${where}`)}`);
+            ui.say();
+            ui.say(`  ${style.bold('Next')}`);
+            for (const [cmd, what] of next) ui.say(`    ${cmd.padEnd(width)}${style.dim(what)}`);
+            ui.say();
+            // A person at a terminal has just read all that; the JSON is for scripts and agents.
+            if (io.interactive && io.stdout.isTTY) return;
             return emit({ ok: true, email: result.email, name: result.name, keyPrefix: result.keyPrefix, origin });
         }
         if (command.name === 'logout') {
@@ -124,6 +150,11 @@ async function execute(argv, io, envKey, secrets) {
     if (flags.body !== undefined) {
         if ((command.convenience || []).some((n) => flags[n] !== undefined)) throw usage('use either --body or the convenience flags, not both');
         body = await resolveBody(flags.body, io.stdin);
+        const extra = command.overlay && command.overlay(flags);
+        if (extra && Object.keys(extra).length) {
+            if (typeof body !== 'object' || body === null || Array.isArray(body)) throw usage('--body must be a JSON object when combined with convenience flags');
+            body = { ...body, ...extra };
+        }
     } else if (command.build) {
         body = command.build(flags);
         if (body === undefined && command.body === 'required') throw usage('provide --body or the convenience flags');

package/src/commands.js

@@ -7,7 +7,7 @@ const { parseJsonArg } = require('./input');
  * @typedef {{name: string, description: string, guid?: boolean}} Arg
  * @typedef {{name: string, summary: string, method: string | null, path: string | null, args: Arg[],
  *   flags: Flag[], body?: 'required' | 'optional', convenience?: string[], destructive?: boolean,
- *   auth?: boolean, build?: (flags: Record<string, any>) => unknown}} Command
+ *   auth?: boolean, build?: (flags: Record<string, any>) => unknown, overlay?: (flags: Record<string, any>) => Record<string, unknown>, notes?: string[]}} Command
  */
 
 /**
@@ -50,7 +50,14 @@ const COMMANDS = [
         flags: [str('search', 'Free-text search', { query: 'search' }), str('state', 'Two-letter state code', { query: 'stateCode' }), ...PAGING],
     }),
     cmd('properties get', 'Get one property', 'GET', '/openapi/Properties/{id}', { args: [id('id', 'Property id')] }),
-    cmd('properties create', 'Create a property', 'POST', '/openapi/Properties', { body: 'required', flags: [BODY] }),
+    cmd('properties create', 'Create a property', 'POST', '/openapi/Properties', {
+        body: 'required',
+        flags: [str('agent', 'Agent to assign: a team member id, or a pending invite id from `team members`'), BODY],
+        overlay: (f) => {
+            if (f.agent !== undefined && !GUID.test(f.agent)) throw usage(`agent id is not a GUID: ${f.agent}`);
+            return compact({ agentId: f.agent });
+        },
+    }),
     cmd('properties update', 'Replace a property (wholesale)', 'PUT', '/openapi/Properties/{id}', {
         args: [id('id', 'Property id')], body: 'required', flags: [BODY, IF_MATCH],
     }),
@@ -95,7 +102,7 @@ const COMMANDS = [
     cmd('comping status', 'Get AI comping status for a transaction', 'GET', '/openapi/Transactions/{transactionId}/comping', {
         args: [id('transactionId', 'Transaction id')],
     }),
-    cmd('team members', 'List team members', 'GET', '/openapi/Team/members', {
+    cmd('team members', 'List team members, including pending invites', 'GET', '/openapi/Team/members', {
         flags: [str('search', 'Free-text search', { query: 'search' }), ...PAGING],
     }),
     cmd('team get', 'Get one team member', 'GET', '/openapi/Team/members/{id}', { args: [id('id', 'Member id')] }),
@@ -137,6 +144,14 @@ const COMMANDS = [
     }),
     cmd('login', 'Sign in through the browser and store a CLI key', null, null, {
         auth: false,
+        notes: [
+            'Opens the Zoodealio sign-in page in your browser. Sign in the way you usually do and click',
+            'Authorize; this terminal then finishes by itself. In a terminal, press Enter to open it',
+            'again, c to copy the link, or q to cancel. The link is always printed too, for when no browser',
+            'can be opened (SSH, containers: use --no-browser and open it on another device).',
+            'The key is saved for this computer; zoodealio logout removes it.',
+            'On CI or a server, set ZOODEALIO_API_KEY instead.',
+        ],
         flags: [
             { name: 'no-browser', type: 'boolean', description: 'Print the sign-in URL to stderr instead of opening a browser' },
             str('name', 'Device name shown at sign-in (default: this host)'),
@@ -149,7 +164,15 @@ const COMMANDS = [
         build: (f) => ({ name: f.name }),
     }),
     cmd('keys revoke', 'Revoke an API key', 'DELETE', '/openapi/Keys/{id}', { args: [id('id', 'Key id')], destructive: true }),
-    cmd('mcp', 'Run a stdio MCP server bridged to /openapi/mcp', 'POST', '/openapi/mcp'),
+    cmd('mcp', 'Run a stdio MCP server bridged to /openapi/mcp', 'POST', '/openapi/mcp', {
+        notes: [
+            'Uses your zoodealio login (or ZOODEALIO_API_KEY). Add it to an AI client:',
+            '  Claude Code:        claude mcp add --scope user zoodealio -- zoodealio mcp',
+            '  Claude Desktop,',
+            '  Cursor, VS Code:    {"command": "zoodealio", "args": ["mcp"]}',
+            'Add --env dev to the args for the dev environment.',
+        ],
+    }),
     cmd('whoami', 'Check the API key and show the target origin', 'GET', '/openapi/Webhooks/event-types'),
     cmd('openapi', 'Print the partner OpenAPI document (no key needed)', 'GET', '/_openapi/partner.json', { auth: false }),
     cmd('api', 'Call any /openapi endpoint directly (DELETE needs --yes)', null, null, {
@@ -163,7 +186,7 @@ const GUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
 /** Flags accepted by every command. */
 const GLOBAL_FLAGS = /** @type {Flag[]} */ ([
-    str('env', 'prod (default) or dev; ZOODEALIO_API_URL overrides'),
+    str('env', 'prod or dev (default prod; dev on a dev build); ZOODEALIO_API_URL overrides'),
     { name: 'pretty', type: 'boolean', description: 'Pretty-print JSON even when piped' },
     { name: 'dry-run', type: 'boolean', description: 'Print the request (key redacted) without sending it' },
     { name: 'yes', type: 'boolean', description: 'Confirm a destructive command (not needed with --dry-run)' },
@@ -208,8 +231,21 @@ function helpText(prefix) {
         if (exact.destructive) lines.push('Destructive: requires --yes.');
         for (const a of exact.args) lines.push(`  <${a.name}>  ${a.description}`);
         for (const f of exact.flags) lines.push(`  --${f.name}  ${f.description}${f.required ? ' (required)' : ''}`);
+        if (exact.notes) lines.push('', ...exact.notes);
     } else {
         lines.push('zoodealio <command> [args] [flags]', '', 'JSON on stdout; errors as JSON on stderr. Sign in with `zoodealio login` or set ZOODEALIO_API_KEY.', '');
+        if (prefix.length === 0) {
+            lines.push(
+                'Get started:',
+                '  zoodealio login             Sign in through your browser',
+                '  zoodealio whoami            Check who you\'re signed in as',
+                '  zoodealio properties list   Your first call',
+                '  zoodealio mcp --help        Connect an AI client (Claude, Cursor, VS Code)',
+                '  zoodealio commands          Every command as JSON, for AI agents',
+                '',
+                'Commands:',
+            );
+        }
         for (const c of matches) lines.push(`  ${c.name.padEnd(28)}${c.summary}`);
         lines.push('', 'Global flags:');
         for (const f of GLOBAL_FLAGS) lines.push(`  --${f.name.padEnd(10)}${f.description}`);

package/src/credentials.js

@@ -69,9 +69,11 @@ function writeAll(env, all) {
  * @param {Record<string, string | undefined>} env
  * @param {string} origin
  * @param {Credential} credential
+ * @returns {string} the credentials file
  */
 function saveCredential(env, origin, credential) {
     writeAll(env, { ...readAll(env, true), [origin]: credential });
+    return path.join(configDir(env), 'credentials.json');
 }
 
 /**

package/src/http.js

@@ -4,6 +4,18 @@ const pkg = require('../package.json');
 const USER_AGENT = `zoodealio-cli/${pkg.version}`;
 const ENVS = { prod: 'https://api.zoodealio.ai', dev: 'https://dev.api.zoodealio.ai' };
 
+/**
+ * CI publishes `<version>-dev.<run>` under the `dev` tag after the dev deployment, so that build
+ * talks to dev unless told otherwise. Every other version is a release and talks to prod.
+ * @param {string} version
+ * @returns {'prod'|'dev'}
+ */
+function defaultEnv(version) {
+    return version.includes('-dev.') ? 'dev' : 'prod';
+}
+
+const DEFAULT_ENV = defaultEnv(pkg.version);
+
 /** @type {Record<number, [number, string]>} status -> [exit code, error code slug] */
 const STATUS_MAP = {
     400: [2, 'bad_request'],
@@ -47,7 +59,7 @@ function scrubKeys(text, keys) {
 function resolveOrigin(env, envName) {
     const override = env.ZOODEALIO_API_URL;
     if (override) return override.replace(/\/+$/, '');
-    const name = envName || 'prod';
+    const name = envName || DEFAULT_ENV;
     if (!Object.hasOwn(ENVS, name)) throw usage('--env must be prod or dev');
     return ENVS[/** @type {'prod'|'dev'} */ (name)];
 }
@@ -123,4 +135,4 @@ async function send(doFetch, req) {
     }
 }
 
-module.exports = { ENVS, USER_AGENT, redactKey, scrubKeys, resolveOrigin, buildUrl, send };
+module.exports = { ENVS, DEFAULT_ENV, USER_AGENT, defaultEnv, redactKey, scrubKeys, resolveOrigin, buildUrl, send };

package/src/login.js

@@ -3,7 +3,7 @@ const http = require('node:http');
 const os = require('node:os');
 const { spawn } = require('node:child_process');
 const { CliError } = require('./errors');
-const { USER_AGENT, send } = require('./http');
+const { DEFAULT_ENV, USER_AGENT, send } = require('./http');
 
 const WEB_ENVS = { prod: 'https://zoodealio.ai', dev: 'https://dev.zoodealio.ai' };
 const LOGIN_TIMEOUT_MS = 5 * 60 * 1000;
@@ -15,7 +15,7 @@ const LOGIN_TIMEOUT_MS = 5 * 60 * 1000;
  */
 function resolveWebOrigin(env, envName) {
     if (env.ZOODEALIO_WEB_URL) return env.ZOODEALIO_WEB_URL.replace(/\/+$/, '');
-    return WEB_ENVS[/** @type {'prod'|'dev'} */ (envName === 'dev' ? 'dev' : 'prod')];
+    return WEB_ENVS[/** @type {'prod'|'dev'} */ ((envName || DEFAULT_ENV) === 'dev' ? 'dev' : 'prod')];
 }
 
 /**
@@ -37,6 +37,27 @@ function openBrowser(url) {
     });
 }
 
+/**
+ * Puts text on the system clipboard with the first tool this machine has. Rejects when none works.
+ * @param {string} text
+ * @returns {Promise<void>}
+ */
+async function copyToClipboard(text) {
+    const tools = process.platform === 'darwin' ? [['pbcopy', []]]
+        : process.platform === 'win32' ? [['clip', []]]
+            : [['wl-copy', []], ['xclip', ['-selection', 'clipboard']], ['xsel', ['--clipboard', '--input']]];
+    for (const [command, args] of /** @type {[string, string[]][]} */ (tools)) {
+        const ok = await new Promise((resolve) => {
+            const child = spawn(command, args, { stdio: ['pipe', 'ignore', 'ignore'] });
+            child.once('error', () => resolve(false));
+            child.once('close', (code) => resolve(code === 0));
+            child.stdin.end(text);
+        });
+        if (ok) return;
+    }
+    throw new Error('no clipboard tool');
+}
+
 const PAGE = (/** @type {string} */ message) => `<!doctype html><meta charset="utf-8"><title>Zoodealio CLI</title><body style="font-family:system-ui;text-align:center;margin-top:4rem"><h1>${message}</h1><p>You can close this tab and return to your terminal.</p>`;
 
 /**
@@ -89,8 +110,13 @@ async function listenForCallback(state, timeoutMs) {
 
 /**
  * Browser sign-in (authorization code + PKCE). Returns the exchange response; the caller stores it.
- * @param {{apiOrigin: string, webOrigin: string, device: string, noBrowser: boolean,
- *   openBrowser?: (url: string) => Promise<void>, timeoutMs?: number, stderr: {write(s: string): unknown}, fetch?: typeof fetch}} opts
+ * Everything it says goes to stderr, so stdout stays JSON. In a terminal someone is typing in
+ * (`interactive` with `onKey`), Enter opens the browser, c copies the link and q cancels; otherwise the
+ * browser opens straight away. The link is always printed, in case no browser can be opened.
+ * @param {{apiOrigin: string, webOrigin: string, device: string, envName: string, noBrowser: boolean,
+ *   openBrowser?: (url: string) => Promise<void>, copy?: (text: string) => Promise<void>,
+ *   interactive?: boolean, onKey?: (handler: (key: string) => void) => () => void,
+ *   timeoutMs?: number, ui: ReturnType<typeof import('./ui').createUi>, fetch?: typeof fetch}} opts
  * @returns {Promise<{key: string, keyId: string, keyPrefix: string, name: string, email: string}>}
  */
 async function browserLogin(opts) {
@@ -100,31 +126,81 @@ async function browserLogin(opts) {
     const listener = await listenForCallback(state, opts.timeoutMs ?? LOGIN_TIMEOUT_MS);
     try {
         const url = `${opts.webOrigin}/cli/login?${new URLSearchParams({ port: String(listener.port), state, challenge, device: opts.device })}`;
-        let opened = false;
-        if (!opts.noBrowser) {
+        const { ui } = opts;
+        const { style } = ui;
+        const minutes = Math.max(1, Math.round((opts.timeoutMs ?? LOGIN_TIMEOUT_MS) / 60000));
+        const open = async () => {
             try {
                 await (opts.openBrowser || openBrowser)(url);
-                opened = true;
+                ui.say(`  ${style.dim('Opened your browser. Nothing there? Use the link above, or press Enter.')}`);
             } catch {
-                // fall through to printing the URL
+                ui.say(`  ${style.red('Couldn\'t open a browser.')} Copy the link above into one.`);
             }
+        };
+        const prompting = !opts.noBrowser && !!opts.interactive && !!opts.onKey;
+
+        ui.say();
+        ui.say(`  ${style.bold(`Sign in to Zoodealio${opts.envName === 'prod' ? '' : ` (${opts.envName})`}`)}`);
+        ui.say();
+        ui.say(opts.noBrowser ? '  1. Open the link below in a browser, on this or any device.'
+            : '  1. Your browser opens the sign-in page. If it doesn\'t, use the link below.');
+        ui.say(`  2. Sign in the way you usually do, then click ${style.bold('Authorize')} for "${opts.device}".`);
+        ui.say('  3. Come back here. This finishes by itself.');
+        ui.say();
+        ui.say(`  ${style.dim('Link:')} ${style.link(url)}`);
+        if (prompting) ui.say(`  ${style.dim('Press Enter to open it again · c to copy the link · q to cancel')}`);
+        ui.say();
+
+        /** @type {() => void} */
+        let stopKeys = () => {};
+        /** @type {Promise<{code?: string, error?: string}>} */
+        let cancelled = new Promise(() => {});
+        if (!opts.noBrowser) await open();
+        if (prompting) {
+            cancelled = new Promise((resolve) => {
+                stopKeys = /** @type {(handler: (key: string) => void) => () => void} */ (opts.onKey)((key) => {
+                    if (key === '\r' || key === '\n') {
+                        void open();
+                    } else if (key === 'c' || key === 'C') {
+                        (opts.copy || copyToClipboard)(url).then(
+                            () => ui.say(`  ${style.green('✓')} Link copied. Paste it into your browser.`),
+                            () => ui.say(`  ${style.red('Couldn\'t reach the clipboard.')} Select the link above to copy it.`),
+                        );
+                    } else if (key === 'q' || key === 'Q' || key === '\u0003') {
+                        resolve({ error: 'cancelled' });
+                    }
+                });
+            });
         }
-        if (!opened) opts.stderr.write(`Open this URL in a browser to sign in:\n${url}\n`);
+        ui.spin(`Waiting for you to authorize in the browser… ${style.dim(`(the link works for ${minutes} minute${minutes === 1 ? '' : 's'})`)}`);
 
-        const { code, error } = await listener.result;
+        let result;
+        try {
+            result = await Promise.race([listener.result, cancelled]);
+        } finally {
+            stopKeys();
+            ui.done();
+        }
+        const { code, error } = result;
         if (!code) {
             throw new CliError({
                 exit: 1, code: error === 'cancelled' ? 'login_cancelled' : 'login_failed',
                 title: error === 'cancelled' ? 'Login cancelled' : 'Login failed',
-                detail: error === 'cancelled' ? 'Sign-in was cancelled in the browser.' : `The browser reported: ${error}`,
+                detail: error === 'cancelled' ? 'Sign-in was cancelled.' : `The browser reported: ${error}`,
             });
         }
-        return /** @type {any} */ (await send(opts.fetch || fetch, {
-            method: 'POST',
-            url: `${opts.apiOrigin}/openapi/cli-logins/exchange`,
-            headers: { Accept: 'application/json', 'Content-Type': 'application/json', 'User-Agent': USER_AGENT },
-            body: { code, verifier },
-        }));
+        ui.say(`${ui.style.green('✓')} Authorized in the browser`);
+        ui.spin('Finishing sign-in…');
+        try {
+            return /** @type {any} */ (await send(opts.fetch || fetch, {
+                method: 'POST',
+                url: `${opts.apiOrigin}/openapi/cli-logins/exchange`,
+                headers: { Accept: 'application/json', 'Content-Type': 'application/json', 'User-Agent': USER_AGENT },
+                body: { code, verifier },
+            }));
+        } finally {
+            ui.done();
+        }
     } finally {
         listener.close();
     }

package/src/ui.js

@@ -0,0 +1,59 @@
+/**
+ * What a person sees on stderr while `login` runs. In a terminal it has color and a spinner; for
+ * agents, scripts and NO_COLOR it is the same text, plain, one line per message.
+ */
+
+const FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+
+/**
+ * @param {{write(s: string): unknown}} stream
+ * @param {{fancy: boolean}} options fancy = an interactive terminal that allows color
+ */
+function createUi(stream, { fancy }) {
+    /** @param {string} code @returns {(s: string) => string} */
+    const paint = (code) => (s) => (fancy ? `\u001b[${code}m${s}\u001b[0m` : s);
+    const style = { bold: paint('1'), dim: paint('2'), green: paint('32'), cyan: paint('36'), red: paint('31'), link: paint('4;36') };
+
+    /** @type {{text: string, timer: NodeJS.Timeout, frame: number} | null} */
+    let spinner = null;
+    const draw = () => {
+        if (!spinner) return;
+        stream.write(`\r\u001b[2K${style.cyan(FRAMES[spinner.frame % FRAMES.length])} ${spinner.text}`);
+        spinner.frame++;
+    };
+    const clear = () => {
+        if (spinner) stream.write('\r\u001b[2K');
+    };
+
+    /** Prints a line, keeping any spinner on the line below it. @param {string} [line] */
+    const say = (line = '') => {
+        clear();
+        stream.write(`${line}\n`);
+        draw();
+    };
+
+    return {
+        style,
+        say,
+        /** @param {string} text */
+        spin(text) {
+            if (!fancy) {
+                stream.write(`${text}\n`);
+                return;
+            }
+            spinner = { text, frame: 0, timer: setInterval(draw, 80) };
+            draw();
+        },
+        /** Stops the spinner, replacing it with a final line. @param {string} [line] */
+        done(line) {
+            if (spinner) {
+                clearInterval(spinner.timer);
+                clear();
+                spinner = null;
+            }
+            if (line) stream.write(`${line}\n`);
+        },
+    };
+}
+
+module.exports = { createUi };