@phnx-labs/agents-cli 0.1.0 → 1.14.1

package/dist/commands/models.js

@@ -1,7 +1,14 @@
+/**
+ * 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', 'gemini', 'opencode', 'cursor', 'openclaw'];
 /**
@@ -10,6 +17,7 @@ const MODEL_CAPABLE_AGENTS = ['claude', 'codex', 'gemini', 'opencode', 'cursor',
  * 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)
@@ -24,6 +32,7 @@ function fallbackPathVersion(agent) {
     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 })
@@ -53,6 +62,7 @@ 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 = [];
@@ -87,7 +97,8 @@ async function resolveTargets(agentSpec) {
             isDefault: v === getGlobalDefault(agent),
         }));
     }
-    let 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);
     }
@@ -97,6 +108,7 @@ async function resolveTargets(agentSpec) {
     }
     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}`;
@@ -104,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);
@@ -152,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

@@ -1,3 +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;
-//# sourceMappingURL=profiles.d.ts.map

package/dist/commands/profiles.js

@@ -1,9 +1,18 @@
+/**
+ * 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/profiles-keychain.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).');
@@ -11,6 +20,7 @@ async function promptForSecret(message) {
     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);
@@ -28,6 +38,7 @@ function readStdinSync() {
     }
     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)) {
@@ -47,12 +58,14 @@ async function ensureProviderToken(provider, signupUrl, fromStdin) {
     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')
@@ -92,6 +105,37 @@ Custom endpoints — drop a YAML file at ~/.agents/profiles/<name>.yml:
     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')
@@ -230,13 +274,18 @@ Profiles store no secrets — safe to 'agents push' to a shared repo.
         .command('logout <provider>')
         .description('Remove a stored provider key from keychain')
         .action((provider) => {
-        const item = keychainItemName(provider);
-        const existed = deleteKeychainToken(item);
-        if (!existed) {
-            console.error(chalk.yellow(`No keychain item '${item}' to remove.`));
+        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);
         }
-        console.log(chalk.green(`Removed keychain item: ${item}`));
     });
 }
-//# sourceMappingURL=profiles.js.map

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;

package/dist/commands/prune.js

@@ -0,0 +1,191 @@
+import chalk from 'chalk';
+import { confirm } from '@inquirer/prompts';
+import { diffVersionCommands, iterCommandsCapableVersions, removeCommandFromVersion, } from '../lib/commands.js';
+import { diffVersionSkills, iterSkillsCapableVersions, removeSkillFromVersion, } from '../lib/skills.js';
+import { diffVersionHooks, iterHooksCapableVersions, removeHookFromVersion, } from '../lib/hooks.js';
+import { getGlobalDefault } from '../lib/versions.js';
+import { resolveAgentName, formatAgentError } from '../lib/agents.js';
+import { pruneDuplicates } from './view.js';
+import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
+const RESOURCE_TYPES = ['commands', 'skills', 'hooks'];
+const ALL_TYPES = [...RESOURCE_TYPES, 'versions'];
+function scopePairs(pairs, all) {
+    if (all)
+        return pairs;
+    return pairs.filter((p) => p.version === getGlobalDefault(p.agent));
+}
+function collectOrphans(types, all) {
+    const groups = [];
+    if (types.includes('commands')) {
+        for (const { agent, version } of scopePairs(iterCommandsCapableVersions(), all)) {
+            const diff = diffVersionCommands(agent, version);
+            if (diff.orphans.length > 0) {
+                groups.push({ type: 'commands', agent, version, orphans: diff.orphans });
+            }
+        }
+    }
+    if (types.includes('skills')) {
+        for (const { agent, version } of scopePairs(iterSkillsCapableVersions(), all)) {
+            const diff = diffVersionSkills(agent, version);
+            if (diff.orphans.length > 0) {
+                groups.push({ type: 'skills', agent, version, orphans: diff.orphans });
+            }
+        }
+    }
+    if (types.includes('hooks')) {
+        for (const { agent, version } of scopePairs(iterHooksCapableVersions(), all)) {
+            const diff = diffVersionHooks(agent, version);
+            if (diff.orphans.length > 0) {
+                groups.push({ type: 'hooks', agent, version, orphans: diff.orphans });
+            }
+        }
+    }
+    return groups;
+}
+function removeOne(group, name) {
+    switch (group.type) {
+        case 'commands':
+            return removeCommandFromVersion(group.agent, group.version, name);
+        case 'skills':
+            return removeSkillFromVersion(group.agent, group.version, name);
+        case 'hooks':
+            return removeHookFromVersion(group.agent, group.version, name);
+    }
+}
+function parseTarget(arg) {
+    if (!arg) {
+        return { resourceTypes: RESOURCE_TYPES, includeVersions: true };
+    }
+    if (RESOURCE_TYPES.includes(arg)) {
+        return { resourceTypes: [arg], includeVersions: false };
+    }
+    if (arg === 'versions') {
+        return { resourceTypes: [], includeVersions: true };
+    }
+    // Try treating as an agent name — shortcut for `prune versions <agent>`.
+    const agentId = resolveAgentName(arg);
+    if (agentId) {
+        return { resourceTypes: [], includeVersions: true, versionAgent: agentId };
+    }
+    console.log(chalk.red(`Unknown prune target: ${arg}`));
+    console.log(chalk.gray(`Available types: ${ALL_TYPES.join(', ')}`));
+    console.log(chalk.gray(formatAgentError(arg)));
+    process.exit(1);
+}
+async function runOrphanPrune(resourceTypes, options) {
+    const groups = collectOrphans(resourceTypes, options.all === true);
+    if (groups.length === 0) {
+        console.log(chalk.green('No orphans.'));
+        return;
+    }
+    const total = groups.reduce((n, g) => n + g.orphans.length, 0);
+    console.log(chalk.bold('Orphans (in version home, not in any source)\n'));
+    for (const g of groups) {
+        const label = `${g.type} · ${g.agent}@${g.version}`;
+        console.log(`  ${chalk.cyan(label)}  ${g.orphans.join(', ')}`);
+    }
+    console.log();
+    if (options.dryRun) {
+        console.log(chalk.gray(`${total} orphan(s). Run without --dry-run to delete.`));
+        return;
+    }
+    if (!options.yes) {
+        if (!isInteractiveTerminal()) {
+            console.log(chalk.yellow('Non-interactive shell: pass -y to confirm, or --dry-run to preview.'));
+            process.exit(1);
+        }
+        let ok = false;
+        try {
+            ok = await confirm({
+                message: `Delete ${total} orphan${total === 1 ? '' : 's'}?`,
+                default: false,
+            });
+        }
+        catch (err) {
+            if (isPromptCancelled(err)) {
+                console.log(chalk.gray('Cancelled'));
+                return;
+            }
+            throw err;
+        }
+        if (!ok) {
+            console.log(chalk.gray('Cancelled'));
+            return;
+        }
+    }
+    let removed = 0;
+    let failures = 0;
+    for (const g of groups) {
+        for (const name of g.orphans) {
+            const r = removeOne(g, name);
+            if (r.success) {
+                removed++;
+            }
+            else {
+                failures++;
+                console.log(chalk.red(`  ! ${g.type} ${g.agent}@${g.version} ${name}: ${r.error}`));
+            }
+        }
+    }
+    const summary = `Pruned ${removed} orphan${removed === 1 ? '' : 's'}`;
+    console.log(chalk.green(summary) + (failures > 0 ? chalk.red(`, ${failures} failed`) : '') + '.');
+}
+export function registerPruneCommand(program) {
+    program
+        .command('prune [target]')
+        .description('Remove orphan resources (commands/skills/hooks) and/or older duplicate version installs')
+        .option('--all', 'For orphan cleanup: sweep every installed version (default: current default version per agent)')
+        .option('--dry-run', 'Show what would be removed without deleting')
+        .option('-y, --yes', 'Skip confirmation prompt')
+        .addHelpText('after', `
+Targets:
+  (none)     Orphans across commands, skills, hooks + duplicate versions
+  commands   Orphan command files only
+  skills     Orphan skill directories only
+  hooks      Orphan hook scripts only
+  versions   Older duplicate version installs only
+  <agent>    Older duplicate versions for one agent (e.g. 'claude')
+
+Examples:
+  # Full sweep: orphan resources + duplicate versions for current defaults
+  agents prune
+
+  # Just orphan skills
+  agents prune skills
+
+  # Just version dedup
+  agents prune versions
+
+  # Just version dedup for one agent
+  agents prune claude
+
+  # Sweep every installed version's orphans, not only the defaults
+  agents prune --all
+
+  # Preview without deleting
+  agents prune --dry-run
+
+What's an orphan?
+  A command, skill, or hook present inside a version home but missing from every
+  configured source (project .agents/, central ~/.agents/, and any enabled extra
+  repos). Usually leftovers from a resource that was deleted or moved but never
+  reconciled into the version install.
+
+What this does NOT do:
+  This is destructive cleanup only. Adds and updates flow through the auto-sync
+  that runs when you launch the agent — there is no manual sync verb.
+`)
+        .action(async (target, options) => {
+        const parsed = parseTarget(target);
+        if (parsed.resourceTypes.length > 0) {
+            await runOrphanPrune(parsed.resourceTypes, options);
+            if (parsed.includeVersions)
+                console.log();
+        }
+        if (parsed.includeVersions) {
+            const versionLabel = parsed.versionAgent ? ` for ${parsed.versionAgent}` : '';
+            console.log(chalk.bold(`Duplicate versions${versionLabel}`));
+            await pruneDuplicates(parsed.versionAgent, options.yes === true, options.dryRun === true);
+        }
+    });
+}

package/dist/commands/pty.d.ts

@@ -16,5 +16,5 @@
  *   agents pty server [start|stop|status]
  */
 import type { Command } from 'commander';
+/** Register the `agents pty` command tree. */
 export declare function registerPtyCommands(program: Command): void;
-//# sourceMappingURL=pty.d.ts.map

package/dist/commands/pty.js

@@ -19,6 +19,7 @@ import chalk from 'chalk';
 import { ptyRequest, unescapeInput } from '../lib/pty-client.js';
 import { isPtyServerRunning, runPtyServer, getPtyPidPath, getPtyLogPath } from '../lib/pty-server.js';
 import * as fs from 'fs';
+/** Register the `agents pty` command tree. */
 export function registerPtyCommands(program) {
     const pty = program
         .command('pty')
@@ -376,6 +377,7 @@ Example:
         await runPtyServer();
     });
 }
+/** Format a millisecond duration as a compact human-readable string (e.g. "5m", "2h 30m"). */
 function formatAge(ms) {
     const secs = Math.floor(ms / 1000);
     if (secs < 60)
@@ -386,4 +388,3 @@ function formatAge(ms) {
     const hours = Math.floor(mins / 60);
     return `${hours}h ${mins % 60}m`;
 }
-//# sourceMappingURL=pty.js.map

package/dist/commands/pull.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Config pull command.
+ *
+ * Registers the `agents pull` command which clones or updates the
+ * system ~/.agents-system/ git repo and syncs CLI versions, MCP servers,
+ * resources, and hooks to installed agent versions.
+ */
 import type { Command } from 'commander';
+/** Register the `agents pull` command. */
 export declare function registerPullCommand(program: Command): void;
-//# sourceMappingURL=pull.d.ts.map