zoodealio 0.1.0 → 0.2.1

package/README.md

@@ -2,30 +2,52 @@
 
 `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.
 
 ## Install
 
-Run it without installing:
-
 ```sh
-npx zoodealio whoami
+npm install -g zoodealio
+zoodealio login
+zoodealio whoami
 ```
 
-or install it globally:
+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.
+
+## Authenticate
+
+### Sign in (the default)
 
 ```sh
-npm install -g zoodealio
-zoodealio whoami
+zoodealio login            # opens your browser; approve "Sign in Zoodealio CLI on <device>"
+zoodealio login --no-browser   # print the URL to stderr instead (SSH, containers)
+zoodealio login --name work-laptop   # device name shown at sign-in (default: this host)
+zoodealio logout           # revokes this machine's key and forgets it
 ```
 
-From a checkout of this repo, `node integrations/cli/bin/zoodealio.js` runs the working copy.
+`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.
 
-## Authenticate
+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.
+
+### API key for CI and servers
 
 Copy a personal API key from **Settings → API** in Zoodealio AI and export it:
 
@@ -33,12 +55,46 @@ Copy a personal API key from **Settings → API** in Zoodealio AI and export it:
 export ZOODEALIO_API_KEY=zoo_...
 ```
 
-The key is read only from this variable and sent only as the `ApiKey` header. It is never
-printed: errors, `--dry-run` output and `whoami` show it as `zoo_…<last4>`. Redirects are
-refused so the header cannot be forwarded. A missing key is a usage error (exit 2) and no
-request is sent. The key keeps its owner's workspace and property scope.
+`ZOODEALIO_API_KEY` wins over a stored login. If neither is present the CLI exits 3 with
+`Not signed in. Run zoodealio login, or set ZOODEALIO_API_KEY.` and sends nothing.
+A 401 on a stored login means it was revoked or expired; run `zoodealio login` again.
+
+The key is sent only as the `ApiKey` header. It is never printed: errors, `--dry-run` output and
+`whoami` show it as `zoo_…<last4>` (the one exception is `keys create`, whose purpose is to show a
+new key once). Redirects are refused so the header cannot be forwarded. The key keeps its owner's
+workspace and property scope. Every request sends `User-Agent: zoodealio-cli/<version>`.
+
+`zoodealio whoami` confirms the key works and shows the target origin, `source` (`login` or
+`env`) and, for a login, the `email`.
+
+### Keys
+
+```sh
+zoodealio keys list                 # your keys; "current" marks the one in use
+zoodealio keys create --name ci     # prints the raw key once
+zoodealio keys revoke <id> --yes
+```
+
+Key management needs a key created by `zoodealio login`; keys made with `keys create` or in the web
+app cannot manage keys.
+
+### MCP
+
+`zoodealio mcp` is a stdio MCP server that forwards each JSON-RPC message to the hosted
+`/openapi/mcp` endpoint with your key, so MCP clients need no HTTP or header setup.
+
+```sh
+claude mcp add zoodealio -- zoodealio mcp
+```
+
+Cursor (`.cursor/mcp.json`) or VS Code (`.vscode/mcp.json`, under `servers`):
+
+```json
+{ "mcpServers": { "zoodealio": { "command": "zoodealio", "args": ["mcp"] } } }
+```
 
-`zoodealio whoami` confirms the key works and shows the target origin.
+Run `zoodealio login` first (or put `ZOODEALIO_API_KEY` in the client's `env`). Stdout carries only
+JSON-RPC; logs go to stderr.
 
 ## Environments
 
@@ -69,9 +125,9 @@ for usage and network errors. A 429 adds `retryAfter` in seconds.
 | Exit | Meaning | `code` |
 | --- | --- | --- |
 | 0 | Success | |
-| 1 | Other API or network error | `http_error`, `network_error` |
-| 2 | Usage: unknown command or flag, missing argument, bad ID or JSON, missing `--yes`, missing key, or HTTP 400 | `usage`, `bad_request` |
-| 3 | Not authenticated or not allowed (401, 403) | `unauthorized`, `forbidden` |
+| 1 | Other API or network error; login cancelled or timed out | `http_error`, `network_error`, `login_cancelled`, `login_timeout` |
+| 2 | Usage: unknown command or flag, missing argument, bad ID or JSON, missing `--yes`, or HTTP 400 | `usage`, `bad_request` |
+| 3 | Not signed in, or not authenticated or allowed (401, 403) | `unauthorized`, `forbidden` |
 | 4 | Not found (404) | `not_found` |
 | 5 | Conflict, precondition or validation failure (409, 412, 422) | `conflict`, `precondition_failed`, `validation_failed` |
 | 6 | Rate limited (429) | `rate_limited` |
@@ -120,12 +176,15 @@ concurrency on `properties update`, `offers accept` and `offers request-details`
 | `webhooks create` | POST Webhooks | `--url` and `--event` (repeatable) or `--body` |
 | `webhooks update <id>` | PUT Webhooks/{id} | `--body` (`endpointUrl`, `eventTypes`, `isActive`) |
 | `webhooks rotate <id>`, `webhooks delete <id>` | POST, DELETE | `--yes` required |
-| `whoami` | | Key check; prints `{ok, origin, key}` |
+| `login`, `logout` | | Browser sign-in and sign-out; `login` takes `--no-browser`, `--name` |
+| `keys list\|create\|revoke` | GET, POST, DELETE Keys | `create`: `--name`; `revoke <id>` needs `--yes`; needs a `login` key |
+| `mcp` | POST `/openapi/mcp` | stdio MCP bridge |
+| `whoami` | | Key check; prints `{ok, origin, key, source, email?}` |
 | `openapi` | GET `/_openapi/partner.json` | Partner OpenAPI document; no key needed |
 | `api <METHOD> <path>` | any `/openapi/...` | `--query k=v` (repeatable), `--body`; `DELETE` needs `--yes` |
 | `commands` | | Command catalogue as JSON |
 
-Destructive commands (`offers accept`, `team remove`, `properties photos delete`,
+Destructive commands (`keys revoke`, `offers accept`, `team remove`, `properties photos delete`,
 `properties documents delete`, `webhooks rotate`, `webhooks delete`, and `api ... DELETE`)
 refuse to run without `--yes`, exit 2, and send nothing. `--dry-run` previews them
 without `--yes`, since it sends nothing either.
@@ -172,15 +231,15 @@ 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
 
 - No multipart uploads of local files. Photos and documents are imported from URLs only
   (`photos add --url`); `api` cannot send multipart either.
-- No config file, keychain or interactive prompts; the environment variable is the only
-  credential source.
+- No keychain or interactive prompts. Credentials are `ZOODEALIO_API_KEY` or the
+  `credentials.json` written by `zoodealio login`.
 
 ## Development
 
@@ -192,13 +251,15 @@ npm run check   # eslint, tsc --noEmit (checkJs), node --test
 
 ## Releasing
 
-Maintainers publish from their machine with a granular npm token kept outside the repo:
+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 publish --userconfig ~/.config/zoodealio/npm-publish.npmrc
+npm stage publish --userconfig ~/.config/zoodealio/npm-publish.npmrc
 ```
 
-A version with a `-` suffix (`0.2.0-beta.1`) goes out with `--tag next` so `latest` stays stable.
+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.1.0",
+  "version": "0.2.1",
   "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,12 +2,17 @@ const { CliError, usage } = require('./errors');
 const { parse, normalizeApiPath, METHODS } = require('./args');
 const { catalogue } = require('./commands');
 const { resolveBody } = require('./input');
-const { redactKey, resolveOrigin, buildUrl, send } = require('./http');
-const pkg = require('../package.json');
+const { 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}} Io
+ *   stderr: {write(s: string): unknown}, stdin: AsyncIterable<string | Buffer>, fetch?: typeof fetch,
+ *   openBrowser?: (url: string) => Promise<void>, copy?: (text: string) => Promise<void>, loginTimeoutMs?: number,
+ *   interactive?: boolean, onKey?: (handler: (key: string) => void) => () => void}} Io
  */
 
 /**
@@ -17,20 +22,18 @@ const pkg = require('../package.json');
  * @returns {Promise<number>} exit code
  */
 async function run(argv, io) {
-    const key = (io.env.ZOODEALIO_API_KEY || '').trim();
+    const envKey = (io.env.ZOODEALIO_API_KEY || '').trim();
+    /** Every key seen this run; none may appear in output. */
+    const secrets = new Set(envKey ? [envKey] : []);
     try {
-        await execute(argv, io, key);
+        await execute(argv, io, envKey, secrets);
         return 0;
     } catch (err) {
         const error = err instanceof CliError
             ? err
             : new CliError({ exit: 1, code: 'internal', title: 'Unexpected error', detail: /** @type {Error} */ (err).message });
-        let text = JSON.stringify(error.toJSON());
-        if (key) {
-            // The key can appear JSON-escaped (newline, quote, backslash) inside the serialized error.
-            for (const form of [key, JSON.stringify(key).slice(1, -1)]) text = text.split(form).join(redactKey(key));
-        }
-        io.stderr.write(`${text}\n`);
+        // A key can appear JSON-escaped (newline, quote, backslash) inside the serialized error.
+        io.stderr.write(`${scrubKeys(JSON.stringify(error.toJSON()), secrets)}\n`);
         return error.exit;
     }
 }
@@ -38,9 +41,10 @@ async function run(argv, io) {
 /**
  * @param {string[]} argv
  * @param {Io} io
- * @param {string} key
+ * @param {string} envKey
+ * @param {Set<string>} secrets
  */
-async function execute(argv, io, key) {
+async function execute(argv, io, envKey, secrets) {
     const parsed = parse(argv);
     if ('help' in parsed) {
         io.stdout.write(parsed.help);
@@ -53,6 +57,68 @@ async function execute(argv, io, key) {
 
     if (command.name === 'commands') return emit(catalogue());
 
+    const origin = resolveOrigin(io.env, flags.env);
+    const stored = readCredential(io.env, origin);
+    if (stored) secrets.add(stored.key);
+    const source = envKey ? 'env' : stored ? 'login' : undefined;
+    const key = envKey || stored?.key || '';
+
+    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),
+                envName: flags.env || 'prod', 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);
+            const file = saveCredential(io.env, origin, { key: result.key, keyId: result.keyId, email: result.email, name: result.name });
+            const dev = flags.env && flags.env !== 'prod' ? ` --env ${flags.env}` : '';
+            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)}${dev ? ` ${style.dim(`(${flags.env})`)}` : ''}`);
+            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') {
+            if (!stored) {
+                return emit({
+                    ok: true, loggedOut: false,
+                    detail: envKey ? 'Signed in only through ZOODEALIO_API_KEY; nothing to sign out of.' : 'Not signed in.',
+                });
+            }
+            try {
+                await send(io.fetch || fetch, {
+                    method: 'DELETE', url: buildUrl(origin, `/openapi/Keys/${encodeURIComponent(stored.keyId)}`, []),
+                    headers: { Accept: 'application/json', 'User-Agent': USER_AGENT, ApiKey: stored.key },
+                });
+            } catch (err) {
+                // 401/404 mean the key is already gone; anything else keeps the login so it can be retried.
+                if (!(err instanceof CliError) || (err.status !== 401 && err.status !== 404)) throw err;
+            }
+            removeCredential(io.env, origin);
+            return emit({ ok: true, loggedOut: true, email: stored.email, origin });
+        }
+        if (!key) throw notSignedIn();
+        return bridge({ url: origin, key, stdin: io.stdin, stdout: io.stdout, stderr: io.stderr, fetch: io.fetch, scrub: (s) => scrubKeys(s, secrets), storedLogin: source === 'login' });
+    }
+
     /** @type {string} */
     let method;
     /** @type {string} */
@@ -90,14 +156,13 @@ async function execute(argv, io, key) {
     }
 
     const needsKey = command.auth !== false;
-    if (needsKey && !key && !flags['dry-run']) throw usage('ZOODEALIO_API_KEY is not set');
+    if (needsKey && !key && !flags['dry-run']) throw notSignedIn();
 
-    const origin = resolveOrigin(io.env, flags.env);
     const url = buildUrl(origin, path, query);
     /** @param {string} apiKey */
     const headers = (apiKey) => ({
         Accept: 'application/json',
-        'User-Agent': `zoodealio-cli/${pkg.version}`,
+        'User-Agent': USER_AGENT,
         ...(needsKey ? { ApiKey: apiKey } : {}),
         ...(body === undefined ? {} : { 'Content-Type': 'application/json' }),
         ...(flags['if-match'] === undefined ? {} : { 'If-Match': flags['if-match'] }),
@@ -105,9 +170,23 @@ async function execute(argv, io, key) {
 
     if (flags['dry-run']) return emit({ method, url, headers: headers(redactKey(key)), body: body ?? null });
 
-    const result = await send(io.fetch || fetch, { method, url, headers: headers(key), body });
-    if (command.name === 'whoami') return emit({ ok: true, origin, key: redactKey(key) });
+    /** @type {unknown} */
+    let result;
+    try {
+        result = await send(io.fetch || fetch, { method, url, headers: headers(key), body });
+    } catch (err) {
+        if (source === 'login' && err instanceof CliError && err.status === 401) {
+            throw new CliError({ exit: 3, status: 401, code: 'unauthorized', title: 'Login revoked or expired', detail: 'The stored login was revoked or expired. Run zoodealio login again.' });
+        }
+        throw err;
+    }
+    if (command.name === 'keys revoke' && source === 'login' && stored && args.id === stored.keyId) removeCredential(io.env, origin);
+    if (command.name === 'whoami') return emit({ ok: true, origin, key: redactKey(key), source, ...(source === 'login' && stored ? { email: stored.email } : {}) });
     return emit(result);
 }
 
+function notSignedIn() {
+    return new CliError({ exit: 3, code: 'unauthorized', title: 'Not signed in', detail: 'Not signed in. Run zoodealio login, or set ZOODEALIO_API_KEY.' });
+}
+
 module.exports = { run };

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, notes?: string[]}} Command
  */
 
 /**
@@ -135,6 +135,37 @@ const COMMANDS = [
     cmd('webhooks deliveries', 'List webhook deliveries', 'GET', '/openapi/Webhooks/deliveries', {
         flags: [str('subscription', 'Subscription id', { query: 'subscriptionId' }), str('status', 'Delivery status', { query: 'status' }), ...PAGING],
     }),
+    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)'),
+        ],
+    }),
+    cmd('logout', 'Revoke the stored CLI key and forget it', 'DELETE', '/openapi/Keys/{keyId}'),
+    cmd('keys list', 'List your API keys (needs a zoodealio login)', 'GET', '/openapi/Keys'),
+    cmd('keys create', 'Create an API key; the raw key is shown once', 'POST', '/openapi/Keys', {
+        flags: [str('name', 'Key name', { required: true })],
+        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', {
+        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, {
@@ -193,8 +224,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. Key: ZOODEALIO_API_KEY.', '');
+        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

@@ -0,0 +1,89 @@
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { CliError } = require('./errors');
+
+/**
+ * @typedef {{key: string, keyId: string, email: string, name: string}} Credential
+ */
+
+/**
+ * @param {Record<string, string | undefined>} env
+ * @returns {string} directory holding credentials.json
+ */
+function configDir(env) {
+    if (env.XDG_CONFIG_HOME) return path.join(env.XDG_CONFIG_HOME, 'zoodealio');
+    if (process.platform === 'win32' && env.APPDATA) return path.join(env.APPDATA, 'zoodealio');
+    return path.join(env.HOME || os.homedir(), '.config', 'zoodealio');
+}
+
+/**
+ * @param {Record<string, string | undefined>} env
+ * @param {boolean} [strict] throw instead of returning empty when the file exists but is unreadable, so a rewrite cannot wipe it
+ * @returns {Record<string, Credential>} stored logins keyed by API origin; empty when missing (or unreadable, unless strict)
+ */
+function readAll(env, strict = false) {
+    const file = path.join(configDir(env), 'credentials.json');
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) return parsed;
+    } catch (err) {
+        if (/** @type {NodeJS.ErrnoException} */ (err).code === 'ENOENT') return {};
+    }
+    if (strict) {
+        throw new CliError({ exit: 1, code: 'credentials_unreadable', title: 'Credentials file is unreadable', detail: `${file} is not valid JSON. Fix or delete it, then run zoodealio login again.` });
+    }
+    return {};
+}
+
+/**
+ * @param {Record<string, string | undefined>} env
+ * @param {string} origin
+ * @returns {Credential | undefined}
+ */
+function readCredential(env, origin) {
+    const all = readAll(env);
+    const entry = Object.hasOwn(all, origin) ? all[origin] : undefined;
+    return entry && typeof entry.key === 'string' && entry.key ? entry : undefined;
+}
+
+/**
+ * Writes atomically (temp file, then rename) with owner-only permissions.
+ * @param {Record<string, string | undefined>} env
+ * @param {Record<string, Credential>} all
+ */
+function writeAll(env, all) {
+    const dir = configDir(env);
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const temp = path.join(dir, `credentials.json.${process.pid}.tmp`);
+    try {
+        fs.writeFileSync(temp, `${JSON.stringify(all, null, 2)}\n`, { mode: 0o600, flag: 'w' });
+        fs.renameSync(temp, path.join(dir, 'credentials.json'));
+    } catch (err) {
+        fs.rmSync(temp, { force: true });
+        throw err;
+    }
+}
+
+/**
+ * @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');
+}
+
+/**
+ * @param {Record<string, string | undefined>} env
+ * @param {string} origin
+ */
+function removeCredential(env, origin) {
+    const all = readAll(env, true);
+    delete all[origin];
+    writeAll(env, all);
+}
+
+module.exports = { configDir, readCredential, saveCredential, removeCredential };

package/src/http.js

@@ -1,5 +1,7 @@
 const { CliError, usage } = require('./errors');
+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' };
 
 /** @type {Record<number, [number, string]>} status -> [exit code, error code slug] */
@@ -23,6 +25,20 @@ function redactKey(key) {
     return key.length >= 12 ? `zoo_…${key.slice(-4)}` : 'zoo_…';
 }
 
+/**
+ * Replaces every known key in text, raw or JSON-escaped, with its redacted form.
+ * @param {string} text
+ * @param {Iterable<string>} keys
+ * @returns {string}
+ */
+function scrubKeys(text, keys) {
+    let out = text;
+    for (const key of keys) {
+        for (const form of [key, JSON.stringify(key).slice(1, -1)]) out = out.split(form).join(redactKey(key));
+    }
+    return out;
+}
+
 /**
  * @param {Record<string, string | undefined>} env
  * @param {string | undefined} envName
@@ -107,4 +123,4 @@ async function send(doFetch, req) {
     }
 }
 
-module.exports = { ENVS, redactKey, resolveOrigin, buildUrl, send };
+module.exports = { ENVS, USER_AGENT, redactKey, scrubKeys, resolveOrigin, buildUrl, send };

package/src/login.js

@@ -0,0 +1,212 @@
+const crypto = require('node:crypto');
+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 WEB_ENVS = { prod: 'https://zoodealio.ai', dev: 'https://dev.zoodealio.ai' };
+const LOGIN_TIMEOUT_MS = 5 * 60 * 1000;
+
+/**
+ * @param {Record<string, string | undefined>} env
+ * @param {string | undefined} envName
+ * @returns {string} web origin without trailing slash
+ */
+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')];
+}
+
+/**
+ * Opens a URL in the default browser. Rejects when no opener could be started.
+ * @param {string} url
+ * @returns {Promise<void>}
+ */
+function openBrowser(url) {
+    const [command, args, options] = process.platform === 'win32'
+        ? ['cmd', ['/d', '/s', '/c', `start "" "${url}"`], { windowsVerbatimArguments: true }]
+        : [process.platform === 'darwin' ? 'open' : 'xdg-open', [url], {}];
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, { stdio: 'ignore', detached: true, ...options });
+        child.once('error', reject);
+        child.once('spawn', () => {
+            child.unref();
+            resolve();
+        });
+    });
+}
+
+/**
+ * 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>`;
+
+/**
+ * Listens on a loopback port for the browser's one redirect back to /callback.
+ * @param {string} state
+ * @param {number} timeoutMs
+ * @returns {Promise<{port: number, result: Promise<{code?: string, error?: string}>, close: () => void}>}
+ */
+async function listenForCallback(state, timeoutMs) {
+    /** @type {(r: {code?: string, error?: string}) => void} */
+    let finish = () => {};
+    /** @type {(e: Error) => void} */
+    let fail = () => {};
+    const result = new Promise((resolve, reject) => { finish = resolve; fail = reject; });
+    const stateBuffer = Buffer.from(state);
+    const server = http.createServer((req, res) => {
+        const url = new URL(req.url || '/', 'http://127.0.0.1');
+        const got = Buffer.from(url.searchParams.get('state') || '');
+        res.setHeader('Connection', 'close');
+        if (req.method !== 'GET' || url.pathname !== '/callback') {
+            res.writeHead(404).end();
+        } else if (got.length !== stateBuffer.length || !crypto.timingSafeEqual(got, stateBuffer)) {
+            // A stray or forged request must not be able to abort the real login.
+            res.writeHead(400, { 'content-type': 'text/html; charset=utf-8' }).end(PAGE('Sign-in link did not match'));
+        } else if (url.searchParams.get('error')) {
+            res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' }).end(PAGE('Sign-in cancelled'));
+            finish({ error: /** @type {string} */ (url.searchParams.get('error')) });
+        } else if (url.searchParams.get('code')) {
+            res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' }).end(PAGE('Signed in to the Zoodealio CLI'));
+            finish({ code: /** @type {string} */ (url.searchParams.get('code')) });
+        } else {
+            res.writeHead(400).end();
+        }
+    });
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', () => resolve(undefined));
+    });
+    const timer = setTimeout(() => fail(new CliError({ exit: 1, code: 'login_timeout', title: 'Login timed out', detail: 'No sign-in came back from the browser. Run zoodealio login again.' })), timeoutMs);
+    return {
+        port: /** @type {import('node:net').AddressInfo} */ (server.address()).port,
+        result,
+        close: () => {
+            clearTimeout(timer);
+            server.close();
+            server.closeIdleConnections();
+        },
+    };
+}
+
+/**
+ * Browser sign-in (authorization code + PKCE). Returns the exchange response; the caller stores it.
+ * 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) {
+    const state = crypto.randomBytes(32).toString('base64url');
+    const verifier = crypto.randomBytes(32).toString('base64url');
+    const challenge = crypto.createHash('sha256').update(verifier).digest('base64url');
+    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 })}`;
+        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);
+                ui.say(`  ${style.dim('Opened your browser. Nothing there? Use the link above, or press Enter.')}`);
+            } catch {
+                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' });
+                    }
+                });
+            });
+        }
+        ui.spin(`Waiting for you to authorize in the browser… ${style.dim(`(the link works for ${minutes} minute${minutes === 1 ? '' : 's'})`)}`);
+
+        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.' : `The browser reported: ${error}`,
+            });
+        }
+        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();
+    }
+}
+
+/** @returns {string} */
+const defaultDevice = () => os.hostname().slice(0, 64) || 'cli';
+
+module.exports = { browserLogin, resolveWebOrigin, defaultDevice };

package/src/mcp.js

@@ -0,0 +1,107 @@
+const { StringDecoder } = require('node:string_decoder');
+const { USER_AGENT } = require('./http');
+
+/** @typedef {{write(s: string): unknown}} Sink */
+
+/** @param {string} text @returns {unknown[]} the JSON payload of each data event */
+function sseMessages(text) {
+    const messages = [];
+    for (const event of text.split(/\r?\n\r?\n/)) {
+        const data = event.split(/\r?\n/).filter((l) => l.startsWith('data:')).map((l) => l.slice(5).replace(/^ /, '')).join('\n');
+        if (!data) continue;
+        try {
+            messages.push(JSON.parse(data));
+        } catch {
+            // not JSON (keep-alive or comment)
+        }
+    }
+    return messages;
+}
+
+/**
+ * Bridges newline-delimited JSON-RPC on stdin to the remote MCP endpoint, one POST per message.
+ * Stdout carries only JSON-RPC responses; logs go to stderr.
+ * @param {{url: string, key: string, stdin: AsyncIterable<string | Buffer>, stdout: Sink, stderr: Sink,
+ *   fetch?: typeof fetch, scrub?: (s: string) => string, storedLogin?: boolean}} opts
+ */
+async function bridge(opts) {
+    const doFetch = opts.fetch || fetch;
+    const scrub = opts.scrub || ((/** @type {string} */ s) => s);
+    /** @type {string | undefined} */
+    let sessionId;
+    /** @type {Set<Promise<void>>} */
+    const pending = new Set();
+
+    /** @param {unknown} message */
+    const emit = (message) => opts.stdout.write(`${JSON.stringify(message)}\n`);
+    /** @param {unknown} id @param {number} code @param {string} message */
+    const fail = (id, code, message) => {
+        const text = scrub(message);
+        opts.stderr.write(`zoodealio mcp: ${text}\n`);
+        if (id !== undefined) emit({ jsonrpc: '2.0', id, error: { code, message: text } });
+    };
+
+    /** @param {string} line */
+    async function forward(line) {
+        let message;
+        try {
+            message = JSON.parse(line);
+        } catch {
+            return fail(null, -32700, 'Parse error: input line is not valid JSON');
+        }
+        const id = message && typeof message === 'object' && 'id' in message ? message.id : undefined;
+        try {
+            const res = await doFetch(`${opts.url}/openapi/mcp`, {
+                method: 'POST',
+                headers: {
+                    ApiKey: opts.key,
+                    Accept: 'application/json, text/event-stream',
+                    'Content-Type': 'application/json',
+                    'User-Agent': USER_AGENT,
+                    ...(sessionId ? { 'Mcp-Session-Id': sessionId } : {}),
+                },
+                body: line,
+                redirect: 'error',
+                signal: AbortSignal.timeout(300000),
+            });
+            const text = await res.text();
+            sessionId ??= res.headers.get('mcp-session-id') || undefined;
+            if (!res.ok) {
+                let detail = '';
+                try {
+                    const problem = JSON.parse(text);
+                    detail = problem.detail || problem.title || '';
+                } catch {
+                    // non-JSON error body
+                }
+                const hint = res.status === 401 && opts.storedLogin ? '. The stored login was revoked or expired; run zoodealio login again' : '';
+                return fail(id, -32000, `HTTP ${res.status}${detail ? `: ${detail}` : ''}${hint}`);
+            }
+            if (!text.trim()) return;
+            const payloads = (res.headers.get('content-type') || '').includes('text/event-stream') ? sseMessages(text) : [JSON.parse(text)];
+            for (const payload of payloads.flat()) emit(payload);
+        } catch (err) {
+            const e = /** @type {{message?: string, cause?: {message?: string}}} */ (err);
+            fail(id, -32000, e.cause?.message || e.message || 'request failed');
+        }
+    }
+
+    const decoder = new StringDecoder('utf8');
+    let buffer = '';
+    /** @param {string} line */
+    const dispatch = (line) => {
+        if (!line.trim()) return;
+        const p = forward(line).finally(() => pending.delete(p));
+        pending.add(p);
+    };
+    for await (const chunk of opts.stdin) {
+        buffer += typeof chunk === 'string' ? chunk : decoder.write(chunk);
+        const lines = buffer.split('\n');
+        buffer = /** @type {string} */ (lines.pop());
+        lines.forEach(dispatch);
+    }
+    dispatch(buffer + decoder.end());
+    await Promise.all(pending);
+}
+
+module.exports = { bridge };

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 };