@phantomcodes/cli 1.2.3 → 1.2.4

package/README.md

@@ -74,7 +74,7 @@ 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
 ```
@@ -175,7 +175,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 +187,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,7 +2,7 @@ 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";
@@ -78,7 +78,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 +115,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 +125,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 +155,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');

package/dist/cli/run.mjs

@@ -1,7 +1,11 @@
 import { VERSION } from "../core/version.mjs";
 import { nodeTrustWarning } from "../core/node-trust.mjs";
-import { die } from "../core/errors.mjs";
-import { handleError, parseFlags } from "../core/helpers.mjs";
+import { die, NO_KEY } from "../core/errors.mjs";
+import { colorOn } from "../core/style.mjs";
+import { ALIASES, closestCommand, commandFromWords, startScreen } from "./start.mjs";
+import { BackToMenu } from "../core/pick.mjs";
+import { runApp } from "./app.mjs";
+import { handleError, parseFlags, pickIo } from "../core/helpers.mjs";
 import { resolveApiKey } from "../keys/saved.mjs";
 import { COMMANDS } from "./commands.mjs";
 import { HELP, PRIMARY_HELP } from "./help.mjs";
@@ -17,6 +21,16 @@ import { LEGACY_SETUP_HINT, legacySetupFound } from "../setup/legacy.mjs";
  * @param node The Node version it runs on; one too old to reject forged
  *   eMudhra certificates gets a warning on stderr first.
  */
+/**
+ * Every flag phantom reads: each one a command's help names, plus the flags
+ * every command takes and two retired ones that explain themselves. A typo
+ * such as --yse is refused instead of quietly ignored, which in CI would
+ * otherwise drop the flag without a word.
+ */
+const KNOWN_FLAGS = new Set([
+    ...COMMANDS.flatMap((command) => [...command.help.matchAll(/--([a-z][a-z0-9-]*)/g)].map((m) => m[1])),
+    'table', 'json', 'help', 'all', 'version', 'mcp', 'pay', 'mpp',
+]);
 export async function run(argv = process.argv.slice(2), env = process.env, io = {
     stdout: (s) => process.stdout.write(s),
     stderr: (s) => process.stderr.write(s),
@@ -30,23 +44,12 @@ export async function run(argv = process.argv.slice(2), env = process.env, io =
         io.stdout(VERSION + '\n');
         return 0;
     }
-    const THREE_STEPS_GUIDE = `
-phantom — prepaid AI inference for coding agents
-
-Get started in three steps:
-  1. Connect your account:
-     phantom login
-
-  2. Fund your balance:
-     phantom fund --amount 10 --card
-     (or phantom fund --amount 10 --coin usdc)
-
-  3. Run your coding agent:
-     phantom claude
-     (or phantom codex, phantom pi)
-
-Run phantom --help for all commands.
-`.trim();
+    // Words people type for a command run as that command: `phantom undo` is setup --restore,
+    // `phantom help setup` is setup --help, and `phantom start` opens the menu.
+    if (argv[0] === 'help' && COMMANDS.some((c) => c.name === argv[1]))
+        argv = [argv[1], '--help'];
+    else if (argv[0] && Object.hasOwn(ALIASES, argv[0]))
+        argv = [...ALIASES[argv[0]], ...(argv[0] === 'help' ? [] : argv.slice(1))];
     // `--help` anywhere before a `--` asks for help, so `phantom setup --help`
     // prints it rather than running setup.
     const own = argv.includes('--') ? argv.slice(0, argv.indexOf('--')) : argv;
@@ -56,32 +59,56 @@ Run phantom --help for all commands.
         io.stderr(LEGACY_SETUP_HINT + '\n');
     }
     if (argv.length === 0) {
-        io.stdout(THREE_STEPS_GUIDE + '\n');
-        return 0;
+        const signedIn = Boolean(resolveApiKey(env));
+        const pick = pickIo({ io, env });
+        if (!pick) {
+            io.stdout(startScreen(env, colorOn(env, io.stdoutIsTTY), signedIn) + '\n');
+            return 0;
+        }
+        // At a terminal, phantom alone is an app you stay in: a menu, each command's result, and what to do next.
+        return runApp(env, pick, io.stderr, (next) => run(next, env, { ...io, fromMenu: true }, node));
     }
     if (own.includes('--help') || own.includes('-h')) {
         const commandHelp = COMMANDS.find((entry) => entry.name === own[0])?.help;
-        io.stdout((own.includes('--all') ? HELP : commandHelp?.trim() ?? PRIMARY_HELP) + '\n');
+        io.stdout((own.includes('--all') ? HELP : commandHelp?.replace(/\s+$/, '') ?? PRIMARY_HELP) + '\n');
         return 0;
     }
     try {
         const command = COMMANDS.find((entry) => entry.name === argv[0]);
-        if (!command)
-            die(`Unknown command: ${argv[0]}. Run with --help for usage.`);
+        if (!command) {
+            // A near miss ("stup"), then a word in a sentence ("how do i add money"), then the way in.
+            const guess = closestCommand(argv[0], COMMANDS.map((entry) => entry.name)) ?? commandFromWords(argv);
+            die(guess ? `Unknown command "${argv[0]}". Did you mean phantom ${guess}?` : `Unknown command "${argv[0]}". Try phantom (a menu), phantom setup, or phantom --help for every command.`);
+        }
         const keyless = command.keyless === true ||
             (command.keyless?.some((flag) => own.slice(1).some((arg) => arg === flag || arg.startsWith(flag + '='))) ?? false);
         const apiKey = keyless ? '' : resolveApiKey(env);
         if (!apiKey && !keyless)
-            die('No API key. Set PHANTOM_API_KEY or run: phantom login');
+            die(NO_KEY);
         const subcommand = argv[1] && !argv[1].startsWith('--') ? argv[1] : undefined;
         const flagArgs = subcommand ? argv.slice(2) : argv.slice(1);
+        // Flags after -- belong to the agent phantom starts, so only the ones before it are checked.
         const flags = parseFlags(flagArgs);
-        const table = Boolean(flags['table']);
+        const ownFlags = parseFlags(flagArgs.includes('--') ? flagArgs.slice(0, flagArgs.indexOf('--')) : flagArgs);
+        // claude, codex and pi hand their arguments to the agent, so they check their own.
+        const passesArgs = command.handler === COMMANDS.find((c) => c.name === 'claude')?.handler;
+        for (const name of passesArgs ? [] : Object.keys(ownFlags)) {
+            if (KNOWN_FLAGS.has(name))
+                continue;
+            const guess = closestCommand(name, [...KNOWN_FLAGS]);
+            die(`Unknown flag --${name} for phantom ${argv[0]}.${guess ? ` Did you mean --${guess}?` : ''} See phantom ${argv[0]} --help.`, 'unknown_flag');
+        }
+        // A person at a terminal reads each command's screen; a pipe (scripts, agents) or --json gets JSON.
+        const table = Boolean(flags['table']) || (Boolean(io.stdoutIsTTY) && !flags['json']);
         const baseUrl = env.PHANTOM_BASE_URL;
         const input = { argv, env, io, apiKey, subcommand, flags, table, baseUrl };
         return await command.handler(input);
     }
     catch (err) {
-        return handleError(err, io.stderr);
+        // Esc on the first step of a command the menu started: let the menu show again.
+        if (err instanceof BackToMenu && io.fromMenu)
+            throw err;
+        // A person at a terminal gets a sentence; scripts and agents reading stderr get JSON.
+        return handleError(err, io.stderr, { human: io.isTTY, env });
     }
 }