@phnx-labs/agents-cli 1.20.70 → 1.20.72

package/dist/commands/secrets.js

@@ -20,7 +20,8 @@ import { bundleExists, bundleItemStore, bundlePolicy, deleteBundle, describeBund
 import { encryptForFallback, decryptForFallback } from '../lib/secrets/filestore.js';
 import { getKeychainToken, getKeychainTokens, hasKeychainToken, secretsKeychainItem, setKeychainToken, } from '../lib/secrets/index.js';
 import { assertOpAvailable, createPasswordItem, deleteItemByTitle, extractSecrets, itemExistsByTitle, listItems, listVaults, } from '../lib/onepassword.js';
-import { secretsHoldMs, agentLoad, agentLock, agentPing, agentStatus, ensureAgentRunning, runAgentLoadFromStdin, runSecretsAgent, uninstallSecretsAgentService, } from '../lib/secrets/agent.js';
+import { secretsHoldMs, secretsAgentDurable, agentLoad, agentLock, agentPing, agentStatus, ensureAgentRunning, runAgentLoadFromStdin, runSecretsAgent, uninstallSecretsAgentService, } from '../lib/secrets/agent.js';
+import { saveSession, deleteSession, deleteAllSessions } from '../lib/secrets/session-store.js';
 import { getCliVersionFresh } from '../lib/version.js';
 import { readMeta } from '../lib/state.js';
 import { parseDuration } from '../lib/hooks/cache.js';
@@ -249,6 +250,9 @@ export function buildRemoteUnlockArgs(names, opts) {
         'unlock',
         ...(opts.all ? ['--all'] : names),
         ...(opts.ttl ? ['--ttl', opts.ttl] : []),
+        // Forward --durable so a remote unlock honors it too; without this the remote
+        // silently falls back to its own secrets.agent.durable default (off).
+        ...(opts.durable ? ['--durable'] : []),
     ];
 }
 // SSH target validation is defined canonically in src/lib/ssh-exec.ts and
@@ -1840,6 +1844,7 @@ Examples:
         .command('unlock [names...]')
         .description('Hold a bundle in the secrets-agent after one Touch ID, so concurrent runs read it without re-prompting (macOS). With --host, unlock FILE-backed bundle(s) on a remote (the passphrase prompt surfaces over the SSH TTY); keychain/biometry bundles are GUI-only and can\'t be remote-unlocked.')
         .option('--ttl <duration>', 'How long to hold it (e.g. 30m, 8h, 3d). Default 7d.')
+        .option('--durable', 'Keep the unlock across sleep + reboot too (default: survives upgrade/restart but re-locks on sleep). Set secrets.agent.durable in agents.yaml to make this the default.')
         .option('--all', 'Unlock every configured bundle')
         .option('--host <target>', 'Unlock the bundle(s) on this remote machine over SSH instead of locally (file-backed bundles only — the remote\'s passphrase prompt surfaces on your terminal over a -tt session). Single-valued (NOT variadic) so it never swallows the bundle name: `unlock <name> --host <machine>`.')
         .action(async (names, opts) => {
@@ -1880,8 +1885,12 @@ Examples:
             return;
         }
         if (process.platform !== 'darwin') {
-            console.error(chalk.red('secrets-agent is macOS-only (no biometry prompt to deduplicate elsewhere).'));
-            process.exit(1);
+            // No broker + no biometry prompt off darwin: secrets already resolve
+            // durably from the OS store (libsecret / Credential Manager) on every
+            // read with no prompt, so an unlock is a friendly no-op — not an error.
+            // Accept --durable as a documented no-op so the command is uniform.
+            console.log(chalk.gray('Nothing to unlock: secrets already persist on this OS — reads never re-prompt.'));
+            return;
         }
         let targets = opts.all ? listBundles().map((b) => b.name) : names;
         if (!targets || targets.length === 0) {
@@ -1915,6 +1924,14 @@ Examples:
                 const { bundle, env } = readAndResolveBundleEnv(name, { noAgent: true, caller: 'unlock' });
                 if (await agentLoad(name, bundle, env, ttlMs)) {
                     loaded++;
+                    // Persist a durable session snapshot so the unlock survives a daemon
+                    // restart / upgrade (and sleep too, with --durable). session-store.ts.
+                    saveSession(name, {
+                        bundle,
+                        env,
+                        expiresAt: Date.now() + ttlMs,
+                        sleepPersist: opts.durable ?? secretsAgentDurable(),
+                    });
                     console.log(`${chalk.green('unlocked')} ${chalk.cyan(name)} ${chalk.gray(`(${Object.keys(env).length} keys, ${humanRemaining(Date.now() + ttlMs)})`)}`);
                 }
                 else {
@@ -1941,12 +1958,15 @@ Examples:
             return; // nothing to lock off darwin
         if (names && names.length > 0 && !opts.all) {
             let total = 0;
-            for (const name of names)
+            for (const name of names) {
                 total += await agentLock(name);
+                deleteSession(name); // also drop the durable snapshot, or a restart re-warms it
+            }
             console.log(total > 0 ? chalk.green(`Locked ${total} bundle(s).`) : chalk.gray('Nothing to lock.'));
         }
         else {
             const wiped = await agentLock();
+            deleteAllSessions();
             console.log(wiped > 0 ? chalk.green(`Locked ${wiped} bundle(s).`) : chalk.gray('Nothing to lock.'));
         }
     });

package/dist/commands/sessions-tail.js

@@ -218,8 +218,7 @@ export function registerSessionsTailCommand(sessionsCmd) {
         .command('tail [sessionId]')
         .description('Stream JSONL events from a session file as they are written, one event per line. Long-running: Ctrl+C to stop. Claude and Codex only.')
         .option('--latest', 'Tail the most recent tailable session (claude or codex)')
-        .option('--from-start', 'Emit the full file first, then follow (default: start at EOF)')
-        .option('--json', 'Raw JSONL passthrough (default)');
+        .option('--from-start', 'Emit the full file first, then follow (default: start at EOF)');
     setHelpSections(tailCmd, {
         examples: `
       # Follow the most recent active Claude or Codex session

package/dist/commands/sessions.d.ts

@@ -155,6 +155,12 @@ export declare function buildOverviewGroups(pool: SessionMeta[], perProjectCap:
  * (`agents logs <id> --full`). Reuses the shared `renderSession` renderer.
  */
 export declare function renderSessionLog(session: SessionMeta, mode?: ViewMode): Promise<void>;
+/**
+ * Emit one session exactly as `agents sessions <id> --json` does — the same
+ * redact-by-default `{ session, events }` shape — so `agents logs <id> --json`
+ * shares one machine-readable session contract instead of inventing another.
+ */
+export declare function renderSessionLogJson(session: SessionMeta): Promise<void>;
 /** Column-visibility flags for the picker row, computed once over the whole pool. */
 export interface PickerColumns {
     /** Render the machine column (only when the pool spans more than one machine). */

package/dist/commands/sessions.js

@@ -998,7 +998,7 @@ async function sessionsAction(query, options) {
     // When the user explicitly asks to render (via mode flag), resolve the
     // query globally so sessions outside the default cwd/30d window are found.
     if (wantsRender && searchQuery) {
-        await renderOneSession(searchQuery, mode, { agent: options.agent, project: options.project, filter: filterOpts, noRedact: options.noRedact });
+        await renderOneSession(searchQuery, mode, { agent: options.agent, project: options.project, filter: filterOpts, redact: options.redact });
         return;
     }
     // Interactive picker loads a deep pool but shows only recent sessions
@@ -1068,7 +1068,7 @@ async function sessionsAction(query, options) {
                 return;
             }
             if (idMatches.length === 0 && looksLikeSessionId(searchQuery)) {
-                await renderOneSession(searchQuery, mode, { agent: options.agent, project: options.project, filter: filterOpts, noRedact: options.noRedact });
+                await renderOneSession(searchQuery, mode, { agent: options.agent, project: options.project, filter: filterOpts, redact: options.redact });
                 return;
             }
         }
@@ -1422,6 +1422,14 @@ function resolveViewMode(options, filters) {
 export async function renderSessionLog(session, mode = 'summary') {
     await renderSession(session, mode, {});
 }
+/**
+ * Emit one session exactly as `agents sessions <id> --json` does — the same
+ * redact-by-default `{ session, events }` shape — so `agents logs <id> --json`
+ * shares one machine-readable session contract instead of inventing another.
+ */
+export async function renderSessionLogJson(session) {
+    await renderSession(session, 'json', {});
+}
 async function renderSession(session, mode, filters, options = {}) {
     // OpenCode stores sessions in SQLite; filePath is "db_path#session_id"
     const realPath = session.filePath.split('#')[0];
@@ -1475,7 +1483,7 @@ async function renderSession(session, mode, filters, options = {}) {
             chalk.gray(` ${formatRelativeTime(session.timestamp)}`) +
             (session.account ? chalk.gray(` (${session.account})`) : ''));
         console.log(chalk.gray('─'.repeat(60)));
-        process.stdout.write(renderMarkdown(renderConversationMarkdown(events, { redact: options.noRedact !== true })));
+        process.stdout.write(renderMarkdown(renderConversationMarkdown(events, { redact: options.redact !== false })));
         return;
     }
     // json — normalized events plus the durable session signals from the state
@@ -1486,7 +1494,7 @@ async function renderSession(session, mode, filters, options = {}) {
     // checklist reflects true session state regardless of any `--include` filter;
     // it lets the Factory panel read the CLI's checklist instead of re-parsing.
     const todos = inferSessionState(parsedEvents, { cwd: session.cwd }).todos;
-    process.stdout.write(renderJson(events, todos ? { ...session, todos } : session));
+    process.stdout.write(renderJson(events, todos ? { ...session, todos } : session, { redact: options.redact !== false }));
 }
 function renderTopicCell(label, topic, query, visibleWidth, paddedWidth) {
     const lbl = (label ?? '').trim();
@@ -2162,7 +2170,7 @@ async function renderOneSession(query, mode, scope) {
             throw new Error('Session resolution failed');
         }
         spinner.stop();
-        await renderSession(session, mode, scope.filter, { noRedact: scope.noRedact });
+        await renderSession(session, mode, scope.filter, { redact: scope.redact });
     }
     catch (err) {
         if (isPromptCancelled(err))
@@ -2195,7 +2203,7 @@ export function registerSessionsCommands(program) {
         .option('-n, --limit <n>', 'Maximum number of sessions to return', '50')
         .option('--sort <field>', 'Sort the list by: recent (default), cost, or duration')
         .option('--markdown', 'Render the session as markdown (user, assistant, thinking, tool calls)')
-        .option('--no-redact', 'Disable default secret redaction in markdown session output')
+        .option('--no-redact', 'Disable default secret redaction in rendered session output (--markdown and --json)')
         .option('--json', 'Output JSON (session list when browsing, event array when rendering one session)')
         .option('--include <roles>', 'Only include these roles (comma-separated): user, assistant, thinking, tools')
         .option('--exclude <roles>', 'Exclude these roles (comma-separated): user, assistant, thinking, tools')

package/dist/commands/skills.js

@@ -45,6 +45,7 @@ When to use:
         .command('list [agent]')
         .description('Show which skills are installed and which agent versions they are synced to')
         .option('-a, --agent <agent>', 'Filter to a specific agent (alternative to positional arg)')
+        .option('--json', 'Emit machine-readable JSON instead of the table/picker')
         .action(async (agentArg, options) => {
         const spinner = ora({ text: 'Loading...', isSilent: !process.stdout.isTTY }).start();
         const agentInput = agentArg || options.agent;
@@ -74,6 +75,7 @@ When to use:
             centralPath: getSkillsDir(),
             filterAgent,
             filterVersion,
+            json: options.json,
         });
     });
     skillsCmd

package/dist/commands/ssh.js

@@ -18,6 +18,7 @@ import ora from 'ora';
 import { getCliVersion } from '../lib/version.js';
 import { readAndResolveBundleEnv, isHeadlessSecretsContext } from '../lib/secrets/bundles.js';
 import { machineId } from '../lib/session/sync/config.js';
+import { registerFleetCaptureCommand } from './fleet-capture.js';
 import { addIgnored, getDevice, loadDevices, loadIgnored, removeDevice, removeIgnored, upsertDevice, } from '../lib/devices/registry.js';
 import { addControlToken } from '../lib/serve/token.js';
 import { DEFAULT_SERVE_PORT } from '../lib/serve/server.js';
@@ -27,7 +28,7 @@ import { resolveDeviceTarget, splitUserHost } from '../lib/devices/resolve-targe
 import { clearPendingSentinel } from '../lib/devices/pending.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 import { hostNameFor, renderSshConfig } from '../lib/devices/ssh-config.js';
-import { ASKPASS_BUNDLE_ENV, ASKPASS_KEY_ENV, buildSshInvocation, writeAskpassShim, } from '../lib/devices/connect.js';
+import { ASKPASS_BUNDLE_ENV, ASKPASS_KEY_ENV, buildSshInvocation, fleetDialTarget, writeAskpassShim, } from '../lib/devices/connect.js';
 import { ensureManagedKnownHostsDir, isHostPinned } from '../lib/devices/known-hosts.js';
 import { shouldSyncTerminfo, syncTerminfoToDevice, terminfoHostKey } from '../lib/devices/terminfo.js';
 import { fanOutDevices, planFleetTargets, remoteFleetTargets, runFleet, skipLabel, upgradeCommand, } from '../lib/devices/fleet.js';
@@ -244,10 +245,10 @@ async function probeRemoteHealth(target) {
     const isWin = /^win/i.test((target.platform ?? '').trim());
     const env = isWin ? undefined : { PATH: '$HOME/.agents/.cache/shims:$HOME/.local/bin:$PATH' };
     const versionCmd = buildRemoteAgentsInvocation(['--version'], undefined, isWin ? 'windows' : undefined, env);
-    const versionRes = await sshExecAsync(target.name, versionCmd, { timeoutMs: 15000, multiplex: true });
+    const versionRes = await sshExecAsync(target.dialTarget, versionCmd, { timeoutMs: 15000, multiplex: true });
     const version = versionRes.code === 0 ? versionRes.stdout.trim().split(/\s+/)[0] || null : null;
     const doctorCmd = buildRemoteAgentsInvocation(['doctor', '--json'], undefined, isWin ? 'windows' : undefined, env);
-    const doctorRes = await sshExecAsync(target.name, doctorCmd, { timeoutMs: 30000, multiplex: true });
+    const doctorRes = await sshExecAsync(target.dialTarget, doctorCmd, { timeoutMs: 30000, multiplex: true });
     if (doctorRes.code !== 0) {
         throw new Error(doctorRes.timedOut ? 'timed out' : (doctorRes.stderr.trim() || `exit ${doctorRes.code ?? 'unknown'}`));
     }
@@ -280,6 +281,20 @@ async function runFleetStatus(opts) {
         name: t.device.name,
         platform: t.device.platform,
         skip: t.skip,
+        dialTarget: fleetDialTarget(t.device),
+        // Fail fast: the stats probe already tried this box with the same
+        // (registry) address. If it came back unreachable, don't spend another
+        // 15s+30s on version+doctor — skip straight to an unreachable row so one
+        // genuinely-offline device can't stall the whole matrix.
+        //
+        // Only trust this on a FRESH probe (`--refresh`/`--live`). loadFleetStats
+        // is cache-first (daemon-warmed ~3min), so a box that came back online
+        // since the last warm would otherwise be skipped to "unreachable" without
+        // a live attempt — a false negative. On a default run we still do the live
+        // probe (fast now that it dials the registry address).
+        ...(forceRefresh && statsMap.get(t.device.name)?.reachable === false && !t.skip
+            ? { skip: 'unreachable' }
+            : {}),
     }));
     const remote = await fanOutDevices(remoteTargets, probeRemoteHealth);
     for (const result of remote) {
@@ -333,7 +348,7 @@ async function probeRemoteAuth(target) {
     const isWin = /^win/i.test((target.platform ?? '').trim());
     const env = isWin ? undefined : { PATH: '$HOME/.agents/.cache/shims:$HOME/.local/bin:$PATH' };
     const cmd = buildRemoteAgentsInvocation(['devices', 'ping', '--local', '--json'], undefined, isWin ? 'windows' : undefined, env);
-    const res = await sshExecAsync(target.name, cmd, { timeoutMs: 60000, multiplex: true });
+    const res = await sshExecAsync(target.dialTarget, cmd, { timeoutMs: 60000, multiplex: true });
     if (res.code !== 0) {
         throw new Error(res.timedOut ? 'timed out' : (res.stderr.trim() || `exit ${res.code ?? 'unknown'}`));
     }
@@ -370,6 +385,7 @@ async function runFleetPing(opts) {
         name: t.device.name,
         platform: t.device.platform,
         skip: t.skip,
+        dialTarget: fleetDialTarget(t.device),
     }));
     const probeable = remoteTargets.filter((t) => !t.skip).length;
     const spinner = isInteractiveTerminal() && !opts.json
@@ -511,6 +527,8 @@ Typical workflow:
             process.exit(1);
         }
     });
+    // `agents fleet capture` — snapshot live state into agents.yaml fleet:.
+    registerFleetCaptureCommand(devicesCmd);
     devicesCmd
         .command('register <name>')
         .description('Register a discovered (pending) node by name — used by the menu-bar "NEW DEVICES → Register" action.')
@@ -781,7 +799,7 @@ Typical workflow:
             return;
         }
         console.log(chalk.gray(`Running \`${cmd.join(' ')}\` on ${targets.filter((t) => !t.skip).length} online device(s)…`));
-        const results = runFleet(targets, cmd);
+        const results = runFleet(targets, cmd, { self: machineId() });
         printFleetResults(results);
     });
     devicesCmd
@@ -800,7 +818,7 @@ Typical workflow:
             return;
         }
         console.log(chalk.gray(`Running \`${cmd.join(' ')}\` on ${targets.filter((t) => !t.skip).length} online device(s)…`));
-        const results = runFleet(targets, cmd);
+        const results = runFleet(targets, cmd, { self: machineId() });
         printFleetResults(results);
     });
 }

package/dist/commands/status.js

@@ -13,6 +13,7 @@ import { AGENTS } from '../lib/agents.js';
 import { setHelpSections } from '../lib/help.js';
 import { computeSyncStatus } from '../lib/sync-status.js';
 import { promptDriftSync } from '../lib/drift-sync.js';
+import { resolveSurface } from './utils.js';
 const agentName = (id) => AGENTS[id]?.name ?? id;
 function versionSummary(v) {
     if (!v.everSynced)
@@ -46,9 +47,14 @@ export function registerStatusCommand(program) {
       agents status --yes
     `,
     });
-    cmd.action(async (opts) => {
+    cmd.action(async (opts, command) => {
+        // Centralized surface read (the human/agent split in one place). Note we still
+        // pass the *raw* `opts.yes` to promptDriftSync below — it distinguishes an
+        // explicit `--yes` (act) from a non-TTY shell (report only), so `surface.assumeYes`
+        // (which conflates the two) would wrongly auto-reconcile in a plain pipe.
+        const surface = resolveSurface(command);
         const cwd = opts.cwd ?? process.cwd();
-        if (opts.json) {
+        if (surface.json) {
             const status = await computeSyncStatus({ cwd });
             console.log(JSON.stringify(status, null, 2));
             return;

package/dist/commands/subagents.js

@@ -53,7 +53,7 @@ When to use:
   - Team sharing: distribute subagent definitions via GitHub repos
 `);
     // Shared list implementation, registered as `list` and hidden `view` alias.
-    const runList = async () => {
+    const runList = async (opts) => {
         const rows = buildSubagentRows();
         await showResourceList({
             resourcePlural: 'subagents',
@@ -62,12 +62,14 @@ When to use:
             rows,
             emptyMessage: 'No subagents in ~/.agents/subagents/. Add one with: agents subagents add gh:user/repo',
             centralPath: getSubagentsDir(),
+            json: opts?.json,
         });
     };
     // agents subagents list
     subagentsCmd
         .command('list')
         .description('Show subagents in a table with sync status across agent versions')
+        .option('--json', 'Emit machine-readable JSON instead of the table/picker')
         .addHelpText('after', `
 Examples:
   # Interactive picker (TTY) or sync-status table (piped)

package/dist/commands/uninstall.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `agents uninstall` — completely remove agents-cli and restore the user's
+ * original agent configs. The reverse of `agents setup`.
+ *
+ * Thin command layer: the restore/teardown logic lives in `lib/uninstall.ts`
+ * (planUninstall / executeUninstall) so it can be tested against a real temp
+ * HOME without the CLI wrapper.
+ */
+import type { Command } from 'commander';
+/** Register `agents uninstall`. */
+export declare function registerUninstallCommands(program: Command): void;

package/dist/commands/uninstall.js

@@ -0,0 +1,158 @@
+import chalk from 'chalk';
+import { confirm } from '@inquirer/prompts';
+import { setHelpSections } from '../lib/help.js';
+import { planUninstall, executeUninstall } from '../lib/uninstall.js';
+import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
+/** Render the read-only plan so the user sees exactly what will change. */
+function printPlan(plan, purge) {
+    const restores = plan.configs.filter((c) => c.kind === 'restore-backup' || c.kind === 'restore-version-home');
+    const dangling = plan.configs.filter((c) => c.kind === 'remove-dangling');
+    const untouched = plan.configs.filter((c) => c.kind === 'leave-real' || c.kind === 'leave-foreign');
+    console.log(chalk.bold('\nagents uninstall — planned changes\n'));
+    if (restores.length > 0) {
+        console.log(chalk.green('Restore your original config (adopted by agents-cli):'));
+        for (const c of restores) {
+            const how = c.kind === 'restore-backup' ? 'from backup' : 'from version home';
+            console.log(chalk.gray(`  ${c.realPath}  ${chalk.dim(`(${how})`)}`));
+        }
+    }
+    if (dangling.length > 0) {
+        console.log(chalk.yellow('Remove dangling symlink (no original found to restore):'));
+        for (const c of dangling)
+            console.log(chalk.gray(`  ${c.realPath}`));
+    }
+    if (untouched.length > 0) {
+        console.log(chalk.cyan('Left untouched (real, un-adopted configs — never modified):'));
+        for (const c of untouched)
+            console.log(chalk.gray(`  ${c.realPath}`));
+    }
+    if (plan.homeFiles.length > 0) {
+        console.log(chalk.green('Restore home files:'));
+        for (const hf of plan.homeFiles)
+            console.log(chalk.gray(`  ${hf.realPath}`));
+    }
+    if (plan.launchers.length > 0) {
+        console.log(chalk.green('Release adopted launchers (restore native binaries on PATH):'));
+        console.log(chalk.gray(`  ${plan.launchers.join(', ')}`));
+    }
+    if (plan.rcFiles.length > 0) {
+        console.log(chalk.green('Remove the shim directory from PATH in:'));
+        for (const rc of plan.rcFiles)
+            console.log(chalk.gray(`  ${rc}`));
+    }
+    console.log(chalk.bold('\nData:'));
+    if (purge) {
+        console.log(chalk.red(`  Permanently delete ${plan.agentsDir} (installed versions, session history, secrets metadata).`));
+        if (plan.legacySymlink)
+            console.log(chalk.red(`  Permanently delete ${plan.legacySymlink}.`));
+    }
+    else {
+        console.log(chalk.gray(`  Move ${plan.agentsDir} aside to ${plan.agentsDir}.removed-<timestamp> (recoverable).`));
+        if (plan.legacySymlink)
+            console.log(chalk.gray(`  Remove the legacy symlink ${plan.legacySymlink}.`));
+        console.log(chalk.gray('  Use --purge to hard-delete instead.'));
+    }
+    console.log();
+}
+/** Report what actually happened, then the final manual npm step. */
+function printResult(result, cleanedPath) {
+    for (const r of result.restoredConfigs)
+        console.log(chalk.green(`Restored ${r.realPath}`));
+    for (const r of result.removedDanglingConfigs)
+        console.log(chalk.yellow(`Removed dangling symlink ${r.realPath}`));
+    for (const f of result.restoredHomeFiles)
+        console.log(chalk.green(`Restored ${f}`));
+    if (result.releasedLaunchers.length > 0)
+        console.log(chalk.green(`Released launchers: ${result.releasedLaunchers.join(', ')}`));
+    for (const rc of result.cleanedRcFiles)
+        console.log(chalk.green(`Cleaned shim PATH entry from ${rc}`));
+    if (result.agentsDir.disposition === 'moved') {
+        console.log(chalk.gray(`Moved ${result.agentsDir.path} to ${result.agentsDir.movedTo}`));
+    }
+    else if (result.agentsDir.disposition === 'purged') {
+        console.log(chalk.gray(`Deleted ${result.agentsDir.path}`));
+    }
+    for (const e of result.errors)
+        console.log(chalk.red(`  ! ${e}`));
+    if (result.purgeDowngraded) {
+        console.log(chalk.yellow(`\n--purge was downgraded to move-aside because a restore step errored — ${result.agentsDir.path} was kept so nothing is lost. Resolve the errors above, then delete ${result.agentsDir.movedTo} manually.`));
+    }
+    console.log(chalk.bold('\nFinish by removing the CLI package:'));
+    console.log(chalk.gray('  npm uninstall -g @phnx-labs/agents-cli    # or: bun remove -g @phnx-labs/agents-cli'));
+    if (cleanedPath) {
+        console.log(chalk.gray('Open a new shell (or re-source your rc file) so the removed PATH entry takes effect.'));
+    }
+    if (result.agentsDir.disposition === 'moved') {
+        console.log(chalk.gray(`Your data is still at ${result.agentsDir.movedTo} — delete it once you are sure.`));
+    }
+}
+/** Register `agents uninstall`. */
+export function registerUninstallCommands(program) {
+    const cmd = program
+        .command('uninstall')
+        .description('Completely remove agents-cli and restore your original agent configs. Reverses `agents setup`.')
+        .option('--purge', 'Hard-delete ~/.agents (installed versions, sessions, secrets metadata) instead of moving it aside')
+        .option('--dry-run', 'Show exactly what would change without modifying anything')
+        .option('-y, --yes', 'Skip the confirmation prompt (required to run non-interactively)');
+    setHelpSections(cmd, {
+        examples: `
+      # Preview everything that would change, without touching anything
+      agents uninstall --dry-run
+
+      # Restore your configs and move ~/.agents aside (recoverable)
+      agents uninstall
+
+      # Same, but hard-delete ~/.agents (no recovery)
+      agents uninstall --purge
+    `,
+        notes: `
+      - Restores every ~/.<agent> that agents-cli adopted; a real config it never adopted is left untouched.
+      - Releases adopted launchers and strips the shim directory from your shell PATH.
+      - Without --purge, ~/.agents is moved to ~/.agents.removed-<timestamp> so nothing is lost.
+      - The CLI cannot delete its own running binary; it prints the final 'npm uninstall -g' step for you.
+    `,
+    });
+    cmd.action(async (options) => {
+        // We are tearing ~/.agents down. Silence the JSONL audit log for the rest
+        // of this process so a late emit() (its events path is memoized to the old
+        // location) can't re-create ~/.agents after we move it aside.
+        process.env.AGENTS_DISABLE_EVENT_LOG = '1';
+        const plan = planUninstall();
+        if (!plan.isInstalled) {
+            console.log(chalk.gray('agents-cli is not set up (no ~/.agents directory) — nothing to uninstall.'));
+            return;
+        }
+        printPlan(plan, !!options.purge);
+        if (options.dryRun) {
+            console.log(chalk.gray('Dry run — nothing was changed.'));
+            return;
+        }
+        if (!options.yes) {
+            if (!isInteractiveTerminal()) {
+                console.log(chalk.red('Refusing to uninstall non-interactively. Re-run with --yes to confirm.'));
+                return;
+            }
+            try {
+                const ok = await confirm({
+                    message: options.purge
+                        ? 'Permanently remove agents-cli and restore your original configs?'
+                        : 'Remove agents-cli (data moved to a recoverable directory) and restore your original configs?',
+                    default: false,
+                });
+                if (!ok) {
+                    console.log(chalk.gray('Cancelled.'));
+                    return;
+                }
+            }
+            catch (err) {
+                if (isPromptCancelled(err)) {
+                    console.log(chalk.gray('Cancelled.'));
+                    return;
+                }
+                throw err;
+            }
+        }
+        const result = executeUninstall(plan, { purge: options.purge, timestamp: Date.now() });
+        printResult(result, result.cleanedRcFiles.length > 0);
+    });
+}

package/dist/commands/usage.d.ts

@@ -10,4 +10,17 @@
  *     don't publish per-account usage today)
  */
 import type { Command } from 'commander';
+import type { AgentId } from '../lib/types.js';
+import { getUsageInfoForIdentity } from '../lib/usage.js';
+/** One agent's usage snapshot — the unit the text and --json renderers share. */
+export interface AgentUsageRecord {
+    agent: AgentId;
+    /** Plain agent name (no ANSI) — safe to emit in --json; the text table colorizes it. */
+    label: string;
+    status: 'unsupported' | 'no-version' | 'not-signed-in' | 'ok';
+    email?: string;
+    usage?: Awaited<ReturnType<typeof getUsageInfoForIdentity>>;
+}
 export declare function registerUsageCommand(program: Command): void;
+/** Render one usage record as the human table section. */
+export declare function formatAgentUsage(rec: AgentUsageRecord): string;

package/dist/commands/usage.js

@@ -13,13 +13,15 @@ const USAGE_SUPPORTED = new Set(['claude', 'codex', 'kimi', 'droid']);
 export function registerUsageCommand(program) {
     addHostOption(program.command('usage [agent]'))
         .description('Show rate-limit / quota usage per agent')
+        .option('--json', 'Emit machine-readable JSON (per-agent usage snapshot) instead of the table')
         .addHelpText('after', `
 Examples:
   agents usage              Show usage for all installed agents
   agents usage claude       Show usage for Claude only
   agents usage codex        Show usage for Codex only
+  agents usage --json       Machine-readable snapshot for scripts
 `)
-        .action(async (agentFilter) => {
+        .action(async (agentFilter, options) => {
         let filter;
         if (agentFilter) {
             const resolved = resolveAgentName(agentFilter);
@@ -33,47 +35,67 @@ Examples:
             ? [filter]
             : ALL_AGENT_IDS.filter((id) => listInstalledVersions(id).length > 0);
         if (targets.length === 0) {
+            if (options.json) {
+                console.log('[]');
+                return;
+            }
             console.log(chalk.gray('No agents installed. Run `agents add <agent>` first.'));
             return;
         }
-        const sections = await Promise.all(targets.map(async (agentId) => renderAgentUsage(agentId)));
-        console.log(sections.filter(Boolean).join('\n\n'));
+        const records = await Promise.all(targets.map((agentId) => collectAgentUsage(agentId)));
+        if (options.json) {
+            console.log(JSON.stringify(records, null, 2));
+            return;
+        }
+        console.log(records.map(formatAgentUsage).filter(Boolean).join('\n\n'));
     });
 }
-async function renderAgentUsage(agentId) {
-    const cfg = AGENTS[agentId];
-    const heading = agentLabel(agentId);
+/** Gather one agent's usage snapshot as structured data (shared by both renderers). */
+async function collectAgentUsage(agentId) {
+    // Plain name — color is applied only at text-render time (formatAgentUsage), so
+    // `--json` never emits ANSI escapes in `label` (e.g. under FORCE_COLOR=1).
+    const label = AGENTS[agentId].name;
     if (!USAGE_SUPPORTED.has(agentId)) {
-        return [
-            `${heading}`,
-            `  ${chalk.dim(`${cfg.name} CLI does not publish usage data.`)}`,
-        ].join('\n');
+        return { agent: agentId, label, status: 'unsupported' };
     }
     const versions = listInstalledVersions(agentId);
     const version = getGlobalDefault(agentId) || versions[0];
     if (!version) {
-        return [`${heading}`, `  ${chalk.dim('No version installed.')}`].join('\n');
+        return { agent: agentId, label, status: 'no-version' };
     }
     const home = getVersionHomePath(agentId, version);
     const info = await getAccountInfo(agentId, home);
     if (!info.usageKey && !info.accountKey) {
-        return [`${heading}`, `  ${chalk.dim('Not signed in.')}`].join('\n');
-    }
-    const usage = await getUsageInfoForIdentity({
-        agentId,
-        home,
-        info,
-        cliVersion: null,
-    });
-    const lines = [heading];
-    if (info.email)
-        lines.push(`  ${chalk.dim(info.email)}`);
-    const section = formatUsageSection(usage);
-    if (section.length === 0) {
-        lines.push(`  ${chalk.dim('No usage data available right now.')}`);
+        return { agent: agentId, label, status: 'not-signed-in' };
     }
-    else {
-        lines.push(...section);
+    const usage = await getUsageInfoForIdentity({ agentId, home, info, cliVersion: null });
+    return { agent: agentId, label, status: 'ok', email: info.email ?? undefined, usage };
+}
+/** Render one usage record as the human table section. */
+export function formatAgentUsage(rec) {
+    const cfg = AGENTS[rec.agent];
+    // Colorize the heading here (not in the record) so the plain `label` stays
+    // clean for --json while the text table keeps its per-agent color.
+    const heading = agentLabel(rec.agent);
+    switch (rec.status) {
+        case 'unsupported':
+            return [heading, `  ${chalk.dim(`${cfg.name} CLI does not publish usage data.`)}`].join('\n');
+        case 'no-version':
+            return [heading, `  ${chalk.dim('No version installed.')}`].join('\n');
+        case 'not-signed-in':
+            return [heading, `  ${chalk.dim('Not signed in.')}`].join('\n');
+        case 'ok': {
+            const lines = [heading];
+            if (rec.email)
+                lines.push(`  ${chalk.dim(rec.email)}`);
+            const section = formatUsageSection(rec.usage);
+            if (section.length === 0) {
+                lines.push(`  ${chalk.dim('No usage data available right now.')}`);
+            }
+            else {
+                lines.push(...section);
+            }
+            return lines.join('\n');
+        }
     }
-    return lines.join('\n');
 }