@phantomcodes/cli 1.2.2 → 1.2.4

package/dist/workspace/command.mjs

@@ -5,10 +5,15 @@ import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { DEFAULT_BASE_URL, httpsOnly, apiError } from "../core/request.mjs";
 import { stateDir } from "../core/state.mjs";
 import { writeSecret, readSecret, removeSecret, keychainOn } from "../core/secrets.mjs";
-import { keyCommand } from "../keys/command.mjs";
+import { keyCommand, loginCommand } from "../keys/command.mjs";
 import { die } from "../core/errors.mjs";
-import { openUrl, flagNum } from "../core/helpers.mjs";
-import { keyPath, namedKeyPath, saveApiKey, saveNamedKey } from "../keys/saved.mjs";
+import { openUrl, flagNum, pickIo, showsScreen } from "../core/helpers.mjs";
+import { BackToMenu, Cancelled, askText, cancelKeys, choose, keyboard } from "../core/pick.mjs";
+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";
 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) {
@@ -21,7 +26,7 @@ async function wire(url, method, endpoint, body, token) {
 function credentials(input) {
     const file = credentialPath(input.env);
     if (!existsSync(file))
-        die('No workspace connection. Run phantom login.', 'workspace_missing');
+        die('Not signed in to a workspace on this computer. Run phantom login to sign in.', 'workspace_missing');
     const saved = JSON.parse(readSecret(input.env, file));
     if (saved.base_url !== base(input))
         die('This workspace belongs to a different API address. Run phantom login for this address.', 'workspace_origin');
@@ -36,8 +41,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.');
@@ -45,17 +54,90 @@ export async function workspaceLogin(input) {
     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');
+    // 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']);
+    if (pick) {
+        const how = await choose(pick, 'How do you want to sign in?', [
+            { label: 'Open the browser', hint: 'approve there, and phantom saves your key', value: 'browser' },
+            { label: 'Just show the link', hint: 'to open it yourself, or on another device', value: 'link' },
+            { label: 'Paste a key I already have', hint: 'starts with sk-phantom-', value: 'paste' },
+        ]);
+        // Esc: back to the menu when it started this, otherwise stop without saving anything.
+        if (how === null && input.io.fromMenu)
+            throw new BackToMenu();
+        if (how === null) {
+            input.io.stderr('  Sign-in cancelled. Nothing was saved.\n');
+            return 0;
+        }
+        if (how === 'paste') {
+            await loginCommand({ ...input, subcommand: undefined, flags: {}, io: opts.inSetup ? { ...input.io, stdout: input.io.stderr } : input.io });
+            return 0;
+        }
+        noBrowser = how === 'link';
+    }
     const url = base(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`);
-    if (!flags['no-browser'])
+    const lit = colorOn(env, io.isTTY);
+    const p = paint(env, lit);
+    io.stderr(`\n  ${p.lime('◆')} ${p.bold('Sign in to Phantom AI')}\n\n` +
+        `    ${p.dim('Open')}  ${p.bold(start.verification_uri_complete)}\n` +
+        `    ${p.dim('Code')}  ${p.lime(p.bold(start.user_code))}  ${p.dim('check that the page shows the same code, then approve')}\n\n` +
+        // In color the spinner below draws this line, so it moves while sign-in waits.
+        (lit ? '' : `    ${p.dim('Waiting for you to approve...')}\n`) +
+        (pick ? `    ${p.dim('esc or ctrl+c to cancel')}\n` : ''));
+    if (!noBrowser)
         openUrl(start.verification_uri_complete);
+    const spinner = lit ? waiting(io.stderr, p) : null;
+    // At a terminal, Esc or Ctrl+C stops the wait, as they do everywhere else.
+    const cancel = pick ? cancelKeys((pick.keys ?? keyboard)()) : null;
+    try {
+        return await pollForApproval(input, opts, { url, start, name, spinner, cancel: cancel?.pressed ?? null });
+    }
+    finally {
+        spinner?.stop();
+        cancel?.close();
+    }
+}
+/** 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 = '⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏';
+    let k = 0;
+    const draw = () => write(`\r    ${p.lime(frames[k++ % frames.length])} ${p.dim(words)}`);
+    draw();
+    const timer = setInterval(draw, 80);
+    // The spinner never keeps the process alive on its own.
+    timer.unref?.();
+    let stopped = false;
+    const stop = (line = '') => {
+        if (stopped)
+            return;
+        stopped = true;
+        clearInterval(timer);
+        write(`\r\x1b[2K${line}`);
+    };
+    return { stop: () => stop(), done: () => stop(`    ${p.lime('✓')} ${doneWords}\n`) };
+}
+/** Asks the server for the approved key until it comes, the code expires, or it fails. */
+async function pollForApproval(input, opts, ctx) {
+    const { env, io } = input;
+    const { url, start, name, spinner, cancel } = ctx;
+    const p = paint(env, colorOn(env, io.isTTY));
     let interval = Math.max(1, start.interval) * 1000;
     const deadline = Date.now() + Math.min(600, start.expires_in) * 1000;
     while (Date.now() < deadline) {
-        await new Promise((r) => setTimeout(r, interval));
+        const key = await Promise.race([new Promise((r) => setTimeout(() => r(null), interval)), cancel ?? new Promise(() => { })]);
+        if (key) {
+            spinner?.stop();
+            if (key === 'ctrl-c')
+                throw new Cancelled();
+            if (input.io.fromMenu)
+                throw new BackToMenu();
+            io.stderr('    Sign-in cancelled. Nothing was saved.\n');
+            return 0;
+        }
         let token;
         try {
             token = await wire(url, 'POST', '/auth/device/token', { device_code: start.device_code });
@@ -70,6 +152,7 @@ export async function workspaceLogin(input) {
             }
             throw error;
         }
+        spinner?.done();
         const saved = { version: 1, workspace_id: token.workspace_id, management_credential: token.management_token, base_url: url, recovery: token.recovery };
         try {
             writeSecret(env, credentialPath(env), JSON.stringify(saved));
@@ -82,7 +165,16 @@ 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;
         }
-        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');
+        if (opts.inSetup) {
+            io.stderr(`  ${p.lime('✓')} Signed in. Setting up your agents next.\n\n`);
+            return 0;
+        }
+        const result = { saved_as: name, key_name: token.key_name, workspace_id: token.workspace_id, storage: keychainOn(env) ? 'macOS Keychain' : 'private files' };
+        if (showsScreen(input)) {
+            io.stdout(signedInScreen(result, { env, color: colorOn(env, io.stdoutIsTTY) }) + '\n');
+            return 0;
+        }
+        io.stdout(JSON.stringify(result) + '\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;
     }
@@ -93,7 +185,8 @@ export async function workspaceCommand(input) {
     const { subcommand, flags, io, env, argv } = input;
     if (argv[0] === 'keys') {
         if (subcommand === 'saved' || subcommand === 'save' || subcommand === 'show' || subcommand === 'rm') {
-            return keyCommand({ ...input, flags: { ...(flags.balance ? { balance: flags.balance } : {}) }, subcommand: subcommand === 'saved' ? 'list' : subcommand });
+            // Only the flags the key command reads pass through; --copy must, or `keys show --copy` would print the key.
+            return keyCommand({ ...input, flags: { ...(flags.balance ? { balance: flags.balance } : {}), ...(flags.copy ? { copy: flags.copy } : {}) }, subcommand: subcommand === 'saved' ? 'list' : subcommand });
         }
         const remoteCommands = new Set(['list', 'create', 'rotate', 'revoke', 'set', undefined]);
         if (!remoteCommands.has(subcommand)) {
@@ -109,7 +202,7 @@ export async function workspaceCommand(input) {
             die('Invalid recovery file.');
         await wire(base(input), 'GET', '/workspaces/' + encodeURIComponent(recovery.workspace_id), undefined, recovery.management_credential);
         writeSecret(env, credentialPath(env), JSON.stringify({ ...recovery, base_url: base(input), recovery }));
-        io.stdout('Workspace restored. Use phantom keys create to save a new API key.\n');
+        io.stdout(showsScreen(input) ? `\n  ${paint(env, colorOn(env, io.stdoutIsTTY)).lime('✓')} Workspace restored. Make a new key with phantom keys create.\n` : 'Workspace restored. Use phantom keys create to save a new API key.\n');
         return 0;
     }
     const saved = credentials(input);
@@ -120,37 +213,72 @@ export async function workspaceCommand(input) {
         if (typeof flags.file !== 'string')
             die('Use phantom workspace export --file <path>.');
         writeFileSync(flags.file, JSON.stringify(saved.recovery, null, 2), { mode: 0o600, flag: 'wx' });
-        io.stdout('Recovery exported. Keep that file private; it grants workspace management.\n');
+        io.stdout(showsScreen(input) ? `\n  ${paint(env, colorOn(env, io.stdoutIsTTY)).lime('✓')} Recovery saved to ${flags.file}. Keep that file private: it can manage this workspace.\n` : 'Recovery exported. Keep that file private; it grants workspace management.\n');
         return 0;
     }
     if (command === 'create' || command === 'rotate') {
-        if (command === 'rotate' && typeof flags.id !== 'string')
-            die('Use --id <key-id> from phantom keys list.');
-        const name = typeof flags.save === 'string' ? flags.save : 'default';
         if (flags.save === true)
             die('--save requires a key name.');
+        // keys create at a terminal with nothing given: a short form (name, then limit), and the key to hand over.
+        if (command === 'create' && flags.save === undefined && flags.limit === undefined) {
+            const pick = pickIo(input);
+            if (pick)
+                return newKeyForm(input, pick, saved, endpoint);
+        }
+        const which = command === 'rotate' ? await whichKey(input, saved, endpoint, 'rotate') : null;
+        if (command === 'rotate' && which === null)
+            return 0;
+        const id = which?.id ?? null;
+        // Rotating a key saved on this computer replaces that saved copy, whatever its name.
+        const mine = id ? savedNameFor(env, id) : null;
+        const name = typeof flags.save === 'string' ? flags.save : (mine ?? 'default');
         const target = name === 'default' ? keyPath(env) : namedKeyPath(env, name);
         const replacing = existsSync(target);
-        if (replacing && (command !== 'rotate' || createHash('sha256').update(readSecret(env, target).trim()).digest('hex') !== flags.id))
-            die('That saved key already exists. Use --save <new-name>.', 'key_exists');
-        const result = await wire(saved.base_url, 'POST', command === 'create' ? endpoint + '/keys' : endpoint + '/keys/' + String(flags.id), command === 'create' ? { name, limit_usd: flags.limit === undefined ? null : Number(flags.limit) } : { action: 'rotate' }, saved.management_credential);
+        if (replacing && name !== mine)
+            die(`A key is already saved here as "${name}". Pick another name with --save <name>.`, 'key_exists');
+        const limit = flags.limit === undefined ? null : Number(flags.limit);
+        const result = await wire(saved.base_url, 'POST', command === 'create' ? endpoint + '/keys' : endpoint + '/keys/' + String(id), command === 'create' ? { name, limit_usd: limit } : { action: 'rotate' }, saved.management_credential);
         if (name === 'default')
             saveApiKey(env, result.api_key);
         else
             saveNamedKey(env, name, result.api_key, { replace: replacing });
-        io.stdout(JSON.stringify({ saved_as: name }) + '\n');
+        io.stdout(showsScreen(input) ? keyChangeScreen(command === 'create' ? 'created' : 'rotated', name, { env, color: colorOn(env, io.stdoutIsTTY), storage: keychainOn(env) ? 'macOS Keychain' : 'private files', limit }) + '\n' : JSON.stringify({ saved_as: name }) + '\n');
         return 0;
     }
     if (command === 'revoke') {
-        if (typeof flags.id !== 'string')
-            die('Use phantom keys revoke --id <key-id>.');
-        await wire(saved.base_url, 'DELETE', endpoint + '/keys/' + flags.id, undefined, saved.management_credential);
-        io.stdout('Key revoked.\n');
+        const which = await whichKey(input, saved, endpoint, 'revoke');
+        if (which === null)
+            return 0;
+        // At a terminal, revoking asks first and names the key: it can't be undone.
+        const pick = flags['yes'] ? null : pickIo(input);
+        if (pick) {
+            const go = await choose({ ...pick, esc: 'back' }, `Revoke ${which.name}?`, [
+                { label: `Revoke ${which.name}`, hint: 'anything using it stops working at once; its credit stays', value: true },
+                { label: 'Cancel', hint: 'keep it', value: false },
+            ], 1);
+            if (!go) {
+                io.stderr('  Nothing was changed.\n');
+                return 0;
+            }
+        }
+        await wire(saved.base_url, 'DELETE', endpoint + '/keys/' + which.id, undefined, saved.management_credential);
+        io.stdout(showsScreen(input) ? keyChangeScreen('revoked', null, { env, color: colorOn(env, io.stdoutIsTTY) }) + '\n' : 'Key revoked.\n');
         return 0;
     }
     if (command === 'set') {
-        if (typeof flags.id !== 'string')
-            die('Use phantom keys set --id <key-id>.');
+        const which = await whichKey(input, saved, endpoint, 'change');
+        if (which === null)
+            return 0;
+        const id = which.id;
+        // No change given, at a terminal: the usual change, a spending limit, as a picker.
+        const anyChange = ['limit', 'budget', 'period', 'rate', 'name', 'policy-file', 'clear-policy'].some((k) => flags[k] !== undefined);
+        const pick = anyChange ? null : pickIo(input);
+        if (pick) {
+            const limit = await chooseLimit(pick);
+            if (limit === undefined)
+                return 0;
+            flags.limit = limit === null ? 'none' : String(limit);
+        }
         const body = {};
         const controls = { limit_usd: flags.limit, budget_usd: flags.budget, period_days: flags.period, rate_usd_per_min: flags.rate };
         for (const [field, value] of Object.entries(controls))
@@ -162,47 +290,75 @@ export async function workspaceCommand(input) {
             body.route_policy = JSON.parse(readFileSync(flags['policy-file'], 'utf8'));
         if (flags['clear-policy'])
             body.route_policy = null;
-        const result = await wire(saved.base_url, 'PATCH', endpoint + '/keys/' + flags.id, body, saved.management_credential);
-        io.stdout(JSON.stringify(result) + '\n');
+        const result = await wire(saved.base_url, 'PATCH', endpoint + '/keys/' + id, body, saved.management_credential);
+        io.stdout(showsScreen(input) ? keyChangeScreen('updated', null, { env, color: colorOn(env, io.stdoutIsTTY) }) + '\n' : JSON.stringify(result) + '\n');
         return 0;
     }
     if (command === 'revoke-access') {
         if (typeof flags.id !== 'string')
             die('Use --id <management-id> from phantom workspace status.');
         await wire(saved.base_url, 'DELETE', endpoint + '/access/' + flags.id, undefined, saved.management_credential);
-        io.stdout('Management access revoked.\n');
+        io.stdout(showsScreen(input) ? `\n  ${paint(env, colorOn(env, io.stdoutIsTTY)).lime('✓')} That sign-in can no longer manage this workspace.\n` : 'Management access revoked.\n');
         return 0;
     }
     if (command === 'payment') {
         if (typeof flags.id !== 'string')
             die('Use --id <payment-id> from phantom workspace fund.');
-        io.stdout(JSON.stringify(await wire(saved.base_url, 'GET', endpoint + '/payments/' + flags.id, undefined, saved.management_credential)) + '\n');
+        const payment = await wire(saved.base_url, 'GET', endpoint + '/payments/' + flags.id, undefined, saved.management_credential);
+        io.stdout((showsScreen(input) ? paymentScreen(payment, { env, color: colorOn(env, io.stdoutIsTTY) }) : JSON.stringify(payment)) + '\n');
         return 0;
     }
     if (command === 'fund') {
         if (flags.pay)
             die('--pay has been removed. Use --card or --coin.');
-        if (!flags.card && !flags.coin)
-            die('fund requires --card or --coin.');
-        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 (flags.coin === true)
+            die(`--coin needs usdc, usdt or sol. ${FUND_EXAMPLE}`);
+        let amount = dollarsFlag(flags);
+        let method = flags.card ? 'card' : flags.coin;
+        // At a terminal, whatever is missing is asked for: first how much, then how to pay.
+        const pick = amount === undefined || !method ? pickIo(input) : null;
+        if (pick && amount === undefined) {
+            amount = (await choose(pick, 'How much credit do you want to add?', [5, 10, 25, 50, 100].map((n) => ({ label: `$${n}`, value: n })), 1)) ?? undefined;
+            if (amount === undefined)
+                return leaveFund(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: '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' },
+            ])) ?? undefined;
+            if (!method)
+                return leaveFund(input);
+        }
+        if (amount === undefined || !method)
+            die(`fund needs how much and how to pay. ${FUND_EXAMPLE}`, 'fund_usage');
+        const result = await wire(saved.base_url, 'POST', endpoint + '/fund', { method: method === 'card' ? 'card' : 'crypto', amount_usd: amount, coin: method === 'card' ? 'usdc' : method }, saved.management_credential);
+        io.stdout((showsScreen(input) ? fundScreen(result, { env, color: colorOn(env, io.stdoutIsTTY), opened: Boolean(result.checkout_url) && !flags['no-browser'] }) : JSON.stringify(result)) + '\n');
         if (result.checkout_url && !flags['no-browser'])
             openUrl(result.checkout_url);
+        // At a terminal, wait for the payment to land, so nobody wonders whether it worked.
+        const watch = pickIo(input);
+        if (watch && result.payment_id)
+            await waitForPayment(input, watch, saved, endpoint, result.payment_id);
         return 0;
     }
     const view = await wire(saved.base_url, 'GET', endpoint, undefined, saved.management_credential);
+    if (showsScreen(input)) {
+        const style = { env, color: colorOn(env, io.stdoutIsTTY) };
+        io.stdout((argv[0] === 'keys' ? keysScreen(view.keys, style) : workspaceScreen(view, style)) + '\n');
+        return 0;
+    }
     io.stdout(JSON.stringify(argv[0] === 'keys' ? view.keys : view, null, 2) + '\n');
     return 0;
 }
-/** Forget local management credentials and revoke server management access, leaving server-side keys and recovery files valid. */
+/** Forget local management credentials and revoke server management access, leaving server-side keys and recovery files valid. True when there was a workspace sign-in to forget. */
 export async function forgetWorkspace(env, baseUrl) {
     const file = credentialPath(env);
-    if (existsSync(file)) {
+    if (!existsSync(file))
+        return false;
+    {
         try {
             const saved = JSON.parse(readSecret(env, file));
             if (saved?.workspace_id && saved?.management_credential) {
@@ -215,4 +371,171 @@ export async function forgetWorkspace(env, baseUrl) {
         }
         removeSecret(file);
     }
+    return true;
+}
+/** The working fund command every fund error shows, so one try is enough. */
+const FUND_EXAMPLE = 'For example: phantom fund --amount 10 --card (or --coin usdc).';
+/**
+ * `--amount` as dollars: `10`, `10.50` or `$10`. A bare `--amount` is
+ * usually `--amount $5` after the shell has replaced `$5` with nothing, so
+ * the message says to leave out the $.
+ */
+export function dollarsFlag(flags) {
+    const raw = flags['amount'];
+    if (raw === undefined)
+        return undefined;
+    if (raw === true || raw.trim() === '')
+        die(`--amount needs a number of dollars, like --amount 10. Leave out the $: the shell drops "$5". ${FUND_EXAMPLE}`, 'fund_usage');
+    const n = Number(raw.trim().replace(/^\$/, ''));
+    if (!Number.isFinite(n) || n <= 0)
+        die(`--amount must be a number of dollars above 0, not "${raw}". ${FUND_EXAMPLE}`, 'fund_usage');
+    return n;
+}
+/** Esc out of fund's pickers: back to the menu if it started this, otherwise say nothing was charged. */
+function leaveFund(input) {
+    if (input.io.fromMenu)
+        throw new BackToMenu();
+    input.io.stderr('  Nothing was charged.\n');
+    return 0;
+}
+/**
+ * The key a key command acts on. --id may be the id, its first few
+ * characters, the key's name, or the start of the key, the way people
+ * remember it. With no --id at a terminal, it asks with a picker. Null means
+ * Esc: nothing was done.
+ */
+async function whichKey(input, saved, endpoint, verb) {
+    const { flags } = input;
+    const view = await wire(saved.base_url, 'GET', endpoint, undefined, saved.management_credential);
+    const named = (id) => ({ id, name: view.keys.find((k) => k.id === id)?.name ?? 'Key' });
+    if (typeof flags.id === 'string')
+        return named(findKey(view.keys, flags.id));
+    const pick = pickIo(input);
+    if (!pick)
+        die(`Say which key with --id: its id, name or start. For example: phantom keys ${verb === 'change' ? 'set' : verb} --id CI${verb === 'change' ? ' --limit 5' : ''}`, 'key_usage');
+    const chosen = await choose(pick, `Which key do you want to ${verb}?`, view.keys.map((k) => ({ label: k.name ?? 'Key', hint: `${k.prefix ?? ''} · id ${k.id.slice(0, 8)} · spent $${(k.spent_usd ?? 0).toFixed(2)}`, value: k.id })));
+    if (chosen === null && input.io.fromMenu)
+        throw new BackToMenu();
+    if (chosen === null)
+        input.io.stderr('  Nothing was changed.\n');
+    return chosen === null ? null : named(chosen);
+}
+/** Finds one key by id, the start of its id, its name, or the start of the key itself. Refuses when none or more than one matches. */
+export function findKey(keys, typed) {
+    const t = typed.trim().toLowerCase();
+    const hits = keys.filter((k) => k.id.toLowerCase() === t);
+    const loose = hits.length ? hits : keys.filter((k) => (t.length >= 4 && k.id.toLowerCase().startsWith(t)) || k.name?.toLowerCase() === t || (t.length >= 8 && k.prefix?.toLowerCase().startsWith(t)));
+    const list = keys.map((k) => `${k.name ?? 'Key'} (${k.id.slice(0, 8)})`).join(', ');
+    if (loose.length === 1)
+        return loose[0].id;
+    if (!loose.length)
+        die(`No key matches "${typed}". Your keys: ${list || 'none yet'}.`, 'key_not_found');
+    die(`"${typed}" matches more than one key: ${loose.map((k) => `${k.name ?? 'Key'} (${k.id.slice(0, 8)})`).join(', ')}. Use more of the id.`, 'key_ambiguous');
+}
+/** The name a key with this id is saved under on this computer, if any: `default` for the login key. */
+function savedNameFor(env, id) {
+    const hash = (key) => createHash('sha256').update(key.trim()).digest('hex');
+    if (existsSync(keyPath(env)) && hash(readSecret(env, keyPath(env))) === id)
+        return 'default';
+    for (const k of listNamedKeys(env).keys) {
+        try {
+            if (hash(readNamedKey(env, k.name)) === id)
+                return k.name;
+        }
+        catch {
+            // A saved key that can't be read is skipped: it can't be the one being rotated.
+        }
+    }
+    return null;
+}
+/** A limit picker: no limit, or a few round amounts. undefined means Esc. */
+async function chooseLimit(pick) {
+    const limit = await choose({ ...pick, esc: 'back' }, 'Spending limit for this key?', [
+        { label: 'No limit', hint: 'it can spend the whole workspace balance', value: 'none' },
+        ...[5, 10, 25, 50, 100].map((n) => ({ label: `$${n}`, hint: 'then it stops working until you raise it', value: n })),
+    ]);
+    return limit === null ? undefined : limit === 'none' ? null : limit;
+}
+/**
+ * keys create at a terminal: name the key, pick a limit, create it, and save
+ * it here. Then, on a Mac, offer to copy it to the clipboard to hand to a
+ * teammate. The key is never printed: only keys show and rotate print one.
+ */
+async function newKeyForm(input, pick, saved, endpoint) {
+    const { env, io } = input;
+    const name = await askText({ ...pick, esc: 'back' }, 'Name this key', {
+        placeholder: 'for example ci or dana',
+        check: (text) => (!/^[a-z0-9][a-z0-9_-]{0,31}$/i.test(text) ? 'Start with a letter or number; then letters, numbers, - and _, up to 32.' : existsSync(namedKeyPath(env, text)) ? `A key is already saved here as "${text}". Type another name.` : null),
+    });
+    if (name === null)
+        return leaveKeys(input);
+    const limit = await chooseLimit(pick);
+    if (limit === undefined)
+        return leaveKeys(input);
+    const result = await wire(saved.base_url, 'POST', endpoint + '/keys', { name, limit_usd: limit }, saved.management_credential);
+    saveNamedKey(env, name, result.api_key);
+    const style = { env, color: colorOn(env, io.stdoutIsTTY), storage: keychainOn(env) ? 'macOS Keychain' : 'private files', limit };
+    io.stdout(keyChangeScreen('created', name, style) + '\n');
+    if (process.platform === 'darwin' && onPath('pbcopy')) {
+        const copy = await choose({ ...pick, esc: 'back' }, 'Hand it to someone?', [
+            { label: 'Copy the key to the clipboard', hint: 'then paste it to your teammate; it is not shown here', value: true },
+            { label: 'No, keep it saved here only', value: false },
+        ]);
+        if (copy) {
+            spawnSync('pbcopy', { input: result.api_key });
+            io.stderr(`  ${paint(env, colorOn(env, io.isTTY)).lime('✓')} Copied. Paste it somewhere private: it works like a password.\n`);
+        }
+    }
+    return 0;
+}
+/** Esc out of a key form: back to the menu if it started this, otherwise say nothing changed. */
+function leaveKeys(input) {
+    if (input.io.fromMenu)
+        throw new BackToMenu();
+    input.io.stderr('  Nothing was changed.\n');
+    return 0;
+}
+/** How often fund checks whether a payment has landed, and for how long, in milliseconds. */
+const PAYMENT_POLL_MS = 2000;
+const PAYMENT_WAIT_MS = 15 * 60 * 1000;
+/**
+ * After fund opens the payment page: a spinner until the payment lands, then
+ * the paid screen. Esc stops waiting (the payment still goes through if it's
+ * finished); Ctrl+C stops everything.
+ */
+async function waitForPayment(input, pick, saved, endpoint, paymentId) {
+    const { env, io } = input;
+    const p = paint(env, colorOn(env, io.isTTY));
+    io.stderr(`    ${p.dim('esc to stop waiting')}\n`);
+    const spinner = colorOn(env, io.isTTY) ? waiting(io.stderr, p, 'Waiting for your payment...', 'Payment received.') : null;
+    const cancel = cancelKeys((pick.keys ?? keyboard)());
+    const deadline = Date.now() + PAYMENT_WAIT_MS;
+    try {
+        while (Date.now() < deadline) {
+            const payment = await wire(saved.base_url, 'GET', endpoint + '/payments/' + encodeURIComponent(paymentId), undefined, saved.management_credential);
+            if (payment.status === 'completed') {
+                spinner?.done();
+                io.stdout(paymentScreen(payment, { env, color: colorOn(env, io.stdoutIsTTY) }) + '\n');
+                // The new balance right away, so nobody has to go and check that it arrived.
+                const view = await wire(saved.base_url, 'GET', endpoint, undefined, saved.management_credential);
+                if (typeof view.balance_usd === 'number')
+                    io.stdout(`  ${p.dim('Workspace balance now')} ${p.bold(`$${view.balance_usd.toFixed(2)}`)}\n`);
+                return;
+            }
+            const key = await Promise.race([new Promise((r) => setTimeout(() => r(null), PAYMENT_POLL_MS)), cancel.pressed]);
+            if (key === 'ctrl-c')
+                throw new Cancelled();
+            if (key) {
+                spinner?.stop();
+                io.stderr(`  ${p.dim('Stopped waiting. If you finish paying, the credit still lands: check Balance.')}\n`);
+                return;
+            }
+        }
+        spinner?.stop();
+        io.stderr(`  ${p.dim('No payment yet. If you finish paying, the credit still lands: check Balance.')}\n`);
+    }
+    finally {
+        spinner?.stop();
+        cancel.close();
+    }
 }

package/package.json

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

package/skills/phantom-ai/SKILL.md

@@ -7,8 +7,9 @@ description: Use the phantom CLI to connect and run coding agents through Phanto
 
 Phantom AI serves model inference at `https://phantom.codes/v1`. The Phantom CLI connects
 existing coding agents to that API, manages model routing to control costs, and
-handles workspace funding and controls. Management commands
-print JSON; add `--table` for supported human-readable output.
+handles workspace funding and controls. Run from an agent (output piped),
+commands print JSON; add `--table` for the human-readable screen. Unknown
+flags are refused, so check `phantom <command> --help` for the flag names.
 
 ## Connect and run