@phantomcodes/cli 1.2.3 → 1.2.5

package/dist/keys/command.mjs

@@ -1,7 +1,11 @@
+import { unknownSub } from "../cli/start.mjs";
 import { createInterface } from 'node:readline/promises';
-import { die } from "../core/errors.mjs";
+import { spawnSync } from 'node:child_process';
+import { die, NO_KEY } from "../core/errors.mjs";
 import { getBalance } from "../core/request.mjs";
-import { out } from "../core/helpers.mjs";
+import { out, showsScreen } from "../core/helpers.mjs";
+import { colorOn, paint } from "../core/style.mjs";
+import { balanceScreen, keySavedScreen, logoutScreen, savedKeysScreen } from "../cli/screens.mjs";
 import { resolveApiKey, readNamedKey, saveNamedKey, removeNamedKey, listNamedKeys, saveApiKey, removeApiKey } from "./saved.mjs";
 /** `--table` output for `balance`. */
 export function tableBalance(d) {
@@ -27,9 +31,10 @@ export function tableKeys(d) {
         .join('\n');
 }
 /** `phantom balance`: the key's credit and expiry. Run by `run()`. */
-export async function balanceCommand({ io, apiKey, table, baseUrl }) {
+export async function balanceCommand(input) {
+    const { io, apiKey, baseUrl, env } = input;
     const result = await getBalance(apiKey, baseUrl);
-    out(result, table, tableBalance, io.stdout);
+    out(result, showsScreen(input), (d) => balanceScreen(d, { env, color: colorOn(env, io.stdoutIsTTY) }), io.stdout);
     return 0;
 }
 /** `phantom key list|save|show|rm`: keys saved by name. Run by `run()`. */
@@ -47,10 +52,10 @@ export async function keyCommand({ argv, env, io, subcommand, flags, table, base
                     return { ...k, active: false };
                 }
             }));
-            out({ keys: withBalance }, table, tableKeys, io.stdout);
+            out({ keys: withBalance }, table, (d) => savedKeysScreen(d.keys, { env, color: colorOn(env, io.stdoutIsTTY) }), io.stdout);
         }
         else {
-            out(list, table, tableKeys, io.stdout);
+            out(list, table, (d) => savedKeysScreen(d.keys, { env, color: colorOn(env, io.stdoutIsTTY) }), io.stdout);
         }
     }
     else if (subcommand === 'save') {
@@ -68,14 +73,22 @@ export async function keyCommand({ argv, env, io, subcommand, flags, table, base
         if (!key.startsWith('sk-phantom-'))
             die('That is not a Phantom AI key. Keys start with sk-phantom-');
         await getBalance(key, baseUrl);
-        out(saveNamedKey(env, name, key), table, (d) => `saved           ${d.name}`, io.stdout);
+        out(saveNamedKey(env, name, key), table, (d) => keySavedScreen(d.name, { env, color: colorOn(env, io.stdoutIsTTY) }), io.stdout);
     }
     else if (subcommand === 'show') {
         // Raw, for PHANTOM_API_KEY=$(phantom key show <name>). With no name, the
         // key phantom itself would use, which is what Claude Code's apiKeyHelper runs.
         const key = name ? readNamedKey(env, name) : resolveApiKey(env);
         if (!key)
-            die('No API key. Set PHANTOM_API_KEY or run: phantom login');
+            die(NO_KEY);
+        // --copy: to the clipboard instead of the screen, for pasting into an app's settings (Cursor's API key box).
+        if (flags['copy']) {
+            const copied = process.platform === 'darwin' ? spawnSync('pbcopy', { input: key }).status === 0 : false;
+            if (!copied)
+                die('Copying needs pbcopy, which is on every Mac. Elsewhere: phantom keys show | your clipboard tool.', 'copy_unavailable');
+            io.stderr(`  ${paint(env, colorOn(env, io.isTTY)).lime('✓')} Copied your key. Paste it where it's asked for; it works like a password.\n`);
+            return 0;
+        }
         io.stdout(key + '\n');
     }
     else if (subcommand === 'rm') {
@@ -84,7 +97,7 @@ export async function keyCommand({ argv, env, io, subcommand, flags, table, base
         out(removeNamedKey(env, name), table, (d) => `removed         ${d.removed}`, io.stdout);
     }
     else {
-        die(`Unknown key subcommand: ${subcommand}`);
+        die(unknownSub('key', String(subcommand), ['list', 'save', 'show', 'rm']), 'key_usage');
     }
     return 0;
 }
@@ -106,11 +119,22 @@ export async function loginCommand({ env, io, subcommand, table, baseUrl }) {
     // Check the key works before saving it.
     const balance = await getBalance(key, baseUrl);
     const saved = saveApiKey(env, key);
-    out({ ...saved, ...balance }, table, (d) => `saved           ${d.saved}\n${tableBalance(d)}`, io.stdout);
+    out({ ...saved, ...balance }, table, (d) => `\n  ${paint(env, colorOn(env, io.stdoutIsTTY)).lime('✓')} Key saved.\n${balanceScreen(d, { env, color: colorOn(env, io.stdoutIsTTY) })}`, io.stdout);
     return 0;
 }
-/** `phantom logout`: forgets the login key. Run by `run()`. */
-export async function logoutCommand({ env, io, table }) {
-    out(removeApiKey(env), table, (d) => `removed         ${d.removed}`, io.stdout);
+/**
+ * `phantom logout`: forgets the login key. `forgotWorkspace` says whether the
+ * workspace sign-in was forgotten too, so the screen doesn't say nothing changed. Run by `run()`.
+ */
+export async function logoutCommand({ env, io, table, flags }, forgotWorkspace = false) {
+    const result = removeApiKey(env);
+    // --all also forgets the keys saved by name; without it they stay, and the screen says so.
+    const named = listNamedKeys(env).keys.map((k) => k.name);
+    if (flags['all'])
+        for (const name of named)
+            removeNamedKey(env, name);
+    const kept = flags['all'] ? [] : named;
+    const removedNamed = flags['all'] ? named : [];
+    out({ ...result, removed_named: removedNamed, kept_named: kept }, table, (d) => logoutScreen(d.removed || forgotWorkspace || removedNamed.length > 0, { env, color: colorOn(env, io.stdoutIsTTY), kept, removedNamed }), io.stdout);
     return 0;
 }

package/dist/phantom.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * phantom: prepaid AI inference for coding agents with Phantom AI.
+ * phantom: points your coding agents at Phantom AI.
  *
  * Keys, money and setup for any AI agent: a Phantom AI key, model routing,
  * and receipts that show which model answered. It runs as a CLI and through

package/dist/plan/command.mjs

@@ -1,5 +1,9 @@
+import { unknownSub } from "../cli/start.mjs";
+import { colorOn } from "../core/style.mjs";
+import { linkScreen, planScreen } from "../cli/screens.mjs";
 import { die } from "../core/errors.mjs";
-import { openUrl, out } from "../core/helpers.mjs";
+import { pickIo, showsScreen, openUrl, out } from "../core/helpers.mjs";
+import { choose } from "../core/pick.mjs";
 import { request } from "../core/request.mjs";
 import { savedManagement } from "../workspace/command.mjs";
 /** The plan of the key's workspace and its week (GET /plan). */
@@ -37,8 +41,6 @@ export function tablePlan(d) {
         lines.push(`period    ends ${p.renews_at}`);
     return lines.join('\n');
 }
-/** What `phantom plan` accepts after `plan`. */
-const USAGE = 'Use phantom plan, phantom plan pro, phantom plan max or phantom plan manage.';
 /**
  * `phantom plan`: the plan of the key's workspace and how much of the week is
  * used. `phantom plan pro|max` prints a Stripe Checkout link that puts the
@@ -48,26 +50,42 @@ const USAGE = 'Use phantom plan, phantom plan pro, phantom plan max or phantom p
  * login` saved, since a key can't manage billing. Run by `run()`.
  */
 export async function planCommand(input) {
-    const { io, apiKey, table, baseUrl, flags, subcommand } = input;
+    const { io, apiKey, baseUrl, flags, subcommand, env } = input;
+    const table = showsScreen(input);
+    const style = { env, color: colorOn(env, io.stdoutIsTTY), opened: !flags['no-browser'] };
     const open = (url) => {
         if (!flags['no-browser'])
             openUrl(url);
     };
     if (subcommand === undefined || subcommand === 'status') {
-        out(await getPlan(apiKey, baseUrl), table, tablePlan, io.stdout);
+        out(await getPlan(apiKey, baseUrl), table, (d) => planScreen(d, style), io.stdout);
     }
     else if (subcommand === 'pro' || subcommand === 'max') {
+        // At a terminal, say what the plan costs and covers, and ask, before sending anyone to pay.
+        const pick = pickIo(input);
+        if (pick) {
+            const offer = (await getPlan(apiKey, baseUrl)).prices?.[subcommand];
+            const what = offer ? `$${offer.usd_per_month} a month, paying for $${offer.week_limit_usd} of model cost a week, for every key in this workspace` : 'for every key in this workspace';
+            const go = await choose(pick, `Start ${subcommand === 'max' ? 'Max' : 'Pro'}?`, [
+                { label: 'Open Stripe to pay', hint: what, value: true },
+                { label: 'Cancel', hint: 'nothing is charged', value: false },
+            ]);
+            if (!go) {
+                io.stderr('  Nothing was charged.\n');
+                return 0;
+            }
+        }
         const result = await planCheckout(apiKey, subcommand, baseUrl);
-        out(result, table, (d) => `Open this link to pay: ${d.checkout_url}`, io.stdout);
+        out(result, table, (d) => linkScreen(`Start ${subcommand === 'max' ? 'Max' : 'Pro'} on Stripe`, d.checkout_url, ['Once it goes through:', 'phantom plan'], style), io.stdout);
         open(result.checkout_url);
     }
     else if (subcommand === 'manage') {
         const result = await planPortal(savedManagement(input) ?? apiKey, baseUrl);
-        out(result, table, (d) => `Open this link to manage billing: ${d.portal_url}`, io.stdout);
+        out(result, table, (d) => linkScreen('Manage billing on Stripe: card, switch plan, cancel', d.portal_url, null, style), io.stdout);
         open(result.portal_url);
     }
     else {
-        die(`Unknown plan command "${subcommand}". ${USAGE}`, 'plan_usage');
+        die(unknownSub('plan', String(subcommand), ['status', 'pro', 'max', 'manage']), 'plan_usage');
     }
     return 0;
 }

package/dist/setup/agents.mjs

@@ -8,10 +8,11 @@ import { SETUP_MODEL, agentBaseUrl, readText, configHome, onPath, phantomCommand
 import { jsonObject, jsonEdit, tomlSet, tomlRemoveOurs, yamlSetTop, yamlAddModel, yamlRemoveOurs } from "./editors.mjs";
 // ── Manual Provider Helper ───────────────────────────────────────────────────
 /** An agent whose model settings live on its own settings screen: setup prints the steps. */
-export function manualProvider(where, steps) {
+export function manualProvider(where, steps, note) {
     return (ctx, off) => ({
         edits: [],
-        result: { settings: where, on: false, warnings: [], manual: off ? [`Remove the Phantom AI settings in ${where}.`] : steps(ctx) },
+        // The note is something to know, not a step to do, so it shows apart from the numbered steps.
+        result: { settings: where, on: false, warnings: off || !note ? [] : [note], manual: off ? [`Remove the Phantom AI settings in ${where}.`] : steps(ctx) },
     });
 }
 // ── Codex ────────────────────────────────────────────────────────────────────
@@ -76,7 +77,7 @@ export function claudePlan(env, opts) {
         };
     }
     if (!resolveApiKey(env))
-        die('No API key to give Claude Code. Run: phantom login', 'no_key');
+        die('No Phantom key yet to give Claude Code. Run phantom login to sign in, then run this again.', 'no_key');
     const baseUrl = agentBaseUrl(env, 'claude-code');
     // `phantom` if it's installed, else this very phantom by absolute path: Claude Code
     // runs the helper outside this shell, so a relative or npx path won't do.
@@ -87,7 +88,8 @@ export function claudePlan(env, opts) {
         ANTHROPIC_API_KEY: '',
         ENABLE_TOOL_SEARCH: 'true',
         CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY: '1',
-        ...(opts.model ? { ANTHROPIC_MODEL: opts.model } : {}),
+        // phantom-1 unless a model is named, as Codex gets: it runs free until there is credit.
+        ANTHROPIC_MODEL: opts.model ?? 'claude-code/phantom-1',
     };
     const changes = [[['apiKeyHelper'], `${phantomCommand(opts.onPath ?? onPath)} key show`], ...Object.entries(set).map(([k, v]) => [['env', k], v])];
     // A token outranks apiKeyHelper, and would send a non-Phantom key.
@@ -310,6 +312,44 @@ export function clineProvider(ctx, off) {
         },
     };
 }
+// ── Gemini CLI ───────────────────────────────────────────────────────────────
+/** Gemini CLI's folder: `.gemini` in `$GEMINI_CLI_HOME`, else in the home folder. */
+export function geminiDir(env, home) {
+    return path.join(env.GEMINI_CLI_HOME?.trim() ? env.GEMINI_CLI_HOME : home, '.gemini');
+}
+/**
+ * Gemini CLI speaks Google's API, which Phantom AI serves at `/gemini-cli`.
+ * The shell block sets GOOGLE_GEMINI_BASE_URL to it and GEMINI_API_KEY to
+ * the Phantom key; `settings.json` in Gemini CLI's folder picks API key
+ * sign-in (`security.auth.selectedType`) and the model (`model.name`).
+ * `--provider off` takes out a phantom model; the sign-in choice stays, and
+ * `phantom setup --restore` puts the file back as it was.
+ */
+export function geminiProvider(ctx, off) {
+    const file = path.join(geminiDir(ctx.env, ctx.home), 'settings.json');
+    const text = readText(file);
+    const settings = jsonObject(file, text);
+    if (off) {
+        const ours = typeof settings.model?.name === 'string' && settings.model.name.startsWith('phantom-');
+        const alone = Object.keys(settings.model ?? {}).length === 1;
+        return offResult('Gemini CLI', file, text, ours ? jsonEdit(file, text, [[alone ? ['model'] : ['model', 'name'], undefined]]) : text);
+    }
+    const model = ctx.model ?? SETUP_MODEL;
+    const changes = [
+        [['security', 'auth', 'selectedType'], 'gemini-api-key'],
+        [['model', 'name'], model],
+    ];
+    return {
+        edits: [{ file, after: jsonEdit(file, text, changes) }],
+        result: {
+            settings: file,
+            on: true,
+            base_url: agentBaseUrl(ctx.env, 'gemini-cli'),
+            model,
+            warnings: ['Gemini CLI reads its key from the shell; open a new terminal before running it. Other programs that read GEMINI_API_KEY get the Phantom key too'],
+        },
+    };
+}
 // ── Registry ─────────────────────────────────────────────────────────────────
 /**
  * The agents `phantom setup` knows, in the order setup runs them. Adding an agent
@@ -354,13 +394,12 @@ export const SETUP_AGENTS = {
         home: '.cursor',
         /** ~/.cursor/skills */
         skills: '.cursor/skills',
+        // Three short steps; the key gets copied without being shown (phantom's menu has "Copy my key").
         provider: manualProvider('Cursor Settings, Models', (ctx) => [
             'Open Cursor Settings (Cmd+Shift+J on macOS), then Models.',
-            `Under OpenAI API Key, paste your Phantom AI key, then turn on Override OpenAI Base URL and set it to ${agentBaseUrl(ctx.env, 'cursor')}`,
-            'Copy the key without showing it: phantom key show | pbcopy',
-            `Use Add model to add ${ctx.model ?? SETUP_MODEL} and any other Phantom AI model ids you want in the picker.`,
-            'While the override is on, Cursor\'s own non-OpenAI models stop working; turn it off to go back. Tab completions never use your own key.',
-        ]),
+            `Paste your Phantom AI key under OpenAI API Key (copy it with "Copy my key" in phantom's menu, or phantom keys show --copy), then turn on Override OpenAI Base URL and set it to ${agentBaseUrl(ctx.env, 'cursor')}`,
+            `Under Add model, add ${ctx.model ?? SETUP_MODEL}.`,
+        ], "While the override is on, Cursor's own non-OpenAI models stop working; turn it off to go back. Tab completions never use your key."),
         shellEnv: () => ({}),
     },
     /** opencode. */
@@ -418,6 +457,20 @@ export const SETUP_AGENTS = {
         home: '.cline',
         provider: clineProvider,
     },
+    /** Gemini CLI. Its address and key come from the shell block; settings.json picks the sign-in and model. */
+    gemini: {
+        label: 'Gemini CLI',
+        /** ~/.gemini, or under $GEMINI_CLI_HOME */
+        home: '.gemini',
+        detect: (env, home) => existsSync(geminiDir(env, home)),
+        /** ~/.agents/skills, which Gemini CLI reads as well as ~/.gemini/skills */
+        skills: '.agents/skills',
+        provider: geminiProvider,
+        shellEnv: (ctx) => ({
+            GOOGLE_GEMINI_BASE_URL: agentBaseUrl(ctx.env, 'gemini-cli'),
+            GEMINI_API_KEY: '$PHANTOM_API_KEY',
+        }),
+    },
 };
 export const SETUP_NAMES = Object.keys(SETUP_AGENTS);
 /** `a, b or c`. */

package/dist/setup/apply.mjs

@@ -1,6 +1,7 @@
+import os from 'node:os';
 import path from 'node:path';
 import { createHash } from 'node:crypto';
-import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmdirSync, rmSync, writeFileSync } from 'node:fs';
 import { stateDir } from "../core/state.mjs";
 import { readText } from "./shared.mjs";
 import { jsonText } from "./editors.mjs";
@@ -52,28 +53,6 @@ export function lineDiff(before, after) {
     }
     return out.join('\n');
 }
-/** A plan as people read it: each file with its diff (keys masked), the skill in one line, then commands, skips and steps to do by hand. */
-export function setupPreview(plan) {
-    const parts = [];
-    for (const f of plan.files) {
-        if (f.skill)
-            parts.push(`${f.action === 'create' ? 'install' : 'update'} skill ${f.file}`);
-        else if (f.action === 'remove')
-            parts.push(`remove ${f.file}`);
-        else
-            parts.push(`${f.action} ${f.file}\n${maskKeys(lineDiff(f.before, f.after))}`);
-    }
-    for (const s of plan.skipped)
-        parts.push(`skip ${s.agent}: ${s.reason}`);
-    for (const a of plan.agents) {
-        const steps = a.provider?.manual ?? [];
-        if (steps.length)
-            parts.push([`${SETUP_AGENTS[a.agent].label}, by hand:`, ...steps.map((s, k) => `  ${k + 1}. ${s}`)].join('\n'));
-    }
-    for (const n of plan.notes)
-        parts.push(n);
-    return parts.length ? parts.join('\n\n') : 'Nothing to change.';
-}
 function backupsFile(env) {
     return path.join(stateDir(env), 'setup-backups.json');
 }
@@ -89,6 +68,10 @@ function writeBackups(env, entries) {
     mkdirSync(stateDir(env), { recursive: true, mode: 0o700 });
     writeFileSync(backupsFile(env), jsonText(entries), { mode: 0o600 });
 }
+/** Whether setup has written anything on this computer that undo could put back: it keeps a record of each file. */
+export function isSetUp(env) {
+    return Object.keys(readBackups(env)).length > 0;
+}
 const sha256 = (text) => createHash('sha256').update(text).digest('hex');
 /**
  * Writes a plan from {@link planSetup}. Before it edits a file it copies it
@@ -213,5 +196,25 @@ export function restoreSetup(env, opts = {}) {
     }
     if (!opts.dryRun && restored.length)
         writeBackups(env, backups);
+    // The phantom-ai skill is phantom's own file, kept out of the backups, so undo removes it here.
+    const home = env.HOME || os.homedir();
+    for (const [agent, spec] of Object.entries(SETUP_AGENTS)) {
+        if (!spec.skills || (opts.agent && opts.agent !== 'all' && agent !== opts.agent))
+            continue;
+        const skill = path.join(home, spec.skills, 'phantom-ai', 'SKILL.md');
+        // Two agents can share a skills folder (pi and Codex use ~/.agents/skills), so each file is listed once.
+        if (!existsSync(skill) || restored.some((r) => r.file === skill) || !/^name: phantom-ai$/m.test(readText(skill) ?? ''))
+            continue;
+        if (!opts.dryRun) {
+            rmSync(skill, { force: true });
+            try {
+                rmdirSync(path.dirname(skill));
+            }
+            catch {
+                // Not empty: something else lives there, so the folder stays.
+            }
+        }
+        restored.push({ file: skill, from: null });
+    }
     return { restored, skipped, ...(opts.dryRun ? { dry_run: true } : {}) };
 }

package/dist/setup/command.mjs

@@ -1,68 +1,68 @@
+import path from 'node:path';
+import { existsSync } from 'node:fs';
 import { createInterface } from 'node:readline/promises';
 import { die } from "../core/errors.mjs";
-import { out } from "../core/helpers.mjs";
+import { out, pickIo } from "../core/helpers.mjs";
+import { BackToMenu, checklist, choose } from "../core/pick.mjs";
 import { resolveApiKey } from "../keys/saved.mjs";
 import { workspaceLogin } from "../workspace/command.mjs";
 import { SETUP_AGENTS, SETUP_NAMES } from "./agents.mjs";
 import { planSetup } from "./plan.mjs";
-import { setupPreview, applySetup, previewSetup, restoreSetup } from "./apply.mjs";
-/** `--table` output for `setup`. */
-export function tableSetup(d) {
-    const r = d;
-    const pad = ''.padEnd(16);
-    const lines = r.agents.map((a) => {
-        const label = SETUP_AGENTS[a.agent]?.label ?? a.agent;
-        const p = a.provider;
-        return [
-            `${a.agent.padEnd(16)}${a.skill ? `skill ${r.dry_run || r.applied === false ? 'goes' : 'installed'} at ${a.skill}` : 'no skill (this agent does not read skills)'}`,
-            ...(!p
-                ? []
-                : p.manual
-                    ? [`${pad}set up by hand in ${p.settings}:`, ...p.manual.map((step, k) => `${pad}  ${k + 1}. ${step}`)]
-                    : p.on
-                        ? [
-                            `${pad}models via Phantom AI at ${p.base_url}${p.model ? `, model ${p.model}` : ''} (${p.settings})`,
-                            `${pad}restart ${label} to pick it up; undo with: phantom setup --agent ${a.agent} --provider off`,
-                        ]
-                        : [a.agent === 'claude' ? `${pad}models back to Anthropic (${p.settings})` : `${pad}Phantom AI settings removed (${p.settings})`]),
-            ...(p?.warnings ?? []).map((w) => `${pad}warning: ${w}`),
-        ].join('\n');
-    });
-    const files = (r.files ?? []).filter((f) => f.diff !== undefined);
-    if (files.length) {
-        lines.push('');
-        for (const f of files) {
-            lines.push(`${r.dry_run || r.applied === false ? `would ${f.action}` : `${f.action}d`} ${f.file}${f.backup ? ` (copy before: ${f.backup})` : ''}`);
-            if (f.diff && (r.dry_run || r.applied === false))
-                lines.push(f.diff.replace(/^/gm, '    '));
-        }
-    }
-    for (const s of r.skipped ?? [])
-        lines.push(`skipped ${s.agent}: ${s.reason}`);
-    for (const n of r.notes ?? [])
-        lines.push(n);
-    if (r.applied === false)
-        lines.push('Nothing was changed.');
-    // Agents that read the key from the shell only see it in a terminal opened after setup.
-    else if (!r.dry_run && (r.files ?? []).some((f) => f.agent === 'shell')) {
-        lines.push('', 'Open a new terminal before you start your agents, so they can read your Phantom AI key.');
-    }
-    return lines.join('\n');
+import { applySetup, previewSetup, restoreSetup } from "./apply.mjs";
+import { setupScreen } from "./screen.mjs";
+import { colorOn, paint, unstyled } from "../core/style.mjs";
+import { inApp } from "../cli/screens.mjs";
+import { brandIntro, motionOn, play, reveal } from "../core/motion.mjs";
+/** `--table` output for `setup`, and what a terminal shows: see {@link setupScreen}. */
+export function tableSetup(d, opts = {}) {
+    return setupScreen(d, opts);
 }
-/** `--table` output for `setup --restore`. */
-export function tableRestore(d) {
+/** `--table` output for `setup --restore`, and what a terminal shows: a ✓ per file put back, a ✗ per file left alone. */
+export function tableRestore(d, opts = {}) {
     const r = d;
+    const p = paint(opts.env ?? {}, Boolean(opts.color));
+    const home = opts.env?.HOME;
+    const short = (file) => (home && file.startsWith(home + '/') ? '~' + file.slice(home.length) : file);
+    if (!r.restored.length && !r.skipped.length)
+        return 'Nothing to restore.';
     const lines = [
-        ...r.restored.map((x) => `${r.dry_run ? 'would restore' : 'restored'} ${x.file}${x.from ? ` from ${x.from}` : ' (phantom created it, so it is removed)'}`),
-        ...r.skipped.map((x) => `skipped ${x.file}: ${x.reason}`),
+        ...r.restored.map((x) => {
+            const verb = x.from ? (r.dry_run ? 'puts back' : 'put back') : r.dry_run ? 'deletes' : 'removed';
+            const what = x.from ? `${verb} ${short(x.file)} as it was before setup` : `${verb} ${short(x.file)} (phantom made this file)`;
+            return `  ${r.dry_run ? p.dim('·') : p.lime('✓')} ${what}`;
+        }),
+        ...r.skipped.map((x) => `  ${p.red('✗')} left ${short(x.file)}: ${x.reason}`),
     ];
-    return lines.length ? lines.join('\n') : 'Nothing to restore.';
+    if (!r.dry_run && r.restored.length) {
+        // What undo leaves alone, so nobody thinks they're back to nothing when they're still signed in.
+        lines.push('', inApp() ? `  ${p.dim('Still here: your sign-in and saved keys. To remove those too, pick Sign out below.')}` : `  ${p.dim('Still here: your sign-in and saved keys. To remove those too:')} ${p.cyan('phantom logout --all')}`);
+        // Cursor was set up by hand, so undo can't reach it; say what to do there.
+        if (opts.env?.HOME && existsSync(path.join(opts.env.HOME, '.cursor')))
+            lines.push(`  ${p.dim("Cursor: if you set it up by hand, turn off Override OpenAI Base URL in Cursor Settings, Models.")}`);
+        lines.push(`  ${p.lime('→')} Restart your agents (and open a new terminal) so they go back to how they were.`);
+    }
+    return lines.join('\n');
 }
 /** `phantom setup`: plans, previews, asks, applies or restores agent setup. Plain setup with no key yet signs in first when it runs in a terminal. Run by `run()`. */
 export async function setupCommand(input) {
     const { env, io, flags } = input;
     // A person at a terminal gets the short summary; a pipe, or --json, gets JSON.
     const table = input.table || (Boolean(io.stdoutIsTTY) && !flags['json']);
+    const diff = Boolean(flags['diff']);
+    // The summary goes to stdout and the question to stderr, so each gets color only when it is a terminal.
+    const shown = (opts = {}) => (d) => tableSetup(d, { env, diff, color: colorOn(env, io.stdoutIsTTY), columns: process.stdout.columns, ...opts });
+    /**
+     * Prints a result to stdout: JSON for a pipe, the screen otherwise, played
+     * as a flipbook when motion is on. The header draws in on a preview; after
+     * the changes, each ✓ ticks in after the one before.
+     */
+    const emit = async (result) => {
+        if (!table || !motionOn(env, io.stdoutIsTTY))
+            return out(result, table, shown(), io.stdout);
+        const lines = shown()(result).split('\n');
+        const book = result.dry_run ? brandIntro(lines) : reveal(lines, (line) => (/^\s+\S*[✓!✗]/.test(unstyled(line)) ? 60 : 0));
+        await play(io.stdout, book, { rows: process.stdout.rows, skipOnKey: true });
+    };
     const agent = flags['agent'];
     if (agent === true)
         die(`--agent requires ${SETUP_NAMES.join(', ')} or all`);
@@ -76,8 +76,29 @@ export async function setupCommand(input) {
         die('--mcp has been removed. Phantom inference runs directly through phantom claude, phantom codex, or phantom pi.');
     const dryRun = Boolean(flags['dry-run']);
     if (flags['restore']) {
+        // At a terminal, undo shows what it will put back, and asks, the way setup asks before it changes anything.
+        const pick = !dryRun && !flags['yes'] ? pickIo(input) : null;
+        if (pick) {
+            const preview = restoreSetup(env, { agent, dryRun: true });
+            if (!preview.restored.length && !preview.skipped.length) {
+                io.stdout('  Nothing to undo: setup has no changes on this computer.\n');
+                return 0;
+            }
+            io.stderr(`\n${tableRestore(preview, { env, color: colorOn(env, io.isTTY) })}\n\n`);
+            // The marker starts on Cancel: undo can't itself be undone, so it takes a deliberate move.
+            const go = await choose(pick, 'Undo these changes?', [
+                { label: 'Undo them', hint: 'your agents go back to how they were', value: true },
+                { label: 'Cancel', hint: 'change nothing', value: false },
+            ], 1);
+            if (!go) {
+                if (go === null && io.fromMenu)
+                    throw new BackToMenu();
+                io.stderr('  Nothing was changed.\n');
+                return 0;
+            }
+        }
         const result = restoreSetup(env, { agent, dryRun });
-        out(result, table, tableRestore, io.stdout);
+        out(result, table, (d) => tableRestore(d, { env, color: colorOn(env, io.stdoutIsTTY) }), io.stdout);
         return result.skipped.length ? 1 : 0;
     }
     // Plain `phantom setup` sets up everything it finds and asks first. Any of
@@ -87,19 +108,90 @@ export async function setupCommand(input) {
     // get one in this run. Its words go to stderr; stdout stays setup's result.
     if (guided && !dryRun && io.isTTY && !resolveApiKey(env)) {
         await workspaceLogin({ ...input, io: { ...io, stdout: io.stderr }, flags: flags['no-browser'] ? { 'no-browser': true } : {} }, { inSetup: true });
+        // Sign-in was cancelled: stop here rather than set up the agents without a key.
+        if (!resolveApiKey(env)) {
+            io.stderr('  Nothing was changed.\n');
+            return 0;
+        }
     }
-    const plan = planSetup(env, {
+    const options = {
         agent,
         provider: guided || provider === true ? true : provider === 'off' ? 'off' : false,
         model: typeof model === 'string' ? model : undefined,
         guided,
-    });
+    };
+    const found = planSetup(env, options);
+    let plan = found;
+    // At a terminal, plain setup asks which of the agents it found to connect (all ticked, Space unticks),
+    // then whether to make the changes. Esc on the question goes back to the checklist.
+    const pick = guided && !flags['yes'] && !dryRun ? pickIo(input) : null;
+    const ticks = Boolean(pick) && found.agents.length > 1;
+    /** Shows the checklist, or returns false when Esc there means leave. */
+    const tick = async () => {
+        const only = await checklist(pick, 'Which agents should use Phantom AI?', found.agents.map((a) => ({ label: SETUP_AGENTS[a.agent].label, hint: a.provider ? 'skill and model settings' : 'skill', value: a.agent, checked: plan.agents.some((p) => p.agent === a.agent) })));
+        if (!only)
+            return false;
+        plan = planSetup(env, { ...options, only });
+        return true;
+    };
+    /** Esc on setup's first step: back to the menu when it started setup, otherwise stop with nothing changed. */
+    const leave = () => {
+        if (io.fromMenu)
+            throw new BackToMenu();
+        io.stderr('  Nothing was changed.\n');
+        return 0;
+    };
+    if (ticks && !(await tick()))
+        return leave();
+    /**
+     * Prints the result and gives the exit code: 1 when a file was skipped, or
+     * when there was no key so the agents weren't pointed at Phantom AI. A script
+     * checking only the exit code then can't mistake half a setup for all of it.
+     */
+    const finish = async (result) => {
+        const partial = guided && provider !== 'off' && !resolveApiKey(env);
+        await emit(partial ? { ...result, complete: false } : result);
+        return result.skipped || partial ? 1 : 0;
+    };
     if (dryRun) {
-        out(previewSetup(plan), table, tableSetup, io.stdout);
+        await emit(previewSetup(plan));
         return 0;
     }
     if (guided && !flags['yes'] && plan.files.length) {
-        io.stderr(setupPreview(plan) + '\n\n');
+        const preview = setupScreen(previewSetup(plan), { env, diff, color: colorOn(env, io.isTTY), columns: process.stderr.columns, mode: 'ask', hint: !(pick && !io.ask) });
+        // The question waits for the header and rows to finish drawing in.
+        if (motionOn(env, io.isTTY))
+            await play(io.stderr, brandIntro(preview.split('\n')), { rows: process.stderr.rows, skipOnKey: true });
+        else
+            io.stderr(preview + '\n');
+        io.stderr('\n');
+        // At a terminal: a choice instead of typing y or n, with a look at every line first if wanted.
+        if (pick && !io.ask) {
+            for (;;) {
+                const answer = await choose({ ...pick, esc: ticks || io.fromMenu ? 'back' : 'cancel' }, 'Make these changes?', [
+                    { label: 'Make these changes', value: 'yes' },
+                    { label: 'Show every line first', value: 'diff' },
+                    { label: 'Cancel', hint: 'change nothing', value: 'no' },
+                ]);
+                if (answer === 'diff') {
+                    io.stderr(setupScreen(previewSetup(plan), { env, diff: true, color: colorOn(env, io.isTTY), columns: process.stderr.columns, mode: 'ask' }) + '\n\n');
+                    continue;
+                }
+                // Esc: back to the checklist, then the preview again; or out, when there was no checklist.
+                if (answer === null) {
+                    if (!ticks || !(await tick()))
+                        return leave();
+                    io.stderr('\n' + setupScreen(previewSetup(plan), { env, diff, color: colorOn(env, io.isTTY), columns: process.stderr.columns, mode: 'ask', hint: false }) + '\n\n');
+                    continue;
+                }
+                if (answer !== 'yes') {
+                    await emit({ ...previewSetup(plan), dry_run: undefined, applied: false });
+                    return 0;
+                }
+                break;
+            }
+            return finish(applySetup(env, plan));
+        }
         const ask = io.ask ??
             (process.stdin.isTTY
                 ? async (q) => {
@@ -114,13 +206,12 @@ export async function setupCommand(input) {
                 : null);
         if (!ask)
             die('phantom setup changes the files above. Run it in a terminal to confirm, or add --yes (or --dry-run to only look)', 'confirm_needed');
-        const answer = await ask('Make these changes? [y/N] ');
+        const q = paint(env, colorOn(env, io.isTTY));
+        const answer = await ask(`  ${q.lime('?')} ${q.bold('Make these changes?')} ${q.dim('[y/N]')} `);
         if (!/^y(es)?$/i.test(answer.trim())) {
-            out({ ...previewSetup(plan), dry_run: undefined, applied: false }, table, tableSetup, io.stdout);
+            await emit({ ...previewSetup(plan), dry_run: undefined, applied: false });
             return 0;
         }
     }
-    const result = applySetup(env, plan);
-    out(result, table, tableSetup, io.stdout);
-    return result.skipped ? 1 : 0;
+    return finish(applySetup(env, plan));
 }

package/dist/setup/editors.mjs

@@ -373,7 +373,7 @@ export function shellBlock(env, fish, state, onPathFn = onPath) {
         '# Written by phantom setup. Sets PHANTOM_API_KEY to the key phantom uses when the',
         '# shell starts, for coding agents that read it. The key is not stored here.',
         `# agents: ${state.agents.join(' ')}`,
-        '# Undo: phantom setup --provider off',
+        '# Undo: phantom setup --restore',
     ];
     if (fish) {
         return [