@phnx-labs/agents-cli 1.12.0 → 1.14.1

package/dist/commands/versions.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Version management commands for installing, switching, and removing agent CLIs.
+ *
+ * Implements `agents add`, `agents remove`, `agents use`, and the deprecated
+ * `agents list`. Handles npm-based installation, shim creation, config symlink
+ * switching, resource sync prompts, and project-level version pinning.
+ */
 import type { Command } from 'commander';
+/** Register `agents add`, `agents remove`, `agents use`, and `agents list` (deprecated). */
 export declare function registerVersionsCommands(program: Command): void;
-//# sourceMappingURL=versions.d.ts.map

package/dist/commands/versions.js

@@ -77,6 +77,7 @@ function warnIfShimShadowed(agent) {
     console.log(chalk.gray(`  Managed shim: ${getShimPath(agent)}`));
     console.log(chalk.gray(`  ${getPathSetupInstructions().split('\n').join('\n  ')}`));
 }
+/** Register `agents add`, `agents remove`, `agents use`, and `agents list` (deprecated). */
 export function registerVersionsCommands(program) {
     program
         .command('add <specs...>')
@@ -443,11 +444,11 @@ Important: This is the ONLY command that sets the default version. If you want a
         .action(async (agentArg, versionArg, options) => {
         try {
             const skipPrompts = options.yes || !isInteractiveTerminal();
-            // Auto-pull ~/.agents if it's a git repo with remote (silent on success)
+            // Auto-pull ~/.agents-system if it's a git repo with remote (silent on success)
             const agentsDir = getAgentsDir();
             const pullResult = await tryAutoPull(agentsDir);
             if (pullResult.pulled) {
-                console.log(chalk.gray('Synced ~/.agents from remote'));
+                console.log(chalk.gray('Synced ~/.agents-system from remote'));
             }
             // Support both "claude 2.0.65" and "claude@2.0.65" formats
             let agent;
@@ -660,6 +661,7 @@ Important: This is the ONLY command that sets the default version. If you want a
                         throw err;
                     }
                 }
+                const previousDefault = getGlobalDefault(agentId);
                 // Set global default
                 setGlobalDefault(agentId, finalVersion);
                 // Regenerate shim so it uses the latest script format
@@ -697,4 +699,3 @@ Important: This is the ONLY command that sets the default version. If you want a
         await viewAction(agentArg);
     });
 }
-//# sourceMappingURL=versions.js.map

package/dist/commands/view.d.ts

@@ -1,8 +1,53 @@
+/**
+ * View command for inspecting installed agents, versions, accounts, and resources.
+ *
+ * Implements `agents view` -- shows installed agent CLIs with version info,
+ * account emails, usage stats, and active status. When given an agent@version
+ * argument, displays a detailed breakdown of commands, skills, MCP servers,
+ * rules, hooks, and promptcuts synced to that version.
+ */
 import type { Command } from 'commander';
+import type { AgentId } from '../lib/types.js';
+/** Machine-readable entry for a single installed version. */
+export interface ViewJsonVersion {
+    version: string;
+    isDefault: boolean;
+    signedIn: boolean;
+    email: string | null;
+    plan: string | null;
+    usageStatus: 'available' | 'rate_limited' | 'out_of_credits' | null;
+    windows: Array<{
+        key: 'session' | 'week' | 'sonnet_week';
+        usedPercent: number;
+        resetsAt: string | null;
+    }>;
+    lastActive: string | null;
+    path: string;
+}
+/** Machine-readable entry for one agent's installed versions. */
+export interface ViewJsonAgent {
+    agent: AgentId;
+    versions: ViewJsonVersion[];
+}
+/**
+ * Prune older installed versions that share an email with a newer installed
+ * version. Keeps the highest semver per email, skips the global default (with
+ * a warning so the user can switch first).
+ *
+ * When filterAgentId is set, prunes that agent first, then cascades: after
+ * each agent, offers the next agent with duplicates. User answering "no"
+ * stops the chain.
+ */
+export declare function pruneDuplicates(filterAgentId: AgentId | undefined, yes: boolean, dryRun: boolean): Promise<void>;
 /**
  * Main view action handler.
  * Exported for use by deprecated aliases.
  */
-export declare function viewAction(agentArg?: string): Promise<void>;
+export declare function viewAction(agentArg?: string, options?: {
+    json?: boolean;
+    prune?: boolean;
+    yes?: boolean;
+    dryRun?: boolean;
+}): Promise<void>;
+/** Register the `agents view` command. */
 export declare function registerViewCommand(program: Command): void;
-//# sourceMappingURL=view.d.ts.map

package/dist/commands/view.js

@@ -2,16 +2,19 @@ import chalk from 'chalk';
 import ora from 'ora';
 import * as fs from 'fs';
 import * as path from 'path';
+import * as yaml from 'yaml';
 import { AGENTS, ALL_AGENT_IDS, getAllCliStates, getAccountInfo, resolveAgentName, formatAgentError, agentLabel, colorAgent, } from '../lib/agents.js';
 import { formatUsageSection, formatUsageSummary, getUsageInfoForIdentity, getUsageInfoByIdentity, getUsageLookupKey, } from '../lib/usage.js';
 import { readManifest } from '../lib/manifest.js';
-import { listInstalledVersions, getGlobalDefault, getVersionHomePath, getVersionDir, getAvailableResources, getActuallySyncedResources, getNewResources, hasNewResources, promptNewResourceSelection, syncResourcesToVersion, } from '../lib/versions.js';
-import { getShimsDir, isShimsInPath, } from '../lib/shims.js';
+import { listInstalledVersions, getGlobalDefault, getVersionHomePath, getVersionDir, resolveVersionAlias, getAvailableResources, getActuallySyncedResources, getNewResources, hasNewResources, promptNewResourceSelection, syncResourcesToVersion, removeVersion, } from '../lib/versions.js';
+import { getShimsDir, isShimsInPath, ensureVersionedAliasCurrent, removeShim, } from '../lib/shims.js';
 import { getAgentResources } from '../lib/resources.js';
-import { getAgentsDir } from '../lib/state.js';
+import { getAgentsDir, getUserAgentsDir, getPromptcutsPath } from '../lib/state.js';
 import { isGitRepo, getGitSyncStatus } from '../lib/git.js';
 import { getCentralMemoryFileName } from '../lib/memory.js';
-import { formatPath, isPromptCancelled } from './utils.js';
+import { getConfiguredRunStrategy } from '../lib/rotate.js';
+import { confirm } from '@inquirer/prompts';
+import { formatPath, isInteractiveTerminal, isPromptCancelled } from './utils.js';
 function formatLastActive(date) {
     if (!date)
         return '';
@@ -70,6 +73,25 @@ async function showInstalledVersions(filterAgentId) {
     spinner.stop();
     const agentsToShow = filterAgentId ? [filterAgentId] : ALL_AGENT_IDS;
     const showPaths = !!filterAgentId;
+    // Auto-heal stale versioned aliases. Pre-v2 aliases (e.g. pre-CLAUDE_CONFIG_DIR
+    // claude shims) silently route login through the default version's symlinked
+    // home, so `agents view` would never reflect the right account. Regenerate on
+    // sight — it's safe, idempotent, and fixes the symptom exactly where the user
+    // notices it.
+    // Yield between agents so the heal loop doesn't block the event loop as one
+    // long sync burst — per-version readFileSync+writeFileSync across 5 agents
+    // can otherwise stall spinners and stdout flushes.
+    const healedAliases = [];
+    for (const agentId of agentsToShow) {
+        await new Promise((resolve) => setImmediate(resolve));
+        for (const version of listInstalledVersions(agentId)) {
+            const status = ensureVersionedAliasCurrent(agentId, version);
+            if (status === 'updated' || status === 'created') {
+                healedAliases.push(`${agentId}@${version}`);
+            }
+        }
+    }
+    // Shim healing is silent — users don't need to know about internal repairs
     console.log(chalk.bold('Installed Agent CLIs\n'));
     // Pre-fetch account info for all versions in parallel
     const infoFetches = [];
@@ -187,8 +209,10 @@ async function showInstalledVersions(filterAgentId) {
             const agent = AGENTS[agentId];
             const versions = listInstalledVersions(agentId);
             const globalDefault = getGlobalDefault(agentId);
+            const runStrategy = getConfiguredRunStrategy(agentId);
+            const strategyLabel = chalk.gray(` (${runStrategy})`);
             const noDefaultLabel = !globalDefault ? chalk.yellow(' (no default)') : '';
-            console.log(`  ${chalk.bold(agentLabel(agentId))}${noDefaultLabel}`);
+            console.log(`  ${chalk.bold(agentLabel(agentId))}${strategyLabel}${noDefaultLabel}`);
             // Sort versions with default first, then by semver descending
             const sortedVersions = [...versions].sort((a, b) => {
                 if (a === globalDefault)
@@ -380,11 +404,12 @@ async function showAgentResources(agentId, requestedVersion) {
     }
     const home = getVersionHomePath(agentId, version);
     // Get git sync status if ~/.agents/ is a git repo
-    const hasGitRepo = isGitRepo(agentsDir);
-    const commandsSync = hasGitRepo ? await getGitSyncStatus(agentsDir, 'commands') : null;
-    const skillsSync = hasGitRepo ? await getGitSyncStatus(agentsDir, 'skills') : null;
-    const hooksSync = hasGitRepo ? await getGitSyncStatus(agentsDir, 'hooks') : null;
-    const memorySync = hasGitRepo ? await getGitSyncStatus(agentsDir, 'memory') : null;
+    const userAgentsDir = getUserAgentsDir();
+    const hasGitRepo = isGitRepo(userAgentsDir);
+    const commandsSync = hasGitRepo ? await getGitSyncStatus(userAgentsDir, 'commands') : null;
+    const skillsSync = hasGitRepo ? await getGitSyncStatus(userAgentsDir, 'skills') : null;
+    const hooksSync = hasGitRepo ? await getGitSyncStatus(userAgentsDir, 'hooks') : null;
+    const memorySync = hasGitRepo ? await getGitSyncStatus(userAgentsDir, 'rules') : null;
     // Helper to determine sync state for a resource
     const getSyncState = (resourceName, resourceType, syncStatus) => {
         if (!syncStatus)
@@ -400,9 +425,9 @@ async function showAgentResources(agentId, requestedVersion) {
             relativePath = `hooks/${resourceName}`;
         }
         else {
-            // Memory files: map agent-specific name (CLAUDE.md) back to canonical (AGENTS.md)
+            // Rules files: map agent-specific name (CLAUDE.md) back to canonical (AGENTS.md)
             const centralName = getCentralMemoryFileName(agentId);
-            relativePath = `memory/${centralName}`;
+            relativePath = `rules/${centralName}`;
         }
         const matchesPath = (f) => f === relativePath || f.startsWith(relativePath + '/');
         const isNew = syncStatus.new.some(matchesPath);
@@ -477,13 +502,35 @@ async function showAgentResources(agentId, requestedVersion) {
             let display = nameColor(r.name);
             if (r.ruleCount !== undefined)
                 display += chalk.gray(` (${r.ruleCount} rules)`);
-            if (r.scope === 'project') {
-                display += chalk.gray(' [project]');
-            }
+            // Source annotation: project overrides user, user overrides system
+            const sourceTag = r.scope === 'project' ? chalk.blue('[project]')
+                : r.scope === 'user' ? chalk.cyan('[user]')
+                    : chalk.gray('[system]');
+            display += ` ${sourceTag}`;
             const pathStr = r.path ? chalk.gray(formatPath(r.path, cwd)) : '';
             const syncStr = r.syncState ? chalk.gray(` [${r.syncState}]`) : '';
-            console.log(`    ${display.padEnd(24)} ${pathStr}${syncStr}`);
+            console.log(`    ${display.padEnd(38)} ${pathStr}${syncStr}`);
+        }
+    }
+    // Render the single ~/.agents/promptcuts.yaml (cross-agent, not per-version).
+    // Reads the file to surface the shortcut count — cheap (<1KB typical).
+    function renderPromptcuts() {
+        console.log(chalk.bold(`\nPromptcuts\n`));
+        const promptcutsPath = getPromptcutsPath();
+        if (!fs.existsSync(promptcutsPath)) {
+            console.log(`  ${chalk.gray('none')}`);
+            return;
         }
+        let count = 0;
+        try {
+            const parsed = yaml.parse(fs.readFileSync(promptcutsPath, 'utf-8'));
+            count = parsed?.shortcuts ? Object.keys(parsed.shortcuts).length : 0;
+        }
+        catch {
+            count = 0;
+        }
+        const label = `${count} shortcut${count === 1 ? '' : 's'}`;
+        console.log(`  ${chalk.green(label).padEnd(24)} ${chalk.gray(formatPath(promptcutsPath, cwd))}`);
     }
     // 1. Agent CLI info
     console.log(chalk.bold('Agent CLIs\n'));
@@ -520,18 +567,267 @@ async function showAgentResources(agentId, requestedVersion) {
     renderSection('MCP Servers', agentData.mcp);
     renderSection('Rules', agentData.memory);
     renderSection('Hooks', agentData.hooks);
+    renderPromptcuts();
     // Show legend at the end if git repo exists
     if (hasGitRepo) {
         console.log();
         console.log(chalk.gray('Legend:'), chalk.green('Tracked'), chalk.blue('Local-only'), chalk.yellow('Modified'), chalk.red('Deleted'));
     }
 }
+/**
+ * Collect structured info for one or more agents without rendering to the
+ * terminal. Used by `--json` output and any programmatic consumer (e.g. the
+ * agents-cli extension's "resume current session in best available version"
+ * command).
+ */
+async function collectAgentsJson(filterAgentId) {
+    const agentsToShow = filterAgentId ? [filterAgentId] : ALL_AGENT_IDS;
+    const infoFetches = [];
+    for (const agentId of agentsToShow) {
+        for (const ver of listInstalledVersions(agentId)) {
+            const home = getVersionHomePath(agentId, ver);
+            infoFetches.push(getAccountInfo(agentId, home).then((info) => ({ agentId, version: ver, home, info })));
+        }
+    }
+    const infoResults = await Promise.all(infoFetches);
+    const { canonicalByUsageKey, usageByKey } = await getUsageInfoByIdentity(infoResults.map(({ agentId, home, version, info }) => ({
+        agentId,
+        home,
+        cliVersion: version,
+        info,
+    })));
+    const mergeCanonical = (info) => {
+        const key = getUsageLookupKey(info);
+        if (!key)
+            return info;
+        const canon = canonicalByUsageKey.get(key);
+        if (!canon)
+            return info;
+        return {
+            ...info,
+            plan: canon.plan,
+            usageStatus: canon.usageStatus,
+            overageCredits: canon.overageCredits,
+        };
+    };
+    const byAgent = new Map();
+    for (const { agentId, version, info: rawInfo } of infoResults) {
+        const info = mergeCanonical(rawInfo);
+        const globalDefault = getGlobalDefault(agentId);
+        const usageKey = getUsageLookupKey(info);
+        const usageInfo = usageKey ? usageByKey.get(usageKey) : undefined;
+        const snapshot = usageInfo?.snapshot ?? null;
+        const entry = {
+            version,
+            isDefault: version === globalDefault,
+            signedIn: !!info.email,
+            email: info.email,
+            plan: info.plan,
+            usageStatus: info.usageStatus,
+            windows: snapshot
+                ? snapshot.windows.map((w) => ({
+                    key: w.key,
+                    usedPercent: w.usedPercent,
+                    resetsAt: w.resetsAt ? w.resetsAt.toISOString() : null,
+                }))
+                : [],
+            lastActive: info.lastActive ? info.lastActive.toISOString() : null,
+            path: getVersionDir(agentId, version),
+        };
+        const existing = byAgent.get(agentId);
+        if (existing)
+            existing.push(entry);
+        else
+            byAgent.set(agentId, [entry]);
+    }
+    const out = [];
+    for (const agentId of agentsToShow) {
+        const versions = byAgent.get(agentId) ?? [];
+        versions.sort((a, b) => {
+            if (a.isDefault !== b.isDefault)
+                return a.isDefault ? -1 : 1;
+            return compareVersions(b.version, a.version);
+        });
+        out.push({ agent: agentId, versions });
+    }
+    return out;
+}
+async function buildAgentPrunePlan(agentId) {
+    const entries = await Promise.all(listInstalledVersions(agentId).map(async (version) => {
+        const home = getVersionHomePath(agentId, version);
+        const info = await getAccountInfo(agentId, home);
+        return { version, info };
+    }));
+    const globalDefault = getGlobalDefault(agentId);
+    const byEmail = new Map();
+    for (const e of entries) {
+        if (!e.info.email)
+            continue;
+        const key = e.info.email.toLowerCase();
+        const list = byEmail.get(key) ?? [];
+        list.push(e);
+        byEmail.set(key, list);
+    }
+    const toPrune = [];
+    const skippedDefaults = [];
+    for (const [, group] of byEmail) {
+        if (group.length < 2)
+            continue;
+        const sorted = [...group].sort((a, b) => compareVersions(b.version, a.version));
+        const keeper = sorted[0].version;
+        for (const older of sorted.slice(1)) {
+            const plan = {
+                agentId,
+                version: older.version,
+                email: older.info.email,
+                keeper,
+                isDefault: older.version === globalDefault,
+            };
+            if (plan.isDefault)
+                skippedDefaults.push(plan);
+            else
+                toPrune.push(plan);
+        }
+    }
+    return { agentId, toPrune, skippedDefaults };
+}
+async function executePrunePlan(plan) {
+    let removed = 0;
+    for (const p of plan.toPrune) {
+        console.log(chalk.gray(`Removing ${agentLabel(p.agentId)}@${p.version}...`));
+        const ok = removeVersion(p.agentId, p.version);
+        if (ok) {
+            console.log(chalk.green(`Removed ${agentLabel(p.agentId)}@${p.version}`));
+            removed++;
+        }
+        else {
+            console.log(chalk.yellow(`Already gone: ${agentLabel(p.agentId)}@${p.version}`));
+        }
+    }
+    if (listInstalledVersions(plan.agentId).length === 0) {
+        removeShim(plan.agentId);
+    }
+    return removed;
+}
+function printPrunePlan(plan, isFirst) {
+    if (plan.skippedDefaults.length > 0) {
+        console.log(chalk.yellow(`Skipping default versions for ${agentLabel(plan.agentId)} (switch default first):`));
+        for (const s of plan.skippedDefaults) {
+            console.log(`  ${agentLabel(s.agentId)}@${s.version}  ${chalk.cyan(s.email)}  ` +
+                chalk.gray(`— duplicate of ${s.agentId}@${s.keeper}. Run: agents use ${s.agentId}@${s.keeper}`));
+        }
+        console.log();
+    }
+    if (plan.toPrune.length === 0)
+        return;
+    const heading = isFirst ? `Will prune ${agentLabel(plan.agentId)}:` : `Also found duplicates for ${agentLabel(plan.agentId)}:`;
+    console.log(chalk.bold(heading));
+    for (const p of plan.toPrune) {
+        console.log(`  ${agentLabel(p.agentId)}@${p.version}  ${chalk.cyan(p.email)}  ` +
+            chalk.gray(`— keeping ${p.agentId}@${p.keeper}`));
+    }
+    console.log();
+}
+/**
+ * Prune older installed versions that share an email with a newer installed
+ * version. Keeps the highest semver per email, skips the global default (with
+ * a warning so the user can switch first).
+ *
+ * When filterAgentId is set, prunes that agent first, then cascades: after
+ * each agent, offers the next agent with duplicates. User answering "no"
+ * stops the chain.
+ */
+export async function pruneDuplicates(filterAgentId, yes, dryRun) {
+    const ordered = filterAgentId
+        ? [filterAgentId, ...ALL_AGENT_IDS.filter((a) => a !== filterAgentId)]
+        : [...ALL_AGENT_IDS];
+    const spinner = ora({ text: 'Scanning installed versions...', isSilent: !process.stdout.isTTY }).start();
+    const plans = await Promise.all(ordered.map((a) => buildAgentPrunePlan(a)));
+    spinner.stop();
+    const actionable = plans.filter((p) => p.toPrune.length > 0 || p.skippedDefaults.length > 0);
+    if (actionable.length === 0) {
+        console.log(chalk.gray('Nothing to prune — no older versions share an account with a newer version.'));
+        return;
+    }
+    const totalCandidates = actionable.reduce((n, plan) => n + plan.toPrune.length, 0);
+    let totalRemoved = 0;
+    let isFirst = true;
+    let processedAny = false;
+    for (const plan of actionable) {
+        printPrunePlan(plan, isFirst);
+        if (plan.toPrune.length === 0) {
+            // Only skippedDefaults for this agent; move on.
+            isFirst = false;
+            continue;
+        }
+        if (dryRun) {
+            processedAny = true;
+            isFirst = false;
+            continue;
+        }
+        if (!yes) {
+            if (!isInteractiveTerminal()) {
+                console.log(chalk.red('Refusing to prune in a non-interactive shell without --yes.'));
+                if (filterAgentId) {
+                    console.log(chalk.gray(`Re-run with: agents prune ${filterAgentId} --dry-run`));
+                }
+                else {
+                    console.log(chalk.gray('Re-run with: agents prune --dry-run'));
+                }
+                process.exit(1);
+            }
+            const n = plan.toPrune.length;
+            const message = isFirst
+                ? `Prune ${n} ${agentLabel(plan.agentId)} version${n === 1 ? '' : 's'}?`
+                : `Also prune ${n} ${agentLabel(plan.agentId)} version${n === 1 ? '' : 's'}?`;
+            let proceed = false;
+            try {
+                proceed = await confirm({ message, default: false });
+            }
+            catch (err) {
+                if (isPromptCancelled(err)) {
+                    console.log(chalk.gray('Cancelled'));
+                    break;
+                }
+                throw err;
+            }
+            if (!proceed) {
+                console.log(chalk.gray('Stopping here.'));
+                break;
+            }
+        }
+        totalRemoved += await executePrunePlan(plan);
+        processedAny = true;
+        isFirst = false;
+        console.log();
+    }
+    if (dryRun) {
+        console.log(chalk.gray(`${totalCandidates} version${totalCandidates === 1 ? '' : 's'} would be pruned. Run without --dry-run to delete.`));
+        return;
+    }
+    if (processedAny) {
+        console.log(chalk.bold(`Pruned ${totalRemoved} version${totalRemoved === 1 ? '' : 's'}.`));
+    }
+}
 /**
  * Main view action handler.
  * Exported for use by deprecated aliases.
  */
-export async function viewAction(agentArg) {
+export async function viewAction(agentArg, options) {
+    const json = options?.json === true;
+    const prune = options?.prune === true;
+    const yes = options?.yes === true;
+    const dryRun = options?.dryRun === true;
     if (!agentArg) {
+        if (prune) {
+            await pruneDuplicates(undefined, yes, dryRun);
+            return;
+        }
+        if (json) {
+            const data = await collectAgentsJson();
+            console.log(JSON.stringify(data, null, 2));
+            return;
+        }
         // No argument: show all installed versions
         await showInstalledVersions();
         return;
@@ -539,12 +835,32 @@ export async function viewAction(agentArg) {
     // Parse agent@version syntax
     const parts = agentArg.split('@');
     const agentName = parts[0];
-    const requestedVersion = parts[1] || null;
     const agentId = resolveAgentName(agentName);
     if (!agentId) {
+        if (json) {
+            console.log(JSON.stringify({ error: formatAgentError(agentName) }));
+            process.exit(1);
+        }
         console.log(chalk.red(formatAgentError(agentName)));
         process.exit(1);
     }
+    const requestedVersion = resolveVersionAlias(agentId, parts[1]) ?? null;
+    if (prune) {
+        if (requestedVersion) {
+            console.log(chalk.red('--prune does not take a @version suffix.'));
+            console.log(chalk.gray(`Run: agents view ${agentId} --prune`));
+            process.exit(1);
+        }
+        await pruneDuplicates(agentId, yes, dryRun);
+        return;
+    }
+    if (json) {
+        // --json ignores the @version suffix (detailed resource view is not yet
+        // exposed as structured data). Emit the version list for the agent.
+        const data = await collectAgentsJson(agentId);
+        console.log(JSON.stringify(data[0] ?? { agent: agentId, versions: [] }, null, 2));
+        return;
+    }
     if (requestedVersion) {
         // Specific version requested: show detailed resources
         await showAgentResources(agentId, requestedVersion);
@@ -554,10 +870,15 @@ export async function viewAction(agentArg) {
         await showInstalledVersions(agentId);
     }
 }
+/** Register the `agents view` command. */
 export function registerViewCommand(program) {
     program
         .command('view [agent]')
         .description('Show what agent CLIs are installed and which versions you have. Inspect resources when you pass agent@version.')
+        .option('--json', 'Emit machine-readable JSON (version list, usage, signed-in status).')
+        .option('--prune', 'Remove older installed versions that share an account with a newer installed version. Skips the global default.')
+        .option('--dry-run', 'With --prune, show duplicate versions without deleting')
+        .option('-y, --yes', 'Skip the prune confirmation prompt.')
         .addHelpText('after', `
 Examples:
   # Show all installed agents with versions, accounts, and usage
@@ -570,17 +891,29 @@ Examples:
   agents view claude@2.1.112
   agents view claude@default
 
+  # Machine-readable output (used by tools that pick a version programmatically)
+  agents view claude --json
+
+  # Prune older versions that duplicate an account already used by a newer version
+  agents view --prune --dry-run
+  agents view claude --prune
+  agents view claude --prune -y
+
 When to use:
   - Checking which agents are installed and what their default versions are
   - Seeing which account each version is logged into (useful for multi-account setups)
   - Inspecting commands, skills, hooks, and MCP servers synced to a version
   - Verifying a version is installed before running it
+  - Cleaning up stale versions left behind after upgrading (--prune)
 
 Output:
   - Without arguments: table of all agents with versions, emails, usage stats
   - With agent name: versions for that agent, showing which is the default
   - With agent@version: detailed breakdown of resources synced to that version
+  - With --json: structured JSON with version, isDefault, signedIn, email, plan,
+    usageStatus, per-window usedPercent, lastActive, and path
+  - With --prune: plan of which older versions will be removed, then confirm
+  - With --prune --dry-run: preview only, no deletions
 `)
-        .action(viewAction);
+        .action((agentArg, options) => viewAction(agentArg, options));
 }
-//# sourceMappingURL=view.js.map

package/dist/index.d.ts

@@ -1,3 +1,8 @@
-#!/usr/bin/env node
+#!/usr/bin/env -S node --no-warnings=ExperimentalWarning
+/**
+ * CLI entry point for agents-cli.
+ *
+ * Registers all commands, handles update checks, auto-corrects typos,
+ * and launches the first-run interactive init when appropriate.
+ */
 export {};
-//# sourceMappingURL=index.d.ts.map