@phnx-labs/agents-cli 1.12.0 → 1.14.2

package/dist/commands/models.js

@@ -1,8 +1,38 @@
+/**
+ * Model catalog inspection command.
+ *
+ * Registers the hidden `agents models` command for listing models
+ * supported by installed agent versions. Extracts model catalogs from
+ * each agent's CLI bundle and displays IDs, aliases, and metadata.
+ */
 import chalk from 'chalk';
+import * as fs from 'fs';
 import { resolveAgentName, formatAgentError, agentLabel, } from '../lib/agents.js';
-import { listInstalledVersions, getGlobalDefault, resolveVersion } from '../lib/versions.js';
+import { listInstalledVersions, getGlobalDefault, resolveVersion, resolveVersionAlias } from '../lib/versions.js';
 import { getModelCatalog, locateModelSource } from '../lib/models.js';
-const MODEL_CAPABLE_AGENTS = ['claude', 'codex'];
+const MODEL_CAPABLE_AGENTS = ['claude', 'codex', 'gemini', 'opencode', 'cursor', 'openclaw'];
+/**
+ * Agents that don't necessarily install under ~/.agents/versions (cursor ships
+ * via a curl script). For these, fall back to the PATH binary and synthesize
+ * a version label from the install path so cache keys stay stable.
+ */
+const PATH_ONLY_AGENTS = new Set(['cursor']);
+/** Derive a version label from the PATH-installed binary location for agents without managed versions. */
+function fallbackPathVersion(agent) {
+    const src = locateModelSource(agent, 'unresolved');
+    if (!src)
+        return null;
+    let real = src.path;
+    try {
+        real = fs.realpathSync(src.path);
+    }
+    catch {
+        /* keep symlink path */
+    }
+    const m = real.match(/\/versions\/([^/]+)\//);
+    return m ? m[1] : 'installed';
+}
+/** Register the hidden `agents models` command. */
 export function registerModelsCommand(program) {
     program
         .command('models [agentSpec]', { hidden: true })
@@ -32,11 +62,15 @@ export function registerModelsCommand(program) {
         }
     });
 }
+/** Resolve the agent spec into one or more (agent, version) pairs to inspect. */
 async function resolveTargets(agentSpec) {
     if (!agentSpec) {
         const targets = [];
         for (const agent of MODEL_CAPABLE_AGENTS) {
-            const version = getGlobalDefault(agent) || (listInstalledVersions(agent)[0] ?? null);
+            let version = getGlobalDefault(agent) || (listInstalledVersions(agent)[0] ?? null);
+            if (!version && PATH_ONLY_AGENTS.has(agent)) {
+                version = fallbackPathVersion(agent);
+            }
             if (version)
                 targets.push({ agent, version, isDefault: true });
         }
@@ -63,13 +97,18 @@ async function resolveTargets(agentSpec) {
             isDefault: v === getGlobalDefault(agent),
         }));
     }
-    const version = versionSpec || resolveVersion(agent, process.cwd()) || getGlobalDefault(agent);
+    const aliasedVersion = resolveVersionAlias(agent, versionSpec);
+    let version = aliasedVersion || resolveVersion(agent, process.cwd()) || getGlobalDefault(agent);
+    if (!version && PATH_ONLY_AGENTS.has(agent)) {
+        version = fallbackPathVersion(agent);
+    }
     if (!version) {
         console.error(chalk.red(`No version of ${agent} is installed. Try \`agents add ${agent}@latest\`.`));
         return [];
     }
     return [{ agent, version, isDefault: version === getGlobalDefault(agent) }];
 }
+/** Print the model catalog for a single agent version with optional cloud/reasoning details. */
 function printCatalog(agent, version, isDefault, options) {
     const tag = isDefault ? chalk.gray(' (default)') : '';
     const header = `${agentLabel(agent)} ${chalk.bold(version)}${tag}`;
@@ -77,7 +116,7 @@ function printCatalog(agent, version, isDefault, options) {
     const src = locateModelSource(agent, version);
     if (!src) {
         console.log(chalk.yellow(`  Could not locate model source for ${agent}@${version}.`));
-        console.log(chalk.gray(`  Expected the agent's CLI bundle or native binary under ~/.agents/versions/${agent}/${version}/.`));
+        console.log(chalk.gray(`  Expected the agent's CLI bundle or native binary under ~/.agents-system/versions/${agent}/${version}/.`));
         return;
     }
     const catalog = getModelCatalog(agent, version);
@@ -125,7 +164,7 @@ function printCatalog(agent, version, isDefault, options) {
         }
     }
 }
+/** Abbreviate a path by replacing the home directory with ~. */
 function shortPath(p) {
     return p.replace(process.env.HOME || '~', '~');
 }
-//# sourceMappingURL=models.js.map

package/dist/commands/packages.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Package registry and installation commands.
+ *
+ * Registers `agents registry`, `agents search`, and `agents install`
+ * for discovering and installing MCP servers, skills, commands, and
+ * hooks from configured registries or GitHub sources.
+ */
 import type { Command } from 'commander';
+/** Register the `agents registry`, `agents search`, and `agents install` commands. */
 export declare function registerPackagesCommands(program: Command): void;
-//# sourceMappingURL=packages.d.ts.map

package/dist/commands/packages.js

@@ -1,3 +1,10 @@
+/**
+ * Package registry and installation commands.
+ *
+ * Registers `agents registry`, `agents search`, and `agents install`
+ * for discovering and installing MCP servers, skills, commands, and
+ * hooks from configured registries or GitHub sources.
+ */
 import chalk from 'chalk';
 import ora from 'ora';
 import { AGENTS, ALL_AGENT_IDS, MCP_CAPABLE_AGENTS, getAllCliStates, registerMcpToTargets, agentLabel, } from '../lib/agents.js';
@@ -10,9 +17,11 @@ import { discoverHooksFromRepo, installHooks, installHooksCentrally, } from '../
 import { listInstalledVersions, resolveInstalledAgentTargets, resolveConfiguredAgentTargets, syncResourcesToVersion, } from '../lib/versions.js';
 import { isInteractiveTerminal, isPromptCancelled, requireDestructiveArg, requireInteractiveSelection, } from './utils.js';
 import { itemPicker } from '../lib/picker.js';
-// Picker fallback for `registry enable/config [name]`. Returns the picked
-// name, or null if the user cancels. In non-TTY shells, hard-fails with a
-// clear reminder of the positional form.
+/**
+ * Picker fallback for `registry enable/config [name]`.
+ * Returns the picked name, or null if the user cancels. In non-TTY shells,
+ * hard-fails with a clear reminder of the positional form.
+ */
 async function pickRegistryName(type, verb, pred) {
     const registries = getRegistries(type);
     const entries = Object.entries(registries).filter(([, cfg]) => (pred ? pred(cfg) : true));
@@ -55,6 +64,7 @@ async function pickRegistryName(type, verb, pred) {
         throw err;
     }
 }
+/** Register the `agents registry`, `agents search`, and `agents install` commands. */
 export function registerPackagesCommands(program) {
     // ==========================================================================
     // REGISTRY COMMANDS
@@ -265,9 +275,6 @@ When to use:
             spinner.stop();
             if (results.length === 0) {
                 console.log(chalk.yellow('\nNo packages found.'));
-                if (!options.type) {
-                    console.log(chalk.gray('\nTip: skill registries not yet available. Use gh:user/repo for skills.'));
-                }
                 return;
             }
             console.log(chalk.bold(`Found ${results.length} packages`));
@@ -538,4 +545,3 @@ When to use:
         }
     });
 }
-//# sourceMappingURL=packages.js.map

package/dist/commands/permissions.d.ts

@@ -1,3 +1,11 @@
+/**
+ * Permission management commands for controlling agent access boundaries.
+ *
+ * Implements `agents permissions` -- list, add, remove, and view permission
+ * sets (allow/deny rules for bash, tools, and filesystem). Supports importing
+ * from agent config files, GitHub repos, and YAML, with merge/replace
+ * semantics and multi-version targeting.
+ */
 import type { Command } from 'commander';
+/** Register the `agents permissions` command tree (list, add, remove, view). */
 export declare function registerPermissionsCommands(program: Command): void;
-//# sourceMappingURL=permissions.d.ts.map

package/dist/commands/permissions.js

@@ -7,9 +7,10 @@ import { confirm, checkbox } from '@inquirer/prompts';
 import { AGENTS, resolveAgentName, formatAgentError, agentLabel, } from '../lib/agents.js';
 import { cloneRepo } from '../lib/git.js';
 import { PERMISSIONS_CAPABLE_AGENTS, listInstalledPermissions, discoverPermissionsFromRepo, installPermissionSet, removePermissionSet, applyPermissionsToVersion, readAgentPermissions, exportPermissionsFromPath, getDefaultPermissionSet, computePermissionsDiff, mergePermissionSets, saveDefaultPermissionSet, } from '../lib/permissions.js';
-import { listInstalledVersions, getGlobalDefault, getVersionHomePath, promptAgentVersionSelection, resolveAgentVersionTargets, } from '../lib/versions.js';
+import { listInstalledVersions, getGlobalDefault, getVersionHomePath, promptAgentVersionSelection, resolveAgentVersionTargets, resolveVersionAlias, } from '../lib/versions.js';
 import { recordVersionResources } from '../lib/state.js';
 import { isPromptCancelled, isInteractiveTerminal, parseCommaSeparatedList, printWithPager, requireInteractiveSelection, } from './utils.js';
+/** Register the `agents permissions` command tree (list, add, remove, view). */
 export function registerPermissionsCommands(program) {
     const permissionsCmd = program
         .command('permissions')
@@ -106,12 +107,12 @@ When to use:
             // Parse agent@version syntax
             const parts = agentArg.split('@');
             const agentName = parts[0];
-            const requestedVersion = parts[1] || null;
             const agentId = resolveAgentName(agentName);
             if (!agentId) {
                 console.log(chalk.red(formatAgentError(agentName, PERMISSIONS_CAPABLE_AGENTS)));
                 process.exit(1);
             }
+            const requestedVersion = resolveVersionAlias(agentId, parts[1]) ?? null;
             if (!PERMISSIONS_CAPABLE_AGENTS.includes(agentId)) {
                 console.log(chalk.yellow(`${AGENTS[agentId].name} does not support fine-grained permissions`));
                 return;
@@ -720,4 +721,3 @@ Examples:
     // Note: This needs to be registered at the program level, not as a subcommand
     // The actual deprecation message is shown in index.ts
 }
-//# sourceMappingURL=permissions.js.map

package/dist/commands/plugins.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Plugin management commands.
+ *
+ * Registers the `agents plugins` command tree for listing, viewing,
+ * syncing, and removing plugin bundles (skills + hooks + permissions)
+ * stored in ~/.agents/plugins/.
+ */
 import type { Command } from 'commander';
+/** Register the `agents plugins` command tree. */
 export declare function registerPluginsCommands(program: Command): void;
-//# sourceMappingURL=plugins.d.ts.map

package/dist/commands/plugins.js

@@ -1,3 +1,10 @@
+/**
+ * Plugin management commands.
+ *
+ * Registers the `agents plugins` command tree for listing, viewing,
+ * syncing, and removing plugin bundles (skills + hooks + permissions)
+ * stored in ~/.agents/plugins/.
+ */
 import * as fs from 'fs';
 import * as path from 'path';
 import chalk from 'chalk';
@@ -9,6 +16,8 @@ import { isPromptCancelled, isInteractiveTerminal, requireDestructiveArg, requir
 import { itemPicker } from '../lib/picker.js';
 import { showResourceList, buildTargetsSection, } from './resource-view.js';
 import { getPluginsDir } from '../lib/state.js';
+import { safeJoin } from '../lib/paths.js';
+/** Replace the home directory prefix with ~ for display. */
 function formatPath(p) {
     const home = process.env.HOME || '';
     if (home && p.startsWith(home)) {
@@ -16,6 +25,7 @@ function formatPath(p) {
     }
     return p;
 }
+/** Register the `agents plugins` command tree. */
 export function registerPluginsCommands(program) {
     const pluginsCmd = program
         .command('plugins')
@@ -257,7 +267,7 @@ Examples:
         }
         const name = nameArg;
         const pluginsDir = path.join(process.env.HOME || '', '.agents', 'plugins');
-        const pluginRoot = path.join(pluginsDir, name);
+        const pluginRoot = safeJoin(pluginsDir, name);
         // Use discovered plugin when present; fall back to name+root if source is already gone
         const plugin = getPlugin(name);
         const resolvedRoot = plugin?.root || pluginRoot;
@@ -295,6 +305,7 @@ Examples:
         }
     });
 }
+/** Convert discovered plugins into rows suitable for the resource list view. */
 function buildPluginRows(plugins) {
     const rows = [];
     // Cache version lists per agent once.
@@ -337,6 +348,7 @@ function buildPluginRows(plugins) {
     });
     return rows;
 }
+/** Build the multi-line detail pane shown when a plugin is selected in the picker. */
 function formatPluginDetail(plugin, targets) {
     const lines = [];
     const title = plugin.manifest.version
@@ -379,4 +391,3 @@ function formatPluginDetail(plugin, targets) {
     }
     return lines.join('\n');
 }
-//# sourceMappingURL=plugins.js.map

package/dist/commands/profiles.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Profile management commands.
+ *
+ * Registers the `agents profiles` command tree for creating, viewing,
+ * and removing named bundles of (host CLI, endpoint, model, keychain auth).
+ * Profiles let users run non-default providers (Kimi, DeepSeek, Qwen, etc.)
+ * through a standard agent CLI with no local proxy.
+ */
+import type { Command } from 'commander';
+/** Register the `agents profiles` command tree. */
+export declare function registerProfilesCommands(program: Command): void;

package/dist/commands/profiles.js

@@ -0,0 +1,291 @@
+/**
+ * Profile management commands.
+ *
+ * Registers the `agents profiles` command tree for creating, viewing,
+ * and removing named bundles of (host CLI, endpoint, model, keychain auth).
+ * Profiles let users run non-default providers (Kimi, DeepSeek, Qwen, etc.)
+ * through a standard agent CLI with no local proxy.
+ */
+import chalk from 'chalk';
+import * as fs from 'fs';
+import { listProfiles, readProfile, writeProfile, deleteProfile, profileExists, profileFromPreset, getPresetForProfile, } from '../lib/profiles.js';
+import { getPreset, listPresets } from '../lib/profiles-presets.js';
+import { hasKeychainToken, keychainItemName, setKeychainToken, deleteKeychainToken, } from '../lib/secrets/profiles.js';
+import { isInteractiveTerminal } from './utils.js';
+/** Prompt the user for a secret value with masked input. Requires an interactive TTY. */
+async function promptForSecret(message) {
+    if (!isInteractiveTerminal()) {
+        throw new Error('A secret is required but the shell is not interactive. Pipe the key via stdin (--key-stdin).');
+    }
+    const { password } = await import('@inquirer/prompts');
+    return await password({ message, mask: true });
+}
+/** Read all available data from stdin synchronously, trimmed. */
+function readStdinSync() {
+    const chunks = [];
+    const buf = Buffer.alloc(65536);
+    while (true) {
+        let bytesRead;
+        try {
+            bytesRead = fs.readSync(0, buf, 0, buf.length, null);
+        }
+        catch {
+            break;
+        }
+        if (bytesRead === 0)
+            break;
+        chunks.push(Buffer.from(buf.subarray(0, bytesRead)));
+    }
+    return Buffer.concat(chunks).toString('utf-8').trim();
+}
+/** Ensure a provider API key exists in keychain, prompting or reading stdin if missing. */
+async function ensureProviderToken(provider, signupUrl, fromStdin) {
+    const item = keychainItemName(provider);
+    if (hasKeychainToken(item)) {
+        return;
+    }
+    let token;
+    if (fromStdin) {
+        token = readStdinSync();
+        if (!token) {
+            throw new Error('No key received on stdin.');
+        }
+    }
+    else {
+        const hint = signupUrl ? ` (get one at ${signupUrl})` : '';
+        token = await promptForSecret(`Enter API key for ${provider}${hint}`);
+    }
+    setKeychainToken(item, token);
+    console.log(chalk.green(`Stored in keychain: ${item}`));
+}
+/** Format a single profile as a table row for the `profiles list` output. */
+function renderProfileRow(p) {
+    const host = p.host.version ? `${p.host.agent}@${p.host.version}` : p.host.agent;
+    const model = p.env.ANTHROPIC_MODEL || p.env.OPENAI_MODEL || p.env.GEMINI_MODEL || '-';
+    const provider = p.provider || (p.auth?.keychainItem?.split('.')[1]) || '-';
+    return `${chalk.cyan(p.name.padEnd(16))} ${host.padEnd(14)} ${provider.padEnd(12)} ${chalk.gray(model)}`;
+}
+/** Register the `agents profiles` command tree. */
+export function registerProfilesCommands(program) {
+    const cmd = program
+        .command('profiles')
+        .description('Named bundles of (host CLI, endpoint, model, auth) — run Kimi/DeepSeek/Qwen/etc through Claude Code without a proxy.')
+        .addHelpText('after', `
+A profile pins a host CLI (claude, codex, gemini, ...) to a non-default endpoint
+and model, with a keychain-backed API key. Running 'agents run <profile>' spawns
+the host CLI with the right env vars — no plaintext tokens, no local proxy.
+
+Built-in presets (via OpenRouter, one shared key):
+  kimi       Kimi K2.5           (top HumanEval, reasoning — interactive only)
+  kimi-chat  Kimi K2 0905        (non-reasoning, print-safe)
+  minimax    MiniMax M2.5        (top SWE-bench, reasoning)
+  glm        GLM 5               (top Chatbot Arena among open-weight, reasoning)
+  qwen       Qwen3 Coder Next    (latest coding Qwen, print-safe)
+  deepseek   DeepSeek Chat V3    (latest non-reasoning chat, print-safe)
+
+Run 'agents profiles presets' for the full list with pricing and context sizes.
+
+Typical flow:
+  agents profiles add kimi             # prompts for OpenRouter key, stored in Keychain
+  agents run kimi "refactor this"      # Claude Code UI, Kimi model responses
+  agents profiles add deepseek         # reuses OpenRouter key, no re-prompt
+
+Managing keys:
+  agents profiles login openrouter     # rotate the key (shared across openrouter profiles)
+  agents profiles logout openrouter    # remove from Keychain
+
+Custom endpoints — drop a YAML file at ~/.agents/profiles/<name>.yml:
+  name: local-llama
+  host: { agent: claude }
+  env:
+    ANTHROPIC_BASE_URL: http://localhost:11434
+    ANTHROPIC_MODEL: llama-3.3-70b
+  auth:
+    envVar: ANTHROPIC_AUTH_TOKEN
+    keychainItem: agents-cli.ollama.token
+
+Profiles store no secrets — safe to 'agents push' to a shared repo.
+
+Examples:
+  # One-time: store the OpenRouter key (every preset reuses it)
+  agents profiles login openrouter
+
+  # Add Kimi (top HumanEval) and run it through the Claude Code UI
+  agents profiles add kimi
+  agents run kimi "refactor api/handlers/checkout.py to use async sqlalchemy"
+
+  # Add MiniMax for SWE-bench style fixes; reuses the same OpenRouter key
+  agents profiles add minimax
+  agents run minimax "investigate RUSH-2317 and patch the off-by-one in pagination"
+
+  # Add DeepSeek for cheap, fast non-reasoning work
+  agents profiles add deepseek
+  agents run deepseek "rename UserSession -> AuthSession across the codebase"
+
+  # See every profile and which provider it talks to
+  agents profiles list
+
+  # Browse the catalog (pricing, context sizes, reasoning vs print-safe)
+  agents profiles presets
+
+  # Rotate the OpenRouter key (every openrouter profile picks it up)
+  agents profiles login openrouter
+
+  # Drop a profile, keep the key in Keychain for the next one
+  agents profiles remove kimi
+
+  # Fully remove the OpenRouter key from Keychain
+  agents profiles logout openrouter
+`);
+    cmd
+        .command('list')
+        .alias('ls')
+        .description('List configured profiles')
+        .action(() => {
+        const profiles = listProfiles();
+        if (profiles.length === 0) {
+            console.log(chalk.gray('No profiles configured.'));
+            console.log(chalk.gray('Try: agents profiles add kimi'));
+            console.log(chalk.gray('     agents profiles presets'));
+            return;
+        }
+        console.log(chalk.bold(`${'NAME'.padEnd(16)} ${'HOST'.padEnd(14)} ${'PROVIDER'.padEnd(12)} MODEL`));
+        for (const p of profiles) {
+            console.log(renderProfileRow(p));
+        }
+    });
+    cmd
+        .command('presets')
+        .description('List built-in presets (OpenRouter + direct providers)')
+        .action(() => {
+        const presets = listPresets();
+        console.log(chalk.bold(`${'NAME'.padEnd(14)} ${'PROVIDER'.padEnd(12)} DESCRIPTION`));
+        for (const p of presets) {
+            console.log(`${chalk.cyan(p.name.padEnd(14))} ${p.provider.padEnd(12)} ${chalk.gray(p.description)}`);
+        }
+    });
+    cmd
+        .command('view <name>')
+        .alias('show')
+        .description('Show a profile (env, host, auth source, preset link)')
+        .action((name) => {
+        try {
+            const p = readProfile(name);
+            console.log(chalk.bold(p.name));
+            if (p.description)
+                console.log(chalk.gray(p.description));
+            console.log();
+            console.log(chalk.bold('Host:'), p.host.agent + (p.host.version ? `@${p.host.version}` : ''));
+            if (p.provider)
+                console.log(chalk.bold('Provider:'), p.provider);
+            if (p.preset)
+                console.log(chalk.bold('Preset:'), p.preset);
+            console.log();
+            console.log(chalk.bold('Env:'));
+            for (const [k, v] of Object.entries(p.env)) {
+                console.log(`  ${k}=${v}`);
+            }
+            if (p.auth) {
+                console.log();
+                console.log(chalk.bold('Auth:'));
+                const tokenStatus = hasKeychainToken(p.auth.keychainItem) ? chalk.green('stored') : chalk.red('missing');
+                console.log(`  ${p.auth.envVar} <- keychain:${p.auth.keychainItem} (${tokenStatus})`);
+            }
+            const preset = getPresetForProfile(p);
+            if (preset?.signupUrl) {
+                console.log();
+                console.log(chalk.gray(`Sign up: ${preset.signupUrl}`));
+            }
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+    cmd
+        .command('add <name>')
+        .description('Add a profile. If <name> matches a built-in preset, the preset is applied. Prompts for API key (once per provider).')
+        .option('--preset <preset>', 'Use a named preset (defaults to <name> if a preset by that name exists)')
+        .option('--version <version>', 'Pin the host CLI version (e.g., 2.1.113)')
+        .option('--key-stdin', 'Read API key from stdin instead of prompting (for scripts/CI)')
+        .option('--force', 'Overwrite an existing profile with the same name')
+        .action(async (name, opts) => {
+        try {
+            if (profileExists(name) && !opts.force) {
+                console.error(chalk.red(`Profile '${name}' already exists. Use --force to overwrite.`));
+                process.exit(1);
+            }
+            const presetName = opts.preset || name;
+            const preset = getPreset(presetName);
+            if (!preset) {
+                console.error(chalk.red(`No preset '${presetName}'.`));
+                console.error(chalk.gray('Available presets: ' + listPresets().map((p) => p.name).join(', ')));
+                console.error(chalk.gray('Or pass --preset <name> to pick explicitly.'));
+                process.exit(1);
+            }
+            await ensureProviderToken(preset.provider, preset.signupUrl, opts.keyStdin);
+            const profile = profileFromPreset(name, preset, opts.version);
+            writeProfile(profile);
+            console.log(chalk.green(`Profile '${name}' added.`));
+            console.log(chalk.gray(`Try: agents run ${name} "hello"`));
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+    cmd
+        .command('remove <name>')
+        .alias('rm')
+        .description('Delete a profile (keychain token is kept — use `profiles logout <provider>` to remove)')
+        .action((name) => {
+        const existed = deleteProfile(name);
+        if (!existed) {
+            console.error(chalk.red(`Profile '${name}' not found.`));
+            process.exit(1);
+        }
+        console.log(chalk.green(`Profile '${name}' removed.`));
+    });
+    cmd
+        .command('login <provider>')
+        .description('Store or rotate the API key for a provider (e.g., openrouter). Shared across profiles using that provider.')
+        .option('--key-stdin', 'Read API key from stdin')
+        .action(async (provider, opts) => {
+        try {
+            const item = keychainItemName(provider);
+            let token;
+            if (opts.keyStdin) {
+                token = readStdinSync();
+                if (!token)
+                    throw new Error('No key received on stdin.');
+            }
+            else {
+                token = await promptForSecret(`Enter API key for ${provider}`);
+            }
+            setKeychainToken(item, token);
+            console.log(chalk.green(`Stored in keychain: ${item}`));
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+    cmd
+        .command('logout <provider>')
+        .description('Remove a stored provider key from keychain')
+        .action((provider) => {
+        try {
+            const item = keychainItemName(provider);
+            const existed = deleteKeychainToken(item);
+            if (!existed) {
+                console.error(chalk.yellow(`No keychain item '${item}' to remove.`));
+                process.exit(1);
+            }
+            console.log(chalk.green(`Removed keychain item: ${item}`));
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+}

package/dist/commands/prune.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Top-level `agents prune` — destructive cleanup across the install.
+ *
+ * Two kinds of cleanup, one verb:
+ *   - Resource orphans: command/skill/hook files inside a version home that no
+ *     longer come from any source (deleted from ~/.agents/ but never reconciled
+ *     into the version install).
+ *   - Version duplicates: older installed versions of an agent that share an
+ *     account with a newer installed version of the same agent (the older copy
+ *     is redundant; the newer one is what's signed in and active).
+ *
+ * Sync (additive: copy missing/changed files into version homes) is no longer
+ * a user-facing verb — `syncResourcesToVersion` runs at agent launch and
+ * applies adds/updates automatically. Pruning, however, is destructive, so it
+ * stays explicit.
+ *
+ * Default scope: each agent's currently-pinned default version for orphan
+ * cleanup, plus the standard cross-agent version-dedup pass. Pass `--all`
+ * to widen orphan cleanup to every installed version.
+ */
+import type { Command } from 'commander';
+export declare function registerPruneCommand(program: Command): void;