@phantomcodes/cli 1.2.4 → 1.2.5

package/README.md

@@ -62,8 +62,8 @@ The Phantom CLI detects supported agents, previews the configuration changes, th
 applying them. It connects their model calls to Phantom AI and wires up the saved
 key. Restart your agent, or open a new terminal, to use the connection.
 
-Codex, Claude Code, opencode, Continue, Goose, Aider, GitHub Copilot CLI and Cline
-support saved setup. Cursor gets instructions for its settings screen; pi gets
+Codex, Claude Code, opencode, Continue, Goose, Aider, GitHub Copilot CLI, Cline
+and Gemini CLI support saved setup. Cursor gets instructions for its settings screen; pi gets
 the agent skill.
 
 Preview without changing files with `phantom setup --dry-run`. The Phantom CLI keeps backups;
@@ -79,9 +79,11 @@ phantom workspace status
 phantom codex
 ```
 
-Both setup options require **Node 24+** and your coding agent installed. Connect, fund your
-workspace, then launch **Codex** (`phantom codex`), **Claude Code** (`phantom claude`),
-**pi** (`phantom pi`), or **any other compatible agent**.
+Both setup options require **Node 24+** and your coding agent installed. Connect, then
+launch **Codex** (`phantom codex`), **Claude Code** (`phantom claude`), **pi**
+(`phantom pi`), or **any other compatible agent**. Each runs phantom-1 unless you
+pick a model (`--model` after `--`), and phantom-1 runs on free models until you add
+credit. Free calls leave out web search, which costs money on any model.
 
 Login opens a device approval page and saves a key privately. Funding opens
 checkout; check your workspace balance after payment. Agent runs use temporary

package/dist/agents/command.mjs

@@ -6,7 +6,10 @@ import { die, NO_KEY } from "../core/errors.mjs";
 import { DEFAULT_BASE_URL, httpsOnly, request } from "../core/request.mjs";
 import { keyId, readNamedKey, resolveApiKey } from "../keys/saved.mjs";
 import { workspaceLogin } from "../workspace/command.mjs";
-const DEFAULT_MODEL = 'auto';
+/** The model an agent runs when the user names none: phantom-1, which runs free on a key with no credit. */
+const DEFAULT_MODEL = 'phantom-1';
+/** phantom-1 as Claude Code names it: its picker keeps only ids that say "claude", so Phantom lists them as `claude-code/<id>`. */
+const CLAUDE_DEFAULT_MODEL = `claude-code/${DEFAULT_MODEL}`;
 /** The key's spend and balance, or null when the answer has no numbers, such as a sign-in page that came back with status 200. */
 async function keyStatus(apiKey, baseUrl) {
     const s = await request('GET', '/key/balance', apiKey, undefined, baseUrl);
@@ -23,11 +26,16 @@ export const AGENTS = {
             // --settings outranks settings.json, so an env block or apiKeyHelper
             // `phantom setup` wrote can't send Claude Code past the proxy. The helper
             // reads the token from the environment, so it stays off the command line.
+            // It runs with this phantom's own Node: the curl installer puts none on PATH.
+            const helper = `${JSON.stringify(process.execPath)} -p "process.env.PHANTOM_AGENT_TOKEN || ''"`;
+            // phantom-1 unless the user picks a model. It goes in the environment, which
+            // Claude Code ranks below --model and below a model in its settings file.
+            const model = hasModel(args) || env.ANTHROPIC_MODEL ? {} : { ANTHROPIC_MODEL: CLAUDE_DEFAULT_MODEL };
             const vars = { ANTHROPIC_BASE_URL: proxy, CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY: '1', ENABLE_TOOL_SEARCH: 'true' };
             const { ANTHROPIC_AUTH_TOKEN: _auth, ...rest } = env;
             return {
-                args: ['--settings', JSON.stringify({ apiKeyHelper: 'node -p "process.env.PHANTOM_AGENT_TOKEN || \'\'"', env: vars }), ...args],
-                env: { ...rest, ANTHROPIC_BASE_URL: proxy, ANTHROPIC_API_KEY: token, PHANTOM_AGENT_TOKEN: token },
+                args: ['--settings', JSON.stringify({ apiKeyHelper: helper, env: vars }), ...args],
+                env: { ...rest, ...model, ANTHROPIC_BASE_URL: proxy, ANTHROPIC_API_KEY: token, PHANTOM_AGENT_TOKEN: token },
             };
         },
     },

package/dist/cli/run.mjs

@@ -21,16 +21,21 @@ 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.
  */
+/** Retired flags, accepted so the command can say what replaced them, and never suggested for a typo. */
+const RETIRED_FLAGS = ['pay', 'mpp'];
+/** The flags every command takes, and the retired ones. */
+const EVERY_COMMAND_FLAGS = ['table', 'json', 'help', 'all', 'version', 'mcp', ...RETIRED_FLAGS];
 /**
- * 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.
+ * The flags a command reads: each one its help names, plus those of the
+ * command its subcommand names (`workspace fund` reads `fund`'s), plus
+ * {@link EVERY_COMMAND_FLAGS}. A typo such as --yse, or a flag only another
+ * command takes (balance --key), 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',
-]);
+function flagsOf(command, subcommand) {
+    const helps = [command.help, COMMANDS.find((c) => c.name === subcommand)?.help ?? ''].join('\n');
+    return new Set([...[...helps.matchAll(/--([a-z][a-z0-9-]*)/g)].map((m) => m[1]), ...EVERY_COMMAND_FLAGS]);
+}
 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),
@@ -92,10 +97,11 @@ export async function run(argv = process.argv.slice(2), env = process.env, io =
         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;
+        const known = flagsOf(command, subcommand);
         for (const name of passesArgs ? [] : Object.keys(ownFlags)) {
-            if (KNOWN_FLAGS.has(name))
+            if (known.has(name))
                 continue;
-            const guess = closestCommand(name, [...KNOWN_FLAGS]);
+            const guess = closestCommand(name, [...known].filter((flag) => !RETIRED_FLAGS.includes(flag)));
             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.

package/dist/cli/screens.mjs

@@ -109,15 +109,19 @@ export function spendScreen(s, style = {}) {
     lines.push(...(s.scope === 'workspace' ? next(p, 'Pick the models phantom-1 runs:', 'phantom lineup') : next(p, 'Every key in the workspace:', 'phantom spend --workspace')));
     return lines.join('\n');
 }
+/** `text` cut to `width` characters, ending in … when it was longer. */
+const clip = (text, width) => (text.length > width ? `${text.slice(0, width - 1)}…` : text);
 /** The keys, one row each: name, the start of the key, what it spent, and its limit. */
 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 mark = k.is_active === false ? p.dim('off') : p.lime('●');
+        // 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} ${(k.name ?? 'Key').slice(0, 15).padEnd(16)}${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)}`;
+        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')}` : ''}`;
     });
 }
 /** `phantom workspace`: the shared balance, each key, and the last few charges. */
@@ -161,7 +165,7 @@ export function routeScreen(r, 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 requests for model "auto" are refused.', `  ${p.dim('phantom-1 picks a model for you without one.')}`);
+        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'));
         return lines.join('\n');
     }
@@ -317,7 +321,8 @@ export function savedKeysScreen(keys, style = {}) {
         lines.push(`  ${p.dim('None saved yet.')}`);
     for (const k of keys) {
         const credit = k.credit_balance_usd === undefined ? '' : usd(k.credit_balance_usd).padStart(10);
-        lines.push(`  ${k.active === false ? p.dim('off') : p.lime('●')} ${k.name.slice(0, 19).padEnd(20)}${p.dim(k.id.slice(0, 12).padEnd(14))}${credit}`);
+        const off = k.active === false;
+        lines.push(`  ${off ? p.dim('○') : p.lime('●')} ${clip(k.name, 20).padEnd(21)}${p.dim(k.id.slice(0, 12).padEnd(14))}${credit}${off ? `  ${p.dim('off')}` : ''}`);
     }
     lines.push(...next(p, 'Save another:', 'phantom keys save <name>'));
     return lines.join('\n');

package/dist/core/helpers.mjs

@@ -12,7 +12,7 @@ export function pickIo(input) {
     if (!(io.keys ? io.isTTY : canPick(env, io.isTTY)))
         return null;
     // A command started from the menu goes back to it on Esc; one typed on its own quits.
-    return { write: io.stderr, env, keys: io.keys, esc: io.fromMenu ? 'back' : 'quit', columns: process.stderr.columns };
+    return { write: io.stderr, env, keys: io.keys, esc: io.fromMenu ? 'back' : 'cancel', columns: process.stderr.columns };
 }
 /**
  * Whether a command should draw its screen rather than print JSON: with

package/dist/core/pick.mjs

@@ -96,6 +96,8 @@ function block(write) {
 }
 /** The question line: a lime ? and the question in bold, then the answer once there is one. */
 const asked = (p, question, answer = '') => `  ${p.lime('?')} ${p.bold(question)}${answer ? ` ${p.cyan(answer)}` : ''}`;
+/** The answer a question shows after Esc: back, quit, or cancelled. */
+const escAnswer = (esc) => (esc === 'quit' ? 'quit' : esc === 'cancel' ? 'cancelled' : 'back');
 /** The hint under a picker: which keys do what. */
 const keysHint = (p, words) => `  ${p.dim(words)}`;
 /**
@@ -129,7 +131,7 @@ export async function choose(io, question, choices, start = 0) {
                 return choices[at].value;
             }
             else if (key === 'escape' || key === 'q' || key === 'end') {
-                draw([asked(p, question, io.esc === 'quit' ? 'quit' : 'back')]);
+                draw([asked(p, question, escAnswer(io.esc))]);
                 return null;
             }
             else if (key === 'ctrl-c') {
@@ -190,7 +192,7 @@ export async function checklist(io, question, items) {
                 }
             }
             else if (key === 'escape' || key === 'q' || key === 'end') {
-                draw([asked(p, question, io.esc === 'quit' ? 'quit' : 'back')]);
+                draw([asked(p, question, escAnswer(io.esc))]);
                 return null;
             }
             else if (key === 'ctrl-c') {
@@ -270,7 +272,7 @@ export async function askText(io, question, opts = {}) {
                 problem = why;
             }
             else if (key === 'escape' || key === 'end') {
-                draw([asked(p, question, io.esc === 'quit' ? 'quit' : 'back')]);
+                draw([asked(p, question, escAnswer(io.esc))]);
                 return null;
             }
             else if (key === 'ctrl-c') {

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.4';
+export const VERSION = '1.2.5';

package/dist/setup/agents.mjs

@@ -88,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.
@@ -311,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
@@ -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/command.mjs

@@ -168,7 +168,7 @@ export async function setupCommand(input) {
         // 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' : 'quit' }, 'Make these changes?', [
+                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' },

package/dist/setup/screen.mjs

@@ -208,7 +208,7 @@ function doneSummary(agent, a, files, skipped, p) {
     return files ? 'skill installed.' : p.dim('already set up.');
 }
 /** The command that starts each agent that runs in a terminal. Editors (Cursor, Continue, Cline) are opened, not run. */
-const START = { claude: 'claude', codex: 'codex', pi: 'pi', opencode: 'opencode', goose: 'goose', aider: 'aider', copilot: 'copilot' };
+const START = { claude: 'claude', codex: 'codex', pi: 'pi', opencode: 'opencode', goose: 'goose', aider: 'aider', copilot: 'copilot', gemini: 'gemini' };
 /**
  * The one thing to do after setup, in corner brackets: run the agent. When an
  * agent reads its key from the shell (Codex, Goose and others), the step says

package/dist/setup/shared.mjs

@@ -11,13 +11,14 @@ export function onPath(bin) {
 export const SETUP_MODEL = 'phantom-1';
 /**
  * The address Phantom AI serves a coding agent at, from PHANTOM_BASE_URL
- * without its `/v1`: `/claude-code` (Claude Code adds `/v1` itself), or
- * `/codex/v1`, `/cursor/v1` and `/coding-agent/v1` for the others.
+ * without its `/v1`: `/claude-code` (Claude Code adds `/v1` itself),
+ * `/gemini-cli` (Gemini CLI adds Google's `/v1beta`), or `/codex/v1`,
+ * `/cursor/v1` and `/coding-agent/v1` for the others.
  * @throws {@link CliError} when PHANTOM_BASE_URL is not https ({@link httpsOnly}).
  */
 export function agentBaseUrl(env, agent) {
     const origin = httpsOnly(env.PHANTOM_BASE_URL || DEFAULT_BASE_URL).replace(/\/+$/, '').replace(/\/v1$/, '');
-    return agent === 'claude-code' ? `${origin}/claude-code` : `${origin}/${agent}/v1`;
+    return agent === 'claude-code' || agent === 'gemini-cli' ? `${origin}/${agent}` : `${origin}/${agent}/v1`;
 }
 /** The end of every line phantom adds to a TOML, YAML or shell file. */
 export const SETUP_MARK = '# phantom setup';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phantomcodes/cli",
-  "version": "1.2.4",
+  "version": "1.2.5",
   "description": "AI inference for your coding agents. Route models, control spending, and fund your workspace.",
   "keywords": [
     "phantom",
@@ -66,10 +66,10 @@
   "license": "SEE LICENSE IN LICENSE",
   "author": "Harbor Financial LLC",
   "devDependencies": {
-    "@types/node": "^24.19.1",
+    "@types/node": "^24.19.2",
     "@vitest/coverage-v8": "^5.0.3",
     "typescript": "^6.0.3",
-    "vitest": "^5.0.2"
+    "vitest": "^5.0.5"
   },
   "publishConfig": {
     "access": "public"