@phantomcodes/cli 1.2.1 → 1.2.3

package/README.md

@@ -19,7 +19,6 @@ phantom setup --agent claude
 ```
 
 The skill covers workspace setup, funding, spending controls and model routing.
-[Skill docs](docs/guides/agent-skill.md)
 
 ## Let your agent set it up
 
@@ -65,7 +64,7 @@ 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
-the agent skill. [Agent-specific setup](docs/guides/agent-setup.md).
+the agent skill.
 
 Preview without changing files with `phantom setup --dry-run`. The Phantom CLI keeps backups;
 undo the changes with `phantom setup --restore`.
@@ -83,7 +82,6 @@ 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**.
-[Set up other agents](docs/guides/agent-setup.md).
 
 Login opens a device approval page and saves a key privately. Funding opens
 checkout; check your workspace balance after payment. Agent runs use temporary
@@ -103,8 +101,6 @@ phantom fund --amount 10 --coin usdc
 
 Credit is available after the payment is verified. Check balance anytime with `phantom balance`.
 
-[Funding and payment details](docs/guides/buying-credit.md).
-
 ## Give each agent a budget
 
 Create a key with its own cap, sharing your workspace balance:
@@ -132,7 +128,6 @@ PHANTOM_KEY_NAME=coding phantom route test --table
 
 Prefer a specific model? Select it in your agent. Policies that apply only to
 `auto` leave explicit model choices alone.
-[Routing](docs/guides/routing.md) covers conditions, fallback and conversation affinity.
 
 `phantom-1` picks a tier for each request: economy, standard or frontier. Your key's
 lineup picks the model in each tier, and a fallback model to try when it fails:
@@ -199,13 +194,7 @@ Exit codes: 0 success, 1 error, 2 rejected key; agent runs return the agent's ex
 <details>
 <summary><strong>Advanced tools, integrations and legacy commands</strong></summary>
 
-`phantom --help` shows the main workflows. `phantom --help --all` and the
-[interface reference](docs/reference.md) cover every command.
-
-- [Signed receipts](docs/guides/receipts.md): check which model answered with `phantom verify`.
-- [Funding credit](docs/guides/buying-credit.md): `phantom fund` and checking payments.
-- [Saved secrets](docs/guides/saved-secrets.md): macOS Keychain or private files; guest recovery uses `phantom workspace export` and `phantom workspace import`.
-- [Key selection](docs/guides/which-key.md) and [API address](docs/guides/base-url.md): environment overrides and shell integration.
+`phantom --help` shows the main workflows. `phantom --help --all` covers every command.
 
 The older `phantom key` commands still work.
 `phantom keys list` reads the workspace; `phantom keys saved` lists local copies.
@@ -221,11 +210,9 @@ npm ci
 npm run typecheck
 npm run build
 npm run coverage
-npm run docs
-node scripts/gen-docs.mjs --check
 ```
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md).
+Report a security problem privately to support@phantom.codes, not in a public issue.
 
 </details>
 

package/dist/agents/command.mjs

@@ -26,7 +26,7 @@ export const AGENTS = {
             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: 'printenv PHANTOM_AGENT_TOKEN', env: vars }), ...args],
+                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 },
             };
         },

package/dist/cli/commands.mjs

@@ -138,6 +138,7 @@ export const COMMANDS = [
         [--yes]                     don't ask
         [--no-browser]              print the sign-in link instead of opening it
         [--dry-run]                 show the changes, write nothing
+        [--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:
                                     ${orList(SETUP_NAMES)}

package/dist/cli/help.mjs

@@ -1,9 +1,8 @@
 import { DEFAULT_BASE_URL } from "../core/request.mjs";
 import { COMMANDS } from "./commands.mjs";
 /**
- * Every environment variable phantom reads. The Environment sections of HELP and
- * docs/reference.md are built from this list, and `npm run docs` fails if the
- * code reads a variable that is not here.
+ * Every environment variable phantom reads. The Environment section of HELP is
+ * built from this list.
  */
 export const ENV_VARS = [
     { name: 'PHANTOM_API_KEY', about: 'your Phantom AI API key (or save one with login)', secret: true },

package/dist/cli/run.mjs

@@ -1,4 +1,5 @@
 import { VERSION } from "../core/version.mjs";
+import { nodeTrustWarning } from "../core/node-trust.mjs";
 import { die } from "../core/errors.mjs";
 import { handleError, parseFlags } from "../core/helpers.mjs";
 import { resolveApiKey } from "../keys/saved.mjs";
@@ -11,13 +12,20 @@ import { LEGACY_SETUP_HINT, legacySetupFound } from "../setup/legacy.mjs";
  * fails. Errors go to `io.stderr` as JSON. It never calls `process.exit`.
  * @param argv The arguments after `phantom`.
  * @param env The environment to read settings from.
- * @param io Where output goes, and whether stderr is a terminal (for progress lines).
+ * @param io Where output goes, whether stderr is a terminal (for progress lines),
+ *   and whether stdout is one (setup prints a summary there instead of JSON).
+ * @param node The Node version it runs on; one too old to reject forged
+ *   eMudhra certificates gets a warning on stderr first.
  */
 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),
     isTTY: Boolean(process.stderr.isTTY),
-}) {
+    stdoutIsTTY: Boolean(process.stdout.isTTY),
+}, node = process.versions.node) {
+    const unsafe = nodeTrustWarning(node);
+    if (unsafe)
+        io.stderr(unsafe);
     if (argv[0] === '--version' || argv[0] === '-v') {
         io.stdout(VERSION + '\n');
         return 0;

package/dist/core/node-trust.mjs

@@ -0,0 +1,24 @@
+/**
+ * Node before 24.22.1 still trusts certificates chained to the eMudhra CA
+ * keys found guessable in October 2026, so on a network someone controls, a
+ * forged phantom.codes could read the key this CLI sends. 24.22.1 rejects
+ * those chains ("tls: reject chains containing blocked public keys").
+ */
+/** The first Node 24 that rejects the compromised chains. */
+const FIXED = [24, 22, 1];
+/**
+ * A warning for stderr when `version` (`process.versions.node`) is a Node 24
+ * older than 24.22.1, or null. Other majors get none: the CLI needs 24 or newer,
+ * and the newer lines carry the fix.
+ */
+export function nodeTrustWarning(version) {
+    const [major, minor, patch] = version.split('.').map(Number);
+    if (major !== FIXED[0])
+        return null;
+    if (minor > FIXED[1] || (minor === FIXED[1] && patch >= FIXED[2]))
+        return null;
+    return (`phantom: Node ${version} still trusts certificates from eMudhra's compromised CA keys, ` +
+        `so on an untrusted network a forged phantom.codes could read your key. ` +
+        `Update to Node ${FIXED.join('.')} or newer (nvm install 24), or reinstall with ` +
+        `curl -fsSL https://phantom.codes/install | sh, which brings its own.\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.1';
+export const VERSION = '1.2.3';

package/dist/setup/apply.mjs

@@ -114,6 +114,13 @@ export function applySetup(env, plan) {
                 from = `${f.file}.phantom.bak`;
                 writeFileSync(from, f.before, { mode: 0o600 });
             }
+            if (f.before !== null && (f.agent === 'claude' || f.file.endsWith('settings.json'))) {
+                const standardBak = `${f.file}.bak`;
+                if (!existsSync(standardBak)) {
+                    const content = from && existsSync(from) ? readFileSync(from, 'utf-8') : f.before;
+                    writeFileSync(standardBak, content, { mode: 0o600 });
+                }
+            }
             if (from)
                 backup = from;
             if (f.after === null && from === null)

package/dist/setup/command.mjs

@@ -43,6 +43,10 @@ export function tableSetup(d) {
         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');
 }
 /** `--table` output for `setup --restore`. */
@@ -56,7 +60,9 @@ export function tableRestore(d) {
 }
 /** `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, table } = 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 agent = flags['agent'];
     if (agent === true)
         die(`--agent requires ${SETUP_NAMES.join(', ')} or all`);
@@ -80,7 +86,7 @@ export async function setupCommand(input) {
     // 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)) {
-        await workspaceLogin({ ...input, io: { ...io, stdout: io.stderr }, flags: flags['no-browser'] ? { 'no-browser': true } : {} });
+        await workspaceLogin({ ...input, io: { ...io, stdout: io.stderr }, flags: flags['no-browser'] ? { 'no-browser': true } : {} }, { inSetup: true });
     }
     const plan = planSetup(env, {
         agent,

package/dist/workspace/command.mjs

@@ -7,7 +7,7 @@ import { stateDir } from "../core/state.mjs";
 import { writeSecret, readSecret, removeSecret, keychainOn } from "../core/secrets.mjs";
 import { keyCommand } from "../keys/command.mjs";
 import { die } from "../core/errors.mjs";
-import { openUrl } from "../core/helpers.mjs";
+import { openUrl, flagNum } from "../core/helpers.mjs";
 import { keyPath, namedKeyPath, 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(/\/$/, '');
@@ -36,8 +36,12 @@ export async function workspaceGet(input, path) {
     const saved = credentials(input);
     return wire(saved.base_url, 'GET', '/workspaces/' + encodeURIComponent(saved.workspace_id) + path, undefined, saved.management_credential);
 }
-/** Device authorization for accounts or guests, saving keys locally without copying a secret through the browser. */
-export async function workspaceLogin(input) {
+/**
+ * Device authorization for accounts or guests, saving keys locally without copying a secret through the browser.
+ * With `inSetup`, `phantom setup` carries on once it is signed in, so it says that instead of printing the
+ * saved key's details and the next commands.
+ */
+export async function workspaceLogin(input, opts = {}) {
     const { env, io, flags } = input;
     if (flags.save === true)
         die('--save requires a key name.');
@@ -49,7 +53,9 @@ export async function workspaceLogin(input) {
     const start = await wire(url, 'POST', '/auth/device', { client_name: `phantom on ${hostname()}` });
     if (new URL(start.verification_uri_complete).origin !== new URL(url).origin)
         die('The approval URL belongs to another site.', 'device_origin');
-    io.stderr(`Open ${start.verification_uri_complete}\nConfirm code ${start.user_code}\n`);
+    io.stderr(`Sign in at ${start.verification_uri_complete}\n` +
+        `Check that the page shows code ${start.user_code}, then approve.\n` +
+        'Waiting for you to approve...\n');
     if (!flags['no-browser'])
         openUrl(start.verification_uri_complete);
     let interval = Math.max(1, start.interval) * 1000;
@@ -82,6 +88,10 @@ export async function workspaceLogin(input) {
             io.stderr('phantom could not save the connection. Sign in or restore your workspace to revoke the device key and reconnect.\n');
             throw error;
         }
+        if (opts.inSetup) {
+            io.stderr('Signed in. Setting up your agents next.\n\n');
+            return 0;
+        }
         io.stdout(JSON.stringify({ saved_as: name, key_name: token.key_name, workspace_id: token.workspace_id, storage: keychainOn(env) ? 'macOS Keychain' : 'private files' }) + '\n');
         io.stderr('Ready. Run phantom claude, phantom codex or phantom pi. Guests can export recovery with phantom workspace export --file <path>.\n');
         return 0;
@@ -184,7 +194,12 @@ export async function workspaceCommand(input) {
             die('--pay has been removed. Use --card or --coin.');
         if (!flags.card && !flags.coin)
             die('fund requires --card or --coin.');
-        const result = await wire(saved.base_url, 'POST', endpoint + '/fund', { method: flags.card ? 'card' : 'crypto', amount_usd: Number(flags.amount), coin: flags.coin ?? 'usdc' }, saved.management_credential);
+        const amount = flagNum(flags, 'amount');
+        if (amount === undefined)
+            die('fund requires --amount <USD>.');
+        if (amount <= 0)
+            die('--amount must be greater than 0.');
+        const result = await wire(saved.base_url, 'POST', endpoint + '/fund', { method: flags.card ? 'card' : 'crypto', amount_usd: amount, coin: flags.coin ?? 'usdc' }, saved.management_credential);
         io.stdout(JSON.stringify(result) + '\n');
         if (result.checkout_url && !flags['no-browser'])
             openUrl(result.checkout_url);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phantomcodes/cli",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "description": "AI inference for your coding agents. Route models, control spending, and fund your workspace.",
   "keywords": [
     "phantom",
@@ -50,7 +50,6 @@
     "build": "tsc -p .",
     "coverage": "vitest run --coverage",
     "dev": "node src/phantom.mts",
-    "docs": "node scripts/gen-docs.mjs",
     "prepare": "npm run build",
     "test": "vitest run",
     "typecheck": "tsc -p . --noEmit",
@@ -69,7 +68,6 @@
   "devDependencies": {
     "@types/node": "^24.19.1",
     "@vitest/coverage-v8": "^5.0.3",
-    "typedoc": "^0.28.20",
     "typescript": "^6.0.3",
     "vitest": "^5.0.2"
   },