@phantomcodes/cli 1.2.3 → 1.2.5

package/README.md

@@ -62,8 +62,8 @@ The Phantom CLI detects supported agents, previews the configuration changes, th
 applying them. It connects their model calls to Phantom AI and wires up the saved
 key. Restart your agent, or open a new terminal, to use the connection.
 
-Codex, Claude Code, opencode, Continue, Goose, Aider, GitHub Copilot CLI and Cline
-support saved setup. Cursor gets instructions for its settings screen; pi gets
+Codex, Claude Code, opencode, Continue, Goose, Aider, GitHub Copilot CLI, Cline
+and Gemini CLI support saved setup. Cursor gets instructions for its settings screen; pi gets
 the agent skill.
 
 Preview without changing files with `phantom setup --dry-run`. The Phantom CLI keeps backups;
@@ -74,14 +74,16 @@ undo the changes with `phantom setup --restore`.
 ```bash
 npm i -g @phantomcodes/cli
 phantom login
-phantom workspace fund --amount 10 --card
+phantom fund --amount 10 --card
 phantom workspace status
 phantom codex
 ```
 
-Both setup options require **Node 24+** and your coding agent installed. Connect, fund your
-workspace, then launch **Codex** (`phantom codex`), **Claude Code** (`phantom claude`),
-**pi** (`phantom pi`), or **any other compatible agent**.
+Both setup options require **Node 24+** and your coding agent installed. Connect, then
+launch **Codex** (`phantom codex`), **Claude Code** (`phantom claude`), **pi**
+(`phantom pi`), or **any other compatible agent**. Each runs phantom-1 unless you
+pick a model (`--model` after `--`), and phantom-1 runs on free models until you add
+credit. Free calls leave out web search, which costs money on any model.
 
 Login opens a device approval page and saves a key privately. Funding opens
 checkout; check your workspace balance after payment. Agent runs use temporary
@@ -175,7 +177,7 @@ it cancels. A named model, not `phantom-1`, still spends credit.
 | Connect | `phantom login`, `phantom logout` |
 | Connect existing agents | `phantom setup`, `phantom setup --dry-run`, `phantom setup --restore` |
 | Run inference | `phantom claude`, `phantom codex`, `phantom pi` |
-| Fund and check spending | `phantom workspace fund`, `phantom workspace status`, `phantom balance`, `phantom spend` |
+| Fund and check spending | `phantom fund`, `phantom balance`, `phantom spend`, `phantom workspace status` |
 | Manage workspace keys | `phantom keys create`, `phantom keys set`, `phantom keys rotate`, `phantom keys revoke` |
 | Manage local copies | `phantom keys saved`, `phantom keys save`, `phantom keys rm` |
 | Route models | `phantom route` |
@@ -187,9 +189,14 @@ Put phantom flags before agent arguments; use `--` to separate them:
 phantom codex --key coding -- exec "explain this repository"
 ```
 
-Commands print JSON; `--table` renders supported results for people. Agent
-commands inherit the terminal and print a spending summary on stderr.
-Exit codes: 0 success, 1 error, 2 rejected key; agent runs return the agent's exit code.
+In a terminal, commands draw a screen for people, and choices are pickers
+(arrow keys, Enter, Esc to go back). Piped, as scripts and agents run them,
+they print JSON on stdout and errors on stderr; `--json` forces JSON in a
+terminal, and `--table` the screen in a pipe. Unknown flags are refused.
+Agent commands inherit the terminal and print a spending summary on stderr.
+Exit codes: 0 success (and Esc), 1 error, 2 rejected key, 130 Ctrl+C;
+`phantom setup` returns 1 when it could only install the skills (no key yet,
+`"complete": false`). Agent runs return the agent's exit code.
 
 <details>
 <summary><strong>Advanced tools, integrations and legacy commands</strong></summary>

package/dist/agents/command.mjs

@@ -2,11 +2,14 @@ import os from 'node:os';
 import path from 'node:path';
 import { spawn } from 'node:child_process';
 import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
-import { die } from "../core/errors.mjs";
+import { die, NO_KEY } from "../core/errors.mjs";
 import { DEFAULT_BASE_URL, httpsOnly, request } from "../core/request.mjs";
 import { keyId, readNamedKey, resolveApiKey } from "../keys/saved.mjs";
 import { workspaceLogin } from "../workspace/command.mjs";
-const DEFAULT_MODEL = 'auto';
+/** The model an agent runs when the user names none: phantom-1, which runs free on a key with no credit. */
+const DEFAULT_MODEL = 'phantom-1';
+/** phantom-1 as Claude Code names it: its picker keeps only ids that say "claude", so Phantom lists them as `claude-code/<id>`. */
+const CLAUDE_DEFAULT_MODEL = `claude-code/${DEFAULT_MODEL}`;
 /** The key's spend and balance, or null when the answer has no numbers, such as a sign-in page that came back with status 200. */
 async function keyStatus(apiKey, baseUrl) {
     const s = await request('GET', '/key/balance', apiKey, undefined, baseUrl);
@@ -23,11 +26,16 @@ export const AGENTS = {
             // --settings outranks settings.json, so an env block or apiKeyHelper
             // `phantom setup` wrote can't send Claude Code past the proxy. The helper
             // reads the token from the environment, so it stays off the command line.
+            // It runs with this phantom's own Node: the curl installer puts none on PATH.
+            const helper = `${JSON.stringify(process.execPath)} -p "process.env.PHANTOM_AGENT_TOKEN || ''"`;
+            // phantom-1 unless the user picks a model. It goes in the environment, which
+            // Claude Code ranks below --model and below a model in its settings file.
+            const model = hasModel(args) || env.ANTHROPIC_MODEL ? {} : { ANTHROPIC_MODEL: CLAUDE_DEFAULT_MODEL };
             const vars = { ANTHROPIC_BASE_URL: proxy, CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY: '1', ENABLE_TOOL_SEARCH: 'true' };
             const { ANTHROPIC_AUTH_TOKEN: _auth, ...rest } = env;
             return {
-                args: ['--settings', JSON.stringify({ apiKeyHelper: 'node -p "process.env.PHANTOM_AGENT_TOKEN || \'\'"', env: vars }), ...args],
-                env: { ...rest, ANTHROPIC_BASE_URL: proxy, ANTHROPIC_API_KEY: token, PHANTOM_AGENT_TOKEN: token },
+                args: ['--settings', JSON.stringify({ apiKeyHelper: helper, env: vars }), ...args],
+                env: { ...rest, ...model, ANTHROPIC_BASE_URL: proxy, ANTHROPIC_API_KEY: token, PHANTOM_AGENT_TOKEN: token },
             };
         },
     },
@@ -78,7 +86,7 @@ function waitFor(bin, args, env) {
         const done = () => process.off('SIGINT', ignore);
         child.on('error', (err) => {
             done();
-            reject(err.code === 'ENOENT' ? new Error(`${bin} is not on your PATH. Install it, then run this again.`) : err);
+            reject(err.code === 'ENOENT' ? new Error(notInstalled(bin)) : err);
         });
         child.on('exit', (code, signal) => {
             done();
@@ -115,7 +123,7 @@ export async function agentCommand(input) {
         if (a === '--key')
             keyName = value(a);
         else if (a === '--mpp')
-            die('--mpp has been removed. Phantom stays prepaid only. Run phantom login or use a saved key.');
+            die('--mpp has been removed. Phantom stays prepaid only. Run phantom login to sign in, or use a saved key.');
         else if (a === '--no-browser')
             noBrowser = true;
         else
@@ -125,12 +133,12 @@ export async function agentCommand(input) {
     let apiKey = keyName ? readNamedKey(env, keyName) : resolveApiKey(env);
     if (!apiKey) {
         if (!io.isTTY)
-            die('Connect a key with phantom login.');
+            die(NO_KEY);
         await workspaceLogin({ ...input, flags: { ...(noBrowser ? { 'no-browser': true } : {}) } });
         apiKey = resolveApiKey(env);
     }
     if (!apiKey)
-        die('No API key. Run: phantom login');
+        die(NO_KEY);
     const auth = { kind: 'key', apiKey };
     const before = await keyStatus(apiKey, baseUrl).catch(() => null);
     const report = async () => {
@@ -155,3 +163,13 @@ export async function agentCommand(input) {
         rmSync(tmp, { recursive: true, force: true });
     }
 }
+/** Where to get each agent phantom starts, for when it isn't installed. */
+const INSTALL = {
+    claude: 'Claude Code: https://code.claude.com/docs/en/setup',
+    codex: 'Codex: npm install -g @openai/codex',
+};
+/** The message when an agent's program isn't installed, in plain words, with where to get it. */
+export function notInstalled(bin) {
+    const how = INSTALL[bin];
+    return `I can't find the ${bin} program on this computer, so it isn't installed yet (or isn't on your PATH).${how ? ` Install ${how}, then run this again.` : ' Install it, then run this again.'}`;
+}

package/dist/cli/app.mjs

@@ -0,0 +1,162 @@
+import { colorOn, paint } from "../core/style.mjs";
+import { BackToMenu, Cancelled, choose } from "../core/pick.mjs";
+import { onPath } from "../setup/shared.mjs";
+import { isSetUp } from "../setup/apply.mjs";
+import { resolveApiKey } from "../keys/saved.mjs";
+import { hideHints } from "./screens.mjs";
+import { startHeader } from "./start.mjs";
+import { COMMANDS } from "./commands.mjs";
+/** The agents the menu can start, and the program each needs on this computer. */
+const AGENTS = [
+    { label: 'Start Claude Code', bin: 'claude', run: ['claude'] },
+    { label: 'Start Codex', bin: 'codex', run: ['codex'] },
+    { label: 'Start pi', bin: 'pi', run: ['pi'] },
+];
+/** The main menu for the state this computer is in. */
+export function mainMenu(s) {
+    const quit = { label: 'Quit', value: { run: [] } };
+    if (!s.signedIn) {
+        return [
+            { label: 'Set up my coding agents', hint: 'sign in and connect them; phantom-1 is free to start', value: { run: ['setup'] } },
+            { label: 'Sign in only', hint: 'or save a Phantom key you already have', value: { run: ['login'] } },
+            { label: 'Every command', hint: 'pick one to run', value: { open: 'commands' } },
+            quit,
+        ];
+    }
+    // Only agents that are installed here, so the menu never offers one that can't start.
+    const agents = s.setUp ? AGENTS.filter((a) => s.installed(a.bin)).map((a) => ({ label: a.label, hint: 'on Phantom AI', value: { run: a.run } })) : [];
+    return [
+        ...(s.setUp ? [] : [{ label: 'Finish setting up my agents', hint: "you're signed in, but no agent uses Phantom yet", value: { run: ['setup'] } }]),
+        ...agents,
+        { label: 'Balance', hint: 'what this key can spend', value: { run: ['balance'] } },
+        { label: 'Spend', hint: 'what you spent, and what phantom-1 saved', value: { run: ['spend'] } },
+        { label: 'Add credit', hint: 'by card or crypto', value: { run: ['fund'] } },
+        { label: 'Choose models', hint: 'the model phantom-1 runs in each tier', value: { run: ['lineup', 'set'] } },
+        { label: 'Keys', hint: 'list, new, limits, revoke', value: { open: 'keys' } },
+        { label: 'Plan', hint: 'Pro or Max, instead of credit', value: { run: ['plan'] } },
+        { label: 'Workspace', hint: 'balance, keys and latest calls together', value: { run: ['workspace'] } },
+        { label: 'More', hint: 'setup, undo, routing, sign out, every command', value: { open: 'more' } },
+        quit,
+    ];
+}
+/** The menus a main-menu row opens. */
+function subMenu(which, s) {
+    if (which === 'keys') {
+        return [
+            { label: 'See my keys', value: { run: ['keys'] } },
+            { label: 'New key', hint: 'for a teammate, CI or another computer', value: { run: ['keys', 'create'] } },
+            { label: 'Set a spending limit', value: { run: ['keys', 'set'] } },
+            { label: 'Revoke a key', hint: 'it stops working at once; its credit stays', value: { run: ['keys', 'revoke'] } },
+            { label: 'Rotate a key', hint: 'a new key in its place; the old one stops working', value: { run: ['keys', 'rotate'] } },
+        ];
+    }
+    if (which === 'commands') {
+        return COMMANDS.filter((c) => !c.advanced).map((c) => ({ label: c.name, hint: c.summary, value: { run: [c.name] } }));
+    }
+    return [
+        { label: s.setUp ? 'Set up more agents' : 'Set up my agents', hint: 'or change how they run', value: { run: ['setup'] } },
+        ...(s.setUp ? [{ label: 'Undo setup', hint: 'put your agents back how they were', value: { run: ['setup', '--restore'] } }] : []),
+        { label: 'Routing rules', hint: 'how model "auto" picks', value: { run: ['route'] } },
+        { label: 'Sign out', hint: 'on this computer', value: { run: ['logout'] } },
+        { label: 'Every command', hint: 'pick one to run', value: { open: 'commands' } },
+    ];
+}
+/**
+ * Next steps that change or reveal something (copying a key, signing out):
+ * the marker starts on "Back to the menu" instead, so a stray Enter is safe.
+ */
+const RISKY = new Set(['keys show --copy', 'logout --all']);
+/** After a command's result: the next steps that fit it, as choices, so nobody types the "→" line. */
+export function nextSteps(ran) {
+    const key = ran.join(' ');
+    const steps = {
+        balance: [['Spend', ['spend']], ['Add credit', ['fund']]],
+        spend: [['Every key in the workspace', ['spend', '--workspace']], ['Choose models', ['lineup', 'set']]],
+        'spend --workspace': [['Keys', ['keys']]],
+        fund: [['Balance', ['balance']]],
+        workspace: [['See my keys', ['keys']], ['Spend by key', ['spend', '--workspace']]],
+        keys: [['New key', ['keys', 'create']], ['Set a spending limit', ['keys', 'set']], ['Revoke a key', ['keys', 'revoke']]],
+        plan: [['Start Pro', ['plan', 'pro']], ['Start Max', ['plan', 'max']], ['Manage billing', ['plan', 'manage']]],
+        route: [['See what a request would get', ['route', 'test']], ['Choose models', ['lineup', 'set']]],
+        'setup --restore': [['Sign out, and forget saved keys', ['logout', '--all']]],
+        login: [['Set up my agents', ['setup']]],
+        'keys create': [['See my keys', ['keys']]],
+        'keys revoke': [['See my keys', ['keys']]],
+        'keys set': [['See my keys', ['keys']]],
+        'keys rotate': [['See my keys', ['keys']]],
+        // Cursor and other editors take the key in their own settings: copy it without showing it.
+        setup: [['Copy my key (for Cursor or another app)', ['keys', 'show', '--copy']]],
+    };
+    return (steps[key] ?? []).map(([label, run]) => ({ label, value: run }));
+}
+/**
+ * Runs the app until Quit, Esc on the main menu, or Ctrl+C. `runCommand` runs
+ * one command the way `phantom <args>` would and returns its exit code; the app
+ * passes it `fromMenu`, so a command's first Esc comes back here.
+ */
+export async function runApp(env, pick, write, runCommand, installed = onPath) {
+    const color = colorOn(env, true);
+    const p = paint(env, color);
+    const state = () => ({ signedIn: Boolean(resolveApiKey(env)), setUp: isSetUp(env), installed });
+    // The "→ type this next" lines would repeat the choices offered after each result, so they're hidden here.
+    const hintsWere = hideHints(true);
+    try {
+        for (;;) {
+            // A clean screen for each visit to the menu: a title, then where you are.
+            write('\x1b[2J\x1b[H' + startHeader(env, color) + '\n');
+            const s = state();
+            write(`  ${p.dim(s.signedIn ? (s.setUp ? 'Signed in · your agents use Phantom AI' : 'Signed in · no agent set up yet') : 'Not signed in yet')}\n\n`);
+            let action = await choose({ ...pick, esc: 'quit' }, 'What would you like to do?', mainMenu(s));
+            if (action === null)
+                return 0;
+            // A row that opens another menu; Esc there comes back to the main menu.
+            while (action && 'open' in action) {
+                const sub = subMenu(action.open, s);
+                action = await choose({ ...pick, esc: 'back' }, action.open === 'keys' ? 'Keys' : action.open === 'commands' ? 'Which command?' : 'More', sub);
+            }
+            if (!action)
+                continue;
+            if (!action.run.length)
+                return 0;
+            let ran = action.run;
+            // Run it, then offer what fits next; Back to the menu, or Quit, end the chain.
+            while (ran) {
+                try {
+                    // Ctrl+C inside a command (exit 130) stops the app too, as it would anywhere else.
+                    if ((await runCommand(ran)) === 130)
+                        return 130;
+                }
+                catch (err) {
+                    if (err instanceof Cancelled)
+                        return 130;
+                    if (!(err instanceof BackToMenu))
+                        throw err;
+                    break;
+                }
+                write('\n');
+                const steps = nextSteps(ran);
+                // A risky step first in the list would run on a stray Enter, so the marker starts on Back then.
+                const safe = steps.some((s) => RISKY.has(s.value.join(' '))) ? steps.length : 0;
+                const next = await choose({ ...pick, esc: 'back' }, 'What next?', [
+                    ...steps,
+                    { label: 'Back to the menu', value: ['menu'] },
+                    { label: 'Quit', value: [] },
+                ], safe);
+                if (next === null || next[0] === 'menu')
+                    ran = null;
+                else if (!next.length)
+                    return 0;
+                else
+                    ran = next;
+            }
+        }
+    }
+    catch (err) {
+        if (err instanceof Cancelled)
+            return 130;
+        throw err;
+    }
+    finally {
+        hideHints(hintsWere);
+    }
+}

package/dist/cli/commands.mjs

@@ -8,13 +8,18 @@ import { verifyCommand } from "../receipts/command.mjs";
 import { setupCommand } from "../setup/command.mjs";
 import { SETUP_MODEL } from "../setup/shared.mjs";
 import { SETUP_NAMES, orList } from "../setup/agents.mjs";
+/** The short `--help`'s headings, in the order they print. */
+export const HELP_GROUPS = ['Start', 'Run', 'Money', 'Keys', 'Routing', 'More'];
 async function loginDispatch(input) {
     const { subcommand, flags } = input;
+    // `phantom login google` or `login github`: a word that isn't a key means the usual browser sign-in, not "that is not a key".
+    if (subcommand && !subcommand.startsWith('sk-'))
+        return workspaceLogin({ ...input, subcommand: undefined });
     return subcommand || flags.paste ? loginCommand(input) : workspaceLogin(input);
 }
 async function logoutDispatch(input) {
-    await forgetWorkspace(input.env, input.baseUrl);
-    return logoutCommand(input);
+    const forgot = await forgetWorkspace(input.env, input.baseUrl);
+    return logoutCommand(input, forgot);
 }
 async function fundDispatch(input) {
     const { flags } = input;
@@ -28,15 +33,14 @@ async function fundDispatch(input) {
 export const COMMANDS = [
     {
         name: 'login', handler: loginDispatch, keyless: true,
-        help: `  login [--save <name>] [--no-browser]  connect an account or guest workspace by device code
-  login --paste                       validate and save an existing key
-  login [key]                       save your key so you don't need PHANTOM_API_KEY
-                                    (use --paste to prompt for an existing key)`,
+        group: 'Start', summary: 'sign in only, or save a Phantom key you already have',
+        help: `  login [--save <name>] [--no-browser]  sign in by device code: an account or a guest workspace
+  login --paste                       save a Phantom key you already have (it asks for it)`,
     },
     {
         name: 'workspace', handler: workspaceCommand, keyless: true,
+        group: 'More', summary: 'the whole workspace: balance, recovery and access',
         help: `  workspace [status]                  shared balance, keys, recent usage and management access
-  workspace fund --amount <USD> [--card | --coin usdc|usdt|sol] [--no-browser]
   workspace payment --id <payment-id>  check verified funding status
   workspace export --file <path>       export private guest recovery; refuses overwrites
   workspace import --file <path>       restore a guest, then issue replacement keys
@@ -44,56 +48,68 @@ export const COMMANDS = [
     },
     {
         name: 'fund', handler: fundDispatch, keyless: true,
+        group: 'Money', summary: 'add credit by card or crypto',
         help: `  fund --amount <USD> [--card | --coin usdc|usdt|sol] [--no-browser]
                                     fund your workspace balance with card (plus Stripe's fee) or crypto`,
     },
     {
         name: 'keys', handler: workspaceCommand, keyless: true,
+        group: 'Keys', summary: "your workspace's keys: list, create, set limits, revoke",
         help: `  keys [list]                         remote workspace key metadata, never secrets
   keys create [--save <name>] [--limit <USD>]
   keys set --id <id> [--limit <USD|none>] [--budget <USD|none>]
            [--period <days|none>] [--rate <USD|none>] [--name <name>]
            [--policy-file <path> | --clear-policy]
   keys rotate --id <id> [--save <name>] replace only the corresponding saved key
-  keys revoke --id <id>                revoke access, keeping workspace credit
+  keys revoke --id <id> [--yes]        revoke access, keeping workspace credit (--yes: don't ask)
   keys saved [--balance]               local saved key metadata
   keys save <name> [key]               validate and save an existing key (prompts if omitted)
   keys show [name]                     print a secret for shell integration only
+  keys show [name] --copy              copy it to the clipboard instead (Mac), for an app's settings
   keys rm <name>                       forget a local copy; remote key keeps working`,
     },
     {
         name: 'claude', handler: agentCommand, keyless: true,
+        group: 'Run', summary: 'start Claude Code on Phantom AI',
         help: `  claude [--key <name>] [--no-browser] -- <agent arguments>`,
     },
     {
         name: 'codex', handler: agentCommand, keyless: true,
+        group: 'Run', summary: 'start Codex on Phantom AI',
         help: `  codex [--key <name>] [--no-browser] -- <agent arguments>`,
     },
     {
         name: 'pi', handler: agentCommand, keyless: true,
+        group: 'Run', summary: 'start pi on Phantom AI',
         help: `  pi [--key <name>] [--no-browser] -- <agent arguments>
                                     run with a saved key`,
     },
     {
         name: 'balance', handler: balanceCommand,
+        group: 'Money', summary: 'your credit, and when it expires',
         help: `  balance                           show credit balance and expiry`,
     },
     {
         name: 'spend', handler: spendCommand, keyless: ['--workspace'],
+        group: 'Money', summary: 'what you spent, and what phantom-1 saved',
         help: `  spend [--from <date>] [--to <date>]  what this key spent, by model and day, and what phantom-1
                                     saved; dates are UTC days as YYYY-MM-DD, default this month
   spend --workspace                 every key in the workspace by name (needs phantom login)`,
     },
     {
         name: 'plan', handler: planCommand,
-        help: `  plan [status]                     this key's Pro or Max plan and how much of the week is used
-  plan pro | max [--no-browser]     print a Stripe Checkout link that puts the plan on this key
-                                    and open it
+        group: 'Money', summary: 'your Pro or Max plan: status, buy, manage',
+        help: `  plan [status]                     this workspace's Pro or Max plan, how much of the week is used,
+                                    and what each plan costs
+  plan pro | max [--no-browser]     open Stripe Checkout to put the plan on this workspace (every
+                                    key in it); at a terminal, it says the price and asks first
   plan manage [--no-browser]        the same for Stripe's billing page: card, switch plan, cancel`,
     },
     {
         name: 'key', advanced: true, handler: keyCommand, keyless: true,
-        help: `  key list [--balance]              saved keys, by name and id
+        group: 'More', summary: 'older names for keys saved, save, show and rm',
+        help: `  key list | save | show | rm       older names for keys saved, keys save, keys show, keys rm
+  key list [--balance]              saved keys, by name and id
   key save <name> [key]             save a key by name (prompts if no key is given)
   key show [name]                   print a saved key, for PHANTOM_API_KEY=$(...);
                                     no name prints the key phantom is using
@@ -101,6 +117,7 @@ export const COMMANDS = [
     },
     {
         name: 'route', handler: routeCommand,
+        group: 'Routing', summary: 'which models "auto" runs, and rules for picking',
         help: `  route [get]                       show which model "auto" runs, and why
   route set --models a,b,c          models for "auto", first is the default
             [--applies-to auto|all] [--on-empty stop|cheapest] [--fallback]
@@ -117,6 +134,7 @@ export const COMMANDS = [
     },
     {
         name: 'lineup', handler: lineupCommand,
+        group: 'Routing', summary: 'the model phantom-1 runs in each tier',
         help: `  lineup [get]                      show the model phantom-1 runs in each tier, and the choices
   lineup set --economy <model>      pick the model for a tier; "default" goes back to the default
              [--standard <model>] [--frontier <model>]
@@ -127,17 +145,21 @@ export const COMMANDS = [
     },
     {
         name: 'logout', handler: logoutDispatch, keyless: true,
-        help: `  logout                            forget workspace access and the default saved key`,
+        group: 'More', summary: 'sign out on this computer',
+        help: `  logout                            sign out: forget workspace access and the default saved key
+  logout --all                      also forget every key saved here by name`,
     },
     {
         name: 'setup', handler: setupCommand, keyless: true,
+        group: 'Start', summary: 'sign in and connect your coding agents',
         help: `  setup                             set up every agent found: install the skill and
                                     point its model calls at Phantom AI; shows each
                                     file's changes and asks first. With no key yet,
                                     signs in first (in a terminal)
         [--yes]                     don't ask
         [--no-browser]              print the sign-in link instead of opening it
-        [--dry-run]                 show the changes, write nothing
+        [--dry-run]                 preview the changes without making them
+        [--diff]                    show every line each file gains or loses
         [--json]                    print JSON in a terminal too (a pipe always gets JSON)
         [--model <id>]              the model each agent starts on (default ${SETUP_MODEL})
   setup --agent <name>              install the skill for one agent, without asking:
@@ -150,6 +172,7 @@ export const COMMANDS = [
     },
     {
         name: 'verify', advanced: true, handler: verifyCommand, keyless: ['--receipt'],
+        group: 'More', summary: 'check a signed receipt',
         help: `  verify --model <id>               make one tiny call and check its signed receipt
                                     names the model you asked for (costs a fraction of a cent)
   verify --receipt <receipt>        check a receipt you already have`,

package/dist/cli/help.mjs

@@ -1,5 +1,5 @@
 import { DEFAULT_BASE_URL } from "../core/request.mjs";
-import { COMMANDS } from "./commands.mjs";
+import { COMMANDS, HELP_GROUPS } from "./commands.mjs";
 /**
  * Every environment variable phantom reads. The Environment section of HELP is
  * built from this list.
@@ -19,7 +19,7 @@ function envHelp() {
 }
 /** Full command reference, printed by `phantom --help --all`. */
 export const HELP = `
-phantom — AI inference for your coding agents
+phantom — points your coding agents at Phantom AI
 
 Commands:
 ${COMMANDS.map((command) => command.help).join('\n')}
@@ -32,6 +32,27 @@ Flags:
 
 ${envHelp()}
 `.trim();
-/** Workflow help printed by default; command definitions remain the source of usage. */
-export const PRIMARY_HELP = HELP.replace(COMMANDS.map((command) => command.help).join('\n'), COMMANDS.filter((command) => !command.advanced).map((command) => command.help).join('\n') +
-    '\n\nAdvanced: phantom --help --all (receipts and verification)');
+/** The order commands take inside their group in the short help: the one most people need first. Others follow in list order. */
+const FIRST = ['setup', 'login', 'claude', 'codex', 'pi', 'balance', 'fund', 'spend', 'plan'];
+const rank = (name) => (FIRST.includes(name) ? FIRST.indexOf(name) : FIRST.length);
+/** One row of the short help: a command name in its column, then what it does. */
+const helpRow = (name, summary) => `  ${name.padEnd(20)}${summary}`;
+/**
+ * The help printed by default: each command in one line, under a heading for
+ * what it's for, so it fits on one screen. The three agents share one row.
+ * `phantom <command> --help` and `--help --all` keep the full usage.
+ */
+export const PRIMARY_HELP = [
+    'phantom — points your coding agents at Phantom AI',
+    '',
+    ...HELP_GROUPS.flatMap((group) => {
+        const shown = COMMANDS.filter((command) => command.group === group && !command.advanced).sort((a, b) => rank(a.name) - rank(b.name));
+        const agents = shown.filter((command) => command.group === 'Run');
+        const rows = group === 'Run'
+            ? [helpRow(agents.map((command) => command.name).join(', '), 'start that agent on Phantom AI')]
+            : shown.map((command) => helpRow(command.name, command.summary));
+        return rows.length ? [group.toUpperCase(), ...rows, ''] : [];
+    }),
+    'phantom <command> --help shows its flags. phantom --help --all lists every flag,',
+    'the advanced commands (receipts and verification) and the environment variables.',
+].join('\n');