@phantomcodes/cli 1.2.6 → 1.2.8

package/README.md

@@ -68,7 +68,11 @@ Mistral Vibe and Zed. Cursor, VS Code, JetBrains AI Assistant, Warp and Trae
 keep these settings on their own settings screens, so setup prints the steps;
 pi gets the agent skill.
 
-Preview without changing files with `phantom setup --dry-run`. The Phantom CLI keeps backups;
+Preview without changing files with `phantom setup --dry-run`. To leave your
+shell startup file alone, untick "Your shell" in the checklist or pass
+`--no-shell`; setup then prints the lines to add yourself. Cap what the key can spend each
+month with `phantom setup --limit 20` (`--limit none` removes it); at a terminal,
+setup asks once when the key has no cap. The Phantom CLI keeps backups;
 undo the changes with `phantom setup --restore`.
 
 ## Connect for one run
@@ -178,6 +182,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` |
+| Providers that answer soonest | `phantom route set --sort fast` (`--sort default` for cheapest first) |
 | Run inference | `phantom claude`, `phantom codex`, `phantom pi` |
 | 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` |

package/dist/cli/app.mjs

@@ -6,6 +6,7 @@ import { resolveApiKey } from "../keys/saved.mjs";
 import { hideHints } from "./screens.mjs";
 import { startHeader } from "./start.mjs";
 import { COMMANDS } from "./commands.mjs";
+import { FREE_LINE } from "../core/free.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'] },
@@ -17,7 +18,7 @@ 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: 'Set up my coding agents', hint: 'sign in and connect them, 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,
@@ -26,7 +27,7 @@ export function mainMenu(s) {
     // 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'] } }]),
+        ...(s.setUp ? [] : [{ label: 'Finish setting up my agents', hint: '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'] } },
@@ -105,7 +106,9 @@ export async function runApp(env, pick, write, runCommand, installed = onPath) {
             // 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`);
+            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`);
+            // Before signing in, the one line that says what free means, whole, since it is why most people came.
+            write(s.signedIn ? '\n' : `  ${p.lime('Free to start:')} ${FREE_LINE}.\n\n`);
             let action = await choose({ ...pick, esc: 'quit' }, 'What would you like to do?', mainMenu(s));
             if (action === null)
                 return 0;

package/dist/cli/commands.mjs

@@ -119,6 +119,9 @@ 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 --sort fast|cheap|throughput|default
+                                    which providers serve this key's models first: fast
+                                    starts answering soonest; cheap is the default
   route set --models a,b,c          models for "auto", first is the default
             [--applies-to auto|all] [--on-empty stop|cheapest] [--fallback]
             [--stick-minutes n]  keep a conversation's model this long (default 5)
@@ -160,6 +163,9 @@ export const COMMANDS = [
         [--no-browser]              print the sign-in link instead of opening it
         [--dry-run]                 preview the changes without making them
         [--diff]                    show every line each file gains or loses
+        [--no-shell]                leave your shell startup file alone and list
+                                    the lines to add yourself
+        [--limit <USD|none>]        cap what this key can spend each month
         [--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:

package/dist/cli/run.mjs

@@ -1,7 +1,7 @@
 import { VERSION } from "../core/version.mjs";
 import { nodeTrustWarning } from "../core/node-trust.mjs";
 import { die, NO_KEY } from "../core/errors.mjs";
-import { colorOn } from "../core/style.mjs";
+import { colorOn, fitText } from "../core/style.mjs";
 import { ALIASES, closestCommand, commandFromWords, startScreen } from "./start.mjs";
 import { BackToMenu } from "../core/pick.mjs";
 import { runApp } from "./app.mjs";
@@ -41,7 +41,17 @@ export async function run(argv = process.argv.slice(2), env = process.env, io =
     stderr: (s) => process.stderr.write(s),
     isTTY: Boolean(process.stderr.isTTY),
     stdoutIsTTY: Boolean(process.stdout.isTTY),
+    columns: process.stdout.columns || process.stderr.columns,
 }, node = process.versions.node) {
+    // A line wider than the terminal breaks at a word, under its own column, rather than wherever the edge falls.
+    if (io.columns) {
+        const { columns, stdout, stderr } = io;
+        io = {
+            ...io,
+            ...(io.stdoutIsTTY ? { stdout: (s) => stdout(fitText(s, columns)) } : {}),
+            ...(io.isTTY ? { stderr: (s) => stderr(fitText(s, columns)) } : {}),
+        };
+    }
     const unsafe = nodeTrustWarning(node);
     if (unsafe)
         io.stderr(unsafe);

package/dist/cli/screens.mjs

@@ -100,8 +100,12 @@ export function spendScreen(s, style = {}) {
     if (s.keys.length > 1) {
         lines.push('', ...caption(p, w, 'BY KEY'));
         for (const k of s.keys) {
-            const saved = k.saved_usd ? p.lime(`  saved ${usd(k.saved_usd)}`) : '';
-            lines.push(`  ${k.name.slice(0, LABEL - 1).padEnd(LABEL + BAR + 2)}${usd(k.spent_usd).padStart(8)}  ${p.dim(plural(k.calls, 'call'))}${saved}${k.active ? '' : p.dim('  revoked or rotated')}`);
+            const savedText = k.saved_usd ? `  saved ${usd(k.saved_usd)}` : '';
+            const offText = k.active ? '' : '  revoked or rotated';
+            // The dollars line up with the model rows above, unless that pushes the row past the window's edge.
+            const tail = 8 + 2 + plural(k.calls, 'call').length + savedText.length + offText.length;
+            const pad = Math.max(LABEL, Math.min(LABEL + BAR + 2, widthOf(style) - 2 - tail));
+            lines.push(`  ${k.name.slice(0, LABEL - 1).padEnd(pad)}${usd(k.spent_usd).padStart(8)}  ${p.dim(plural(k.calls, 'call'))}${savedText ? p.lime(savedText) : ''}${offText ? p.dim(offText) : ''}`);
         }
     }
     if (!s.total.calls)
@@ -116,12 +120,12 @@ function keyRows(p, keys) {
     if (!keys.length)
         return [`  ${p.dim('No keys yet.')}`];
     return keys.map((k) => {
-        const limit = k.limit_usd != null ? `limit ${usd(k.limit_usd)}` : k.budget_usd != null ? `${usd(k.budget_usd)} every ${plural(k.period_days ?? 30, 'day')}` : 'no limit';
+        const limit = k.limit_usd != null ? `limit ${usd(k.limit_usd)}` : k.budget_usd != null ? `${usd(k.budget_usd)} per ${plural(k.period_days ?? 30, 'day')}` : 'no limit';
         // A revoked or rotated key gets a hollow mark and the word off at the end, so the columns stay in line.
         const off = k.is_active === false;
         const mark = off ? p.dim('○') : p.lime('●');
         // The id's first 8 characters: enough for --id, which also takes the name.
-        return `  ${mark} ${clip(k.name ?? 'Key', 20).padEnd(21)}${p.dim((k.id ?? '').slice(0, 8).padEnd(10))}${p.dim((k.prefix ?? '').slice(0, 18).padEnd(20))}${usd(k.spent_usd ?? 0).padStart(8)}  ${p.dim(limit)}${off ? `  ${p.dim('off')}` : ''}`;
+        return `  ${mark} ${clip(k.name ?? 'Key', 20).padEnd(21)}${p.dim((k.id ?? '').slice(0, 8).padEnd(9))}${p.dim((k.prefix ?? '').slice(0, 18).padEnd(20))}${usd(k.spent_usd ?? 0).padStart(8)}  ${p.dim(limit)}${off ? `  ${p.dim('off')}` : ''}`;
     });
 }
 /** `phantom workspace`: the shared balance, each key, and the last few charges. */
@@ -154,6 +158,16 @@ export function signedInScreen(saved, style = {}) {
     const where = saved.saved_as === 'default' ? 'Your key is' : `Key "${saved.saved_as}" is`;
     return ['', `  ${p.lime('✓')} ${p.bold('Signed in.')} ${p.dim(`${where} saved in your ${saved.storage}.`)}`, ...next(p, 'Connect your coding agents:', 'phantom setup')].join('\n');
 }
+/** `phantom login` when this computer already has a key: say so, then how to switch or add one. */
+export function alreadySignedInScreen(keyIdShown, style = {}) {
+    const p = paint(style.env ?? {}, Boolean(style.color));
+    return [
+        '',
+        `  ${p.lime('✓')} ${p.bold('You are already signed in on this computer.')}${keyIdShown ? ` ${p.dim(`key ${keyIdShown}`)}` : ''}`,
+        ...next(p, 'Use another workspace: run phantom logout, then', 'phantom login'),
+        ...next(p, 'Add a second key here:', 'phantom login --save <name>'),
+    ].join('\n');
+}
 /** A ✓ line with an optional dim detail, for a change that worked. */
 function done(p, words, detail = '') {
     return `  ${p.lime('✓')} ${words}${detail ? `  ${p.dim(detail)}` : ''}`;
@@ -164,12 +178,15 @@ export function routeScreen(r, style = {}) {
     const w = ruleWidth(style);
     const lines = ['', ...caption(p, w, 'ROUTING', p.dim('how model "auto" picks for this key'))];
     const policy = r.route_policy;
-    if (!policy) {
-        lines.push('  No route policy, so model "auto" runs phantom-1, which picks a model for each request.');
-        lines.push(...next(p, 'Make one:', 'phantom route set --models a,b,c'));
+    const row = (label, value) => `  ${p.dim(label.padEnd(14))}${value}`;
+    // Which providers serve first holds for every request, routed or not.
+    const sortWords = { cost: 'cheapest first', ttft: 'fastest to start answering first', tps: 'most tokens a second first' };
+    const providers = row('providers', `${sortWords[policy?.sort ?? 'cost']}${policy?.sort ? '' : p.dim('  (the default)')}${policy?.zdr ? ', zero data retention only' : ''}${policy?.no_training ? ', no training on prompts' : ''}`);
+    if (!policy || !policy.models.length) {
+        lines.push('  No route policy, so model "auto" runs phantom-1, which picks a model for each request.', '', providers);
+        lines.push(...(policy?.sort ? next(p, 'Back to cheapest first:', 'phantom route set --sort default') : next(p, 'Providers that start answering soonest:', 'phantom route set --sort fast')));
         return lines.join('\n');
     }
-    const row = (label, value) => `  ${p.dim(label.padEnd(14))}${value}`;
     // One model a line, in the order "auto" tries them, so a long list doesn't wrap.
     policy.models.forEach((m, k) => lines.push(row(k === 0 ? 'models' : '', `${p.dim(`${k + 1}.`)} ${k === 0 ? `${p.bold(m)}  ${p.dim('the default')}` : m}`)));
     lines.push(row('applies to', policy.applies_to === 'all' ? 'every request' : 'requests for model "auto"'));
@@ -177,6 +194,7 @@ export function routeScreen(r, style = {}) {
     lines.push(row('a model fails', policy.fallback_on_error ? 'try the next one' : 'stop there'));
     const stick = policy.stick_minutes ?? 5;
     lines.push(row('conversations', stick ? `stay on their model for ${plural(stick, 'minute')}${policy.stick_by_prompt === false ? ' (by x-phantom-session only)' : ''}` : 'can change model every request'));
+    lines.push(providers);
     const rules = policy.rules ?? [];
     lines.push('', ...caption(p, w, 'RULES', p.dim(rules.length ? 'checked in order; the first that matches picks' : '')));
     if (!rules.length)

package/dist/cli/start.mjs

@@ -3,6 +3,7 @@
 // day to day. It reads no network, so it prints at once, even offline.
 import { brandHeader } from "../core/brand.mjs";
 import { paint } from "../core/style.mjs";
+import { FREE_LINE } from "../core/free.mjs";
 /** One row: a command in cyan, padded, then what it does. */
 const row = (p, command, about) => `  ${p.cyan(command.padEnd(18))}${about}`;
 /** An uppercase caption over a thin rule, like the site's section labels. */
@@ -15,7 +16,7 @@ export function startScreen(env, color, signedIn) {
     const p = paint(env, color);
     const lines = ['', ...brandHeader(p, color, '')];
     if (!signedIn) {
-        lines.push(...caption(p, 'START HERE'), row(p, 'phantom setup', 'signs you in and connects your coding agents'), `  ${' '.repeat(18)}${p.dim('phantom-1 is free to start: no credit needed')}`, '', `  Then use your agent as usual, or start it with ${p.cyan('phantom claude')}, ${p.cyan('phantom codex')} or ${p.cyan('phantom pi')}.`);
+        lines.push(...caption(p, 'START HERE'), row(p, 'phantom setup', 'signs you in and connects your coding agents'), `  ${' '.repeat(18)}${p.dim(FREE_LINE)}`, '', `  Then use your agent as usual, or start it with ${p.cyan('phantom claude')}, ${p.cyan('phantom codex')} or ${p.cyan('phantom pi')}.`);
     }
     else {
         lines.push(`  ${p.lime('✓')} Signed in.`, '', ...caption(p, 'EVERYDAY'), row(p, 'phantom claude', 'run Claude Code on Phantom AI (also codex, pi)'), row(p, 'phantom balance', 'your credit'), row(p, 'phantom spend', 'what you spent, and what phantom-1 saved'), row(p, 'phantom setup', 'connect more agents, or change how they run'));
@@ -67,7 +68,7 @@ export function startChoices(signedIn, setUp = signedIn) {
     const quit = { label: 'Quit', value: [] };
     if (!signedIn) {
         return [
-            { label: 'Set up my coding agents', hint: 'sign in and connect them (phantom-1 is free to start)', value: ['setup'] },
+            { label: 'Set up my coding agents', hint: 'sign in and connect them, free to start', value: ['setup'] },
             { label: 'Sign in only', hint: 'or save a Phantom key you already have', value: ['login'] },
             { label: 'See every command', value: ['--help'] },
             quit,

package/dist/core/free.mjs

@@ -0,0 +1,9 @@
+// What phantom-1 gives a key for free, said the same way on every screen that mentions it.
+/**
+ * Free phantom-1 requests a workspace gets each UTC day, before it has had $10
+ * of credit. Phantom's own limit is `FREE_ROUTER_CAPS.perDay` in the Phantom
+ * repo's `lib/config.ts`; change both together.
+ */
+export const FREE_REQUESTS_A_DAY = 50;
+/** The free offer in one line short enough for an 80-column terminal. */
+export const FREE_LINE = `phantom-1 runs free models, ${FREE_REQUESTS_A_DAY} requests a day, with no card`;

package/dist/core/style.mjs

@@ -34,3 +34,65 @@ export function paint(env, on) {
 }
 /** `text` without color codes, to measure how wide it prints. */
 export const unstyled = (text) => text.replace(/\x1b\[[0-9;]*m/g, '');
+/**
+ * One line of a screen, fitted to a terminal `columns` wide: a longer line
+ * breaks at spaces, and each piece after the first starts under the text it
+ * continues. That is the second column for a table row or a help entry
+ * (text after a run of two spaces), the words after a mark such as `✓ ` or
+ * `→ `, or else the line's own indent. A word longer than the room, such as
+ * a URL, stays whole. Color codes don't count toward the width.
+ */
+export function fitLine(line, columns) {
+    const seen = unstyled(line);
+    if (seen.length <= columns)
+        return line;
+    const lead = seen.length - seen.trimStart().length;
+    const column = /^(\s*\S.*?\s{2,})\S/.exec(seen)?.[1].length;
+    const mark = /^\s*[✓✗→·!◆?❯] /.exec(seen)?.[0].length;
+    const hang = column !== undefined && column <= columns / 2 ? column : (mark ?? lead);
+    const rows = [];
+    let row = '';
+    let width = 0;
+    // A command stays on one line to copy: `phantom` keeps the word after it, and a flag the word before.
+    const words = [];
+    for (const word of line.split(' ')) {
+        const last = words.length ? unstyled(words[words.length - 1]) : '';
+        if (words.length && word && (/(^|[^\w-])phantom$/.test(last) || /^-{1,2}[a-z]/.test(unstyled(word))))
+            words[words.length - 1] += ' ' + word;
+        else
+            words.push(word);
+    }
+    words.forEach((word, i) => {
+        const w = unstyled(word).length;
+        const blank = unstyled(row).trim() === '';
+        if (i > 0 && !blank && width + 1 + w > columns) {
+            rows.push(row.trimEnd());
+            row = ' '.repeat(hang) + word;
+            width = hang + w;
+        }
+        else if (i > 0 && blank && rows.length) {
+            row += word;
+            width += w;
+        }
+        else {
+            row += (i > 0 ? ' ' : '') + word;
+            width += (i > 0 ? 1 : 0) + w;
+        }
+    });
+    return [...rows, row.trimEnd()].join('\n');
+}
+/** Moves the cursor or redraws: text drawn in place (a menu, a spinner), which must not be wrapped. */
+const DRAWN = /\r|\x1b\[[0-9;?]*[A-HJKSTfhlsu]/;
+/**
+ * Text fitted to `columns` with {@link fitLine}, line by line. JSON (text
+ * that starts with `{` or `[`) and anything drawn in place come back as they
+ * are, since a break there would change what they mean.
+ */
+export function fitText(text, columns) {
+    if (!columns || DRAWN.test(text) || /^\s*[{[]/.test(text))
+        return text;
+    return text
+        .split('\n')
+        .map((l) => fitLine(l, columns))
+        .join('\n');
+}

package/dist/core/version.mjs

@@ -1,2 +1,2 @@
 /** This release of phantom. `npm version` keeps it equal to the version in package.json. */
-export const VERSION = '1.2.6';
+export const VERSION = '1.2.8';

package/dist/plan/command.mjs

@@ -65,7 +65,7 @@ export async function planCommand(input) {
         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 what = offer ? `$${offer.usd_per_month} a month for $${offer.week_limit_usd} of model cost a week, every key` : '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 },

package/dist/setup/command.mjs

@@ -4,6 +4,7 @@ import { createInterface } from 'node:readline/promises';
 import { die } from "../core/errors.mjs";
 import { out, pickIo } from "../core/helpers.mjs";
 import { BackToMenu, checklist, choose } from "../core/pick.mjs";
+import { request } from "../core/request.mjs";
 import { resolveApiKey } from "../keys/saved.mjs";
 import { workspaceLogin } from "../workspace/command.mjs";
 import { SETUP_AGENTS, SETUP_NAMES } from "./agents.mjs";
@@ -104,6 +105,8 @@ export async function setupCommand(input) {
     // Plain `phantom setup` sets up everything it finds and asks first. Any of
     // the older flags runs just what they name, without asking.
     const guided = agent === undefined && provider === undefined;
+    // Checked before anything is written, so a typo in --limit changes nothing.
+    const limit = capFlag(flags['limit']);
     // With no key yet, sign in first, as phantom claude does, so the agents
     // get one in this run. Its words go to stderr; stdout stays setup's result.
     if (guided && !dryRun && io.isTTY && !resolveApiKey(env)) {
@@ -119,19 +122,25 @@ export async function setupCommand(input) {
         provider: guided || provider === true ? true : provider === 'off' ? 'off' : false,
         model: typeof model === 'string' ? model : undefined,
         guided,
+        shell: !flags['no-shell'],
     };
     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;
+    const ticks = Boolean(pick) && (found.agents.length > 1 || found.files.some((f) => f.agent === 'shell'));
     /** Shows the checklist, or returns false when Esc there means leave. */
+    // The shell file is a row of its own, so it can be left out like an agent.
+    const shellRow = found.files.some((f) => f.agent === 'shell');
     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) })));
+        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) })),
+            ...(shellRow ? [{ label: 'Your shell', hint: 'new terminals get your key; untick to add it yourself', value: 'shell', checked: plan.files.some((f) => f.agent === 'shell') }] : []),
+        ]);
         if (!only)
             return false;
-        plan = planSetup(env, { ...options, only });
+        plan = planSetup(env, { ...options, only: only.filter((a) => a !== 'shell'), shell: shellRow ? only.includes('shell') : options.shell });
         return true;
     };
     /** Esc on setup's first step: back to the menu when it started setup, otherwise stop with nothing changed. */
@@ -190,7 +199,7 @@ export async function setupCommand(input) {
                 }
                 break;
             }
-            return finish(applySetup(env, plan));
+            return capAfter(input, await finish(applySetup(env, plan)), limit, guided ? pick : null);
         }
         const ask = io.ask ??
             (process.stdin.isTTY
@@ -213,5 +222,49 @@ export async function setupCommand(input) {
             return 0;
         }
     }
-    return finish(applySetup(env, plan));
+    return capAfter(input, await finish(applySetup(env, plan)), limit, null);
+}
+/** `--limit`: dollars a month above zero, `none` to remove the cap, or undefined when it isn't given. */
+function capFlag(value) {
+    if (value === undefined)
+        return undefined;
+    if (value === 'none')
+        return null;
+    const usd = Number(String(value).replace(/^\$/, ''));
+    if (typeof value !== 'string' || !Number.isFinite(usd) || usd <= 0)
+        die('--limit takes dollars a month above zero, such as 20, or none', 'setup_limit');
+    return usd;
+}
+/**
+ * After setup has written its files: the key's monthly spend cap (PATCH
+ * /key/budget, a calendar month). `--limit` sets it; without one, setup at a
+ * terminal asks once, only when the key has no cap yet. Returns setup's exit code.
+ */
+async function capAfter(input, code, limit, pick) {
+    const { env, io, baseUrl } = input;
+    const apiKey = resolveApiKey(env);
+    if (!apiKey || (limit === undefined && !pick))
+        return code;
+    let cap = limit;
+    if (cap === undefined) {
+        const now = await request('GET', '/key/budget', apiKey, undefined, baseUrl).catch(() => null);
+        if (!now || now.budget_usd !== null)
+            return code;
+        io.stderr('\n');
+        const answer = await choose(pick, 'Cap what this key can spend each month?', [
+            { label: 'No cap', hint: 'free use is never charged', value: 0 },
+            { label: '$10 a month', value: 10 },
+            { label: '$25 a month', value: 25 },
+            { label: '$50 a month', value: 50 },
+        ]);
+        if (!answer)
+            return code;
+        cap = answer;
+    }
+    await request('PATCH', '/key/budget', apiKey, cap === null ? { budget_usd: null } : { budget_usd: cap, period_days: null }, baseUrl);
+    const p = paint(env, colorOn(env, io.isTTY));
+    io.stderr(cap === null
+        ? `  ${p.lime('✓')} This key has no monthly cap now.\n`
+        : `  ${p.lime('✓')} This key can spend at most $${cap} a month. Change it any time: ${p.cyan('phantom setup --limit <USD|none>')}\n`);
+    return code;
 }

package/dist/setup/plan.mjs

@@ -109,7 +109,12 @@ export function planSetup(env, opts = {}) {
         }
         agents.push({ agent, skill, ...(result ? { provider: result } : {}) });
     }
-    if (shellOn.size || shellOff.length) {
+    if (shellOn.size && opts.shell === false) {
+        const block = withShellBlock(env, ctx.shellRc, '', shellOn, [], opts.onPath) ?? '';
+        const short = ctx.shellRc.startsWith(home + path.sep) ? '~' + ctx.shellRc.slice(home.length) : ctx.shellRc;
+        notes.push(`Your shell file was left alone. So ${orList([...shellOn.keys()].map((a) => SETUP_AGENTS[a].label))} can find your key, add these lines to ${short}:`, '', ...block.trimEnd().split('\n').map((l) => `  ${l}`));
+    }
+    else if (shellOn.size || shellOff.length) {
         try {
             add('shell', ctx.shellRc, withShellBlock(env, ctx.shellRc, readText(ctx.shellRc), shellOn, shellOff, opts.onPath));
         }

package/dist/setup/screen.mjs

@@ -5,10 +5,11 @@
 // The JSON result (setupCommand without a terminal) never goes through here.
 import os from 'node:os';
 import path from 'node:path';
-import { paint, unstyled } from "../core/style.mjs";
+import { fitText, paint, unstyled } from "../core/style.mjs";
 import { brandHeader } from "../core/brand.mjs";
 import { inApp } from "../cli/screens.mjs";
 import { SETUP_AGENTS } from "./agents.mjs";
+import { FREE_LINE } from "../core/free.mjs";
 /** `text` broken at spaces into lines of at most `width` characters; a single longer word stays whole. */
 export function wrapWords(text, width) {
     const lines = [];
@@ -64,10 +65,12 @@ export function setupScreen(r, opts = {}) {
     // unless that's wider than the window: then rows stay short and unaligned.
     const longest = Math.max(0, ...r.files.map((f) => short(f.file).length));
     const columns = opts.columns ?? process.stdout.columns ?? 100;
-    const fits = width + 4 + 10 + longest + 2 + 8 + 4 <= columns;
+    // The widest "what happens" phrase (`new file, 12 lines`), plus room for "copy kept".
+    const said = Math.max(8, ...r.files.map((f) => change(f).length + (f.backup ? 11 : 0)));
+    const fits = width + 4 + 10 + longest + 2 + said <= columns;
     const pathWidth = fits ? longest : 0;
     // As wide as a file row (name, kind, path, action and a line count), and never wider than the window.
-    const rule = Math.max(20, Math.min(width + 2 + 10 + longest + 2 + 8 + 4, columns - 4));
+    const rule = Math.max(20, Math.min(width + 2 + 10 + longest + 2 + said, columns - 4));
     // After the prompt, a blank line sets the result apart from the answer typed above it.
     const lines = [''];
     const found = r.agents.length;
@@ -134,7 +137,16 @@ export function setupScreen(r, opts = {}) {
             lines.push('');
         if (routes) {
             lines.push(`  ${p.dim('What this does:')} these agents send their model requests to Phantom AI, and phantom-1 picks the model.`);
-            lines.push(`  ${p.dim('Nothing is bought:')} phantom-1 runs free until you add credit.`);
+            lines.push(`  ${p.dim('Free to start:')} ${FREE_LINE}.`);
+            // Claude Code's settings file applies in every folder, so its own login stops being used.
+            if (r.agents.some((a) => a.agent === 'claude' && a.provider?.on)) {
+                lines.push(`  ${p.dim('Claude Code:')} uses Phantom AI in place of your Anthropic login, in every folder. To keep your login, leave Claude Code out and start it with ${p.cyan('phantom claude')} when you want Phantom.`);
+            }
+            const readers = r.agents.filter((a) => a.provider?.on && SETUP_AGENTS[a.agent]?.shellEnv);
+            if (readers.length && r.files.some((f) => f.agent === 'shell')) {
+                lines.push(`  ${p.dim('Your shell:')} new terminals get your key as PHANTOM_API_KEY, for ${readers.map((a) => label(a.agent)).join(', ')}. The file runs ${p.cyan('phantom key show')}; the key itself isn't written in it.`);
+            }
+            lines.push(`  ${p.dim('Undo:')} phantom keeps a copy of each file it changes, and ${p.cyan('phantom setup --restore')} puts them back.`);
         }
         if (skills)
             lines.push(`  ${p.dim('skill:')} a short note that teaches the agent the phantom commands.`);
@@ -153,7 +165,8 @@ export function setupScreen(r, opts = {}) {
         lines.push('', ...nextStep(r, p, opts.columns));
         lines.push('', inApp() ? `  ${p.dim('Undo any time: More, then Undo setup.')}` : `  Undo any time: ${p.cyan('phantom setup --restore')}`);
     }
-    return lines.join('\n');
+    // Long sentences break at a word under their own indent, at the terminal's width.
+    return fitText(lines.join('\n'), columns);
 }
 /** What a file is, in the words the screen uses: its settings (an agent's, or the shell's ~/.zshrc), or its skill. */
 function kind(f) {
@@ -162,22 +175,32 @@ function kind(f) {
     // ~/.zshrc is the shell's own settings file, and the row already says "Your shell".
     return 'settings';
 }
-/** What happens to a file, in one short word. */
-const ACTION = { create: 'new', update: 'update', remove: 'remove' };
+/** `n lines`, or `1 line`. */
+const lineCount = (n) => `${n} line${n === 1 ? '' : 's'}`;
 /**
- * One file under an agent, in columns: what the file is, where it is, what
- * happens to it, and how many lines change. For example
- * `settings  ~/.codex/config.toml  new  +12`.
+ * What happens to a file, in words: `new file, 12 lines`, `adds 3 lines`,
+ * `adds 3, removes 1`, `updated` (a skill) or `deleted`.
  */
-function fileRow(f, p, short, pathWidth) {
-    const action = ACTION[f.action].padEnd(6);
+function change(f) {
     const { added, removed } = counts(f.diff);
-    const change = [added ? p.green(`+${added}`) : '', removed ? p.red(`-${removed}`) : ''].filter(Boolean).join(' ');
+    if (f.action === 'remove')
+        return 'deleted';
+    if (f.action === 'create')
+        return added ? `new file, ${lineCount(added)}` : 'new file';
+    if (!f.diff)
+        return 'updated';
+    return removed ? `adds ${added}, removes ${removed}` : `adds ${lineCount(added)}`;
+}
+/**
+ * One file under an agent, in columns: what the file is, where it is, and
+ * what happens to it. For example `settings  ~/.codex/config.toml  new file, 12 lines`.
+ */
+function fileRow(f, p, short, pathWidth) {
+    const what = change(f);
     return [
         p.dim(kind(f).padEnd(8)),
         short(f.file).padEnd(pathWidth),
-        f.action === 'remove' ? p.red(action) : p.cyan(action),
-        change + (f.backup ? p.dim('  copy kept') : ''),
+        (f.action === 'remove' ? p.red(what) : p.cyan(what)) + (f.backup ? p.dim('  copy kept') : ''),
     ]
         .join('  ')
         .trimEnd();

package/dist/spend/command.mjs

@@ -6,7 +6,7 @@ import { colorOn, paint } from "../core/style.mjs";
 import { choose } from "../core/pick.mjs";
 import { hideHints, lineupScreen, priceHint, routeScreen, routeTestScreen, TIER_ABOUT } from "../cli/screens.mjs";
 import { getLineup, putLineup, resetLineup, LINEUP_TIERS } from "./lineup.mjs";
-import { getRoute, putRoute, patchRoute, clearRoute, testRoute, parseCondition } from "./routing.mjs";
+import { getRoute, putRoute, patchRoute, clearRoute, testRoute, parseCondition, SORT_WORDS } from "./routing.mjs";
 /** `phantom route`: the key's route policy, its rules, and a dry run. Run by `run()`. */
 export async function routeCommand(input) {
     const { argv, io, apiKey, subcommand, flags, baseUrl, env } = input;
@@ -44,11 +44,28 @@ export async function routeCommand(input) {
                 fields.stick_minutes = stick;
             if (flags['stick-by-prompt'] !== undefined)
                 fields.stick_by_prompt = flags['stick-by-prompt'] !== 'false';
-            if (Object.keys(fields).length === 0) {
-                die('route set needs --models a,b,c, --applies-to, --on-empty, --fallback, --stick-minutes, --stick-by-prompt, or --file policy.json');
+            const sort = flags['sort'];
+            if (sort !== undefined && (typeof sort !== 'string' || !(sort in SORT_WORDS || sort === 'default'))) {
+                die('--sort takes fast (quickest to start answering), cheap (the default), throughput (most tokens a second) or default', 'route_usage');
+            }
+            if (typeof sort === 'string' && sort !== 'default')
+                fields.sort = SORT_WORDS[sort];
+            if (Object.keys(fields).length === 0 && sort !== 'default') {
+                die('route set needs --models a,b,c, --sort, --applies-to, --on-empty, --fallback, --stick-minutes, --stick-by-prompt, or --file policy.json');
             }
             const current = (await getRoute(apiKey, baseUrl)).route_policy;
-            const result = current ? await patchRoute(apiKey, fields, baseUrl) : await putRoute(apiKey, fields, baseUrl);
+            let result;
+            if (sort === 'default') {
+                // Back to cheapest first: drop sort, and the whole policy when sort was all it held.
+                const { sort: _was, ...rest } = { ...(current ?? { models: [] }), ...fields };
+                void _was;
+                const empty = !rest.models.length && !rest.zdr && !rest.no_training && !(rest.rules ?? []).length;
+                result = !current ? { route_policy: null } : empty ? await clearRoute(apiKey, baseUrl) : await putRoute(apiKey, rest, baseUrl);
+            }
+            else {
+                // A key with no policy gets one of preferences only, which routes nothing, unless --models is given too.
+                result = current ? await patchRoute(apiKey, fields, baseUrl) : await putRoute(apiKey, { models: [], ...fields }, baseUrl);
+            }
             out(result, table, tableRoute, io.stdout);
         }
     }
@@ -174,7 +191,7 @@ async function lineupPicker(input, pick, show) {
             io.stdout(show(read) + '\n\n');
             const tier = await choose({ ...pick, esc: 'back' }, 'Which tier do you want to change?', [
                 ...LINEUP_TIERS.map((t) => ({ label: t[0].toUpperCase() + t.slice(1), hint: `${TIER_ABOUT[t]} · now ${read.tiers[t].model}`, value: t })),
-                { label: 'Put every tier back to its default', value: 'reset' },
+                { label: 'Reset every tier', hint: 'back to its default', value: 'reset' },
             ], last);
             if (tier === null)
                 return 0;

package/dist/spend/routing.mjs

@@ -1,5 +1,7 @@
 import { die } from "../core/errors.mjs";
 import { request } from "../core/request.mjs";
+/** The words `phantom route set --sort` takes, and the server's name for each. The server's own names work too. */
+export const SORT_WORDS = { cheap: 'cost', fast: 'ttft', throughput: 'tps', cost: 'cost', ttft: 'ttft', tps: 'tps' };
 /** The key's route policy (GET /key/route). */
 export function getRoute(apiKey, baseUrl) {
     return request('GET', '/key/route', apiKey, undefined, baseUrl);

package/dist/workspace/command.mjs

@@ -12,8 +12,8 @@ import { BackToMenu, Cancelled, askText, cancelKeys, choose, keyboard } from "..
 import { spawnSync } from 'node:child_process';
 import { onPath } from "../setup/shared.mjs";
 import { colorOn, paint } from "../core/style.mjs";
-import { fundScreen, keyChangeScreen, keysScreen, paymentScreen, signedInScreen, workspaceScreen } from "../cli/screens.mjs";
-import { keyPath, listNamedKeys, namedKeyPath, readNamedKey, saveApiKey, saveNamedKey } from "../keys/saved.mjs";
+import { alreadySignedInScreen, fundScreen, keyChangeScreen, keysScreen, paymentScreen, signedInScreen, workspaceScreen } from "../cli/screens.mjs";
+import { keyId, keyPath, listNamedKeys, namedKeyPath, readNamedKey, resolveApiKey, saveApiKey, saveNamedKey } from "../keys/saved.mjs";
 const credentialPath = (env) => path.join(stateDir(env), 'workspace');
 const base = (input) => httpsOnly(input.baseUrl || input.env.PHANTOM_BASE_URL || DEFAULT_BASE_URL).replace(/\/$/, '');
 async function wire(url, method, endpoint, body, token) {
@@ -52,8 +52,12 @@ export async function workspaceLogin(input, opts = {}) {
         die('--save requires a key name.');
     const name = typeof flags.save === 'string' ? flags.save : 'default';
     const target = name === 'default' ? keyPath(env) : namedKeyPath(env, name);
-    if (existsSync(target))
-        die(`Saved key ${name} already exists. Use --save <new-name>; no key was overwritten.`, 'key_exists');
+    if (existsSync(target)) {
+        // Signing in again is a question ("am I signed in?"), so it gets an answer, not an error.
+        if (name === 'default')
+            return alreadySignedIn(input);
+        die(`A key named ${name} is already saved here. Pick another name with --save <name>; nothing was changed.`, 'key_exists');
+    }
     // At a terminal, how to sign in is a choice; --no-browser or a pipe skips it.
     const pick = flags['no-browser'] ? null : pickIo(input);
     let noBrowser = Boolean(flags['no-browser']);
@@ -101,6 +105,17 @@ export async function workspaceLogin(input, opts = {}) {
         cancel?.close();
     }
 }
+/** `phantom login` on a computer that already has a key: which key, and how to use another. Exit 0. */
+function alreadySignedIn(input) {
+    const { env, io } = input;
+    const key = resolveApiKey(env);
+    const result = { signed_in: true, already: true, key_id: key ? keyId(key) : null };
+    if (showsScreen(input))
+        io.stdout(alreadySignedInScreen(result.key_id, { env, color: colorOn(env, io.stdoutIsTTY) }) + '\n');
+    else
+        io.stdout(JSON.stringify(result) + '\n');
+    return 0;
+}
 /** A spinner on one line: `⠋ Waiting for you to approve...` until stopped, then `✓ Approved.` or nothing. */
 function waiting(write, p, words = 'Waiting for you to approve...', doneWords = 'Approved.') {
     const frames = '⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏';
@@ -324,7 +339,7 @@ export async function workspaceCommand(input) {
         }
         if (pick && !method) {
             method = (await choose({ ...pick, esc: 'back' }, 'How do you want to pay?', [
-                { label: 'Card', hint: "on Stripe's page; Stripe's fee is added, and the next screen shows the total", value: 'card' },
+                { label: 'Card', hint: "on Stripe's page, plus Stripe's card fee", value: 'card' },
                 { label: 'USDC', hint: 'from a Solana wallet', value: 'usdc' },
                 { label: 'USDT', hint: 'from a Solana wallet', value: 'usdt' },
                 { label: 'SOL', hint: 'from a Solana wallet', value: 'sol' },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phantomcodes/cli",
-  "version": "1.2.6",
+  "version": "1.2.8",
   "description": "AI inference for your coding agents. Route models, control spending, and fund your workspace.",
   "keywords": [
     "phantom",