@swarmify/agents-cli 1.10.2 → 1.10.4

package/README.md

@@ -1,6 +1,8 @@
 # agents
 
-**One CLI for all your AI coding agents.**
+**The package manager and runtime for AI coding agents.**
+
+Install versions. Install skills. Run any agent through one interface. Build pipelines across Claude, Codex, Gemini, Cursor, OpenCode, and more.
 
 ```bash
 npm install -g @swarmify/agents-cli
@@ -8,23 +10,75 @@ npm install -g @swarmify/agents-cli
 
 Also available as `ag` -- all commands work with both `agents` and `ag`.
 
-## The Problem
+---
+
+## Run any agent. Same interface.
+
+```bash
+agents exec claude "Find all auth vulnerabilities in src/"
+agents exec codex "Fix the issues Claude found"
+agents exec gemini "Write tests for the fixed code"
+```
 
-You use Claude, Codex, Gemini, Cursor. Each has its own config location, MCP registration, command format, and version management. New machine? Redo everything. Teammate wants your setup? Good luck.
+Each agent resolves to the project-pinned version, with the right skills, MCP servers, and permissions already synced. No setup between steps -- just run.
 
-## The Solution
+This makes agent pipelines possible. Chain agents by strength, swap one for another, script them in CI -- the interface stays the same:
 
 ```bash
-agents pull gh:yourname/.agents    # One command. Every agent configured.
+# Friday night code review
+agents exec claude "Review all PRs merged this week, summarize risks" \
+  | agents exec codex "Write regression tests for the top 3 risks"
+
+# Same pipeline, different project -- different agent versions, same commands
+cd ../other-project
+agents exec claude "Review all PRs merged this week, summarize risks"
+# ^ resolves to claude@2.0.0 here instead of claude@2.1.89
 ```
 
-Your MCP servers, commands, skills, rules, hooks, and permissions -- synced to Claude, Codex, Gemini, Cursor, and OpenCode in one step.
+Supports plan (read-only) and edit modes, effort levels that map to the right model per agent, and JSON output for scripting.
 
 ---
 
-## What You Can Do
+## Non-interactive usage
+
+Other coding agents usually run in non-TTY shells. `agents` now supports that mode directly:
+
+```bash
+agents add codex@latest --yes
+agents use claude@2.1.79 --yes
+agents commands add --names review-pr,debug --agents codex
+agents skills add --names agents-cli --agents claude
+agents sessions view <session-id>
+agents routines view <job-name>
+```
+
+Rules for automation:
+
+- Pass explicit names or IDs instead of relying on pickers.
+- Use `--yes` when a command would otherwise ask for default sync or confirmation choices.
+- Use `--names` with `commands`, `skills`, `hooks`, `rules`, and `permissions` to install from central storage without a checkbox prompt.
+- Long `view` commands print directly in non-interactive shells instead of opening `less`.
+
+If a command still needs a human-only picker, it now exits with a plain-text hint that shows the matching non-interactive form.
+
+---
+
+## Pin agent versions per project
+
+```bash
+agents add claude@2.0.0             # Install specific version
+agents use claude@2.0.0 -p          # Pin to this project
+```
 
-### Manage skills across all agents
+Like `.nvmrc` for Node -- different projects use different agent versions. A shim system reads `.agents-version` and routes to the right binary automatically. No other tool does this for AI agents.
+
+When you switch versions, configs are backed up and resources are re-synced. Each version gets its own isolated home directory with the right skills, commands, and permissions already in place.
+
+---
+
+## Install skills, MCP servers, and commands once -- every agent gets them
+
+### Skills
 
 Skills are reusable knowledge packs -- rules, patterns, and expertise that make your agents better at specific tasks. Install once, available everywhere.
 
@@ -68,16 +122,6 @@ agents commands view review-pr              # View command content
 
 Commands are markdown files with a description. The CLI handles format conversion automatically -- markdown for Claude/Gemini/Cursor, TOML for Codex.
 
-### Version-lock agents per project
-
-```bash
-agents add claude@2.0.0           # Install specific version
-agents use claude@2.0.0 -p        # Pin to this project
-agents list                       # Show installed versions
-```
-
-Like `nvm` for Node -- different projects can use different agent versions. A shim system reads your project config and routes to the right version automatically.
-
 ### Sync your entire setup
 
 ```bash
@@ -107,16 +151,6 @@ agents routines logs daily-digest      # Check execution logs
 
 Jobs run sandboxed -- agents only see directories and tools you explicitly allow.
 
-### Run any agent with a unified interface
-
-```bash
-agents exec claude "Find all TODO comments in src/"
-agents exec codex -m edit "Add error handling to auth.ts"
-agents exec gemini -e detailed "Analyze this architecture"
-```
-
-Same interface, every agent. Supports plan (read-only) and edit modes, effort levels that map to the right model per agent, and JSON output for scripting.
-
 ### Manage rules/instructions, hooks, and permissions
 
 Each agent has its own instruction file format -- Claude uses `CLAUDE.md`, Codex uses `AGENTS.md`, Cursor uses `.cursorrules`. The CLI manages all of them under one command.
@@ -230,6 +264,10 @@ Add rule files in a `rules/` subdirectory -- each rule is a markdown file with s
 | OpenCode | yes | yes | yes | yes | AGENTS.md | yes | yes | -- |
 | OpenClaw | yes | yes | -- | yes | workspace/AGENTS.md | yes | -- | -- |
 
+## How It Compares
+
+See [docs/04-landscape.md](docs/04-landscape.md) for a detailed comparison with other tools in the ecosystem -- Rivet, Agentloom, mise, skills.sh, cass, Microsoft APM, and more.
+
 ## License
 
 MIT

package/dist/commands/__tests__/sessions.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=sessions.test.d.ts.map

package/dist/commands/__tests__/sessions.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessions.test.d.ts","sourceRoot":"","sources":["../../../src/commands/__tests__/sessions.test.ts"],"names":[],"mappings":""}

package/dist/commands/__tests__/sessions.test.js

@@ -0,0 +1,170 @@
+import { describe, it, expect } from 'vitest';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { spawnSync } from 'child_process';
+const repoRoot = process.cwd();
+const cliEntry = path.join(repoRoot, 'src', 'index.ts');
+const tsxBin = path.join(repoRoot, 'node_modules', '.bin', 'tsx');
+function writeUpdateCache(tempHome) {
+    const packageJson = JSON.parse(fs.readFileSync(path.join(repoRoot, 'package.json'), 'utf-8'));
+    fs.mkdirSync(path.join(tempHome, '.agents'), { recursive: true });
+    fs.writeFileSync(path.join(tempHome, '.agents', '.update-check'), JSON.stringify({ lastCheck: Date.now(), latestVersion: packageJson.version }), 'utf-8');
+}
+function writeClaudeSession(tempHome, projectKey, sessionId, cwd, content, timestamp) {
+    fs.mkdirSync(cwd, { recursive: true });
+    const sessionsDir = path.join(tempHome, '.claude', 'projects', projectKey);
+    fs.mkdirSync(sessionsDir, { recursive: true });
+    fs.writeFileSync(path.join(sessionsDir, `${sessionId}.jsonl`), JSON.stringify({
+        type: 'user',
+        timestamp,
+        cwd,
+        sessionId,
+        version: '2.1.110',
+        gitBranch: 'main',
+        message: { role: 'user', content },
+    }) + '\n', 'utf-8');
+}
+function runAgents(args, cwd, home) {
+    return spawnSync(tsxBin, [cliEntry, ...args], {
+        cwd,
+        env: { ...process.env, HOME: home },
+        encoding: 'utf-8',
+    });
+}
+function outputOf(result) {
+    return `${result.stdout}${result.stderr}`;
+}
+describe('agents sessions', () => {
+    it('lists only sessions from the current directory by default and shows all with --all', () => {
+        const tempHome = fs.mkdtempSync(path.join(os.tmpdir(), 'agents-sessions-list-'));
+        try {
+            writeUpdateCache(tempHome);
+            const swarmifyDir = path.join(tempHome, 'work', 'swarmify');
+            const agentsCliDir = path.join(tempHome, 'work', 'agents-cli');
+            const swarmifySessionId = '11111111-1111-4111-8111-111111111111';
+            const agentsCliSessionId = '22222222-2222-4222-8222-222222222222';
+            writeClaudeSession(tempHome, 'swarmify-test', swarmifySessionId, swarmifyDir, 'Inspect the swarmify session list', '2026-04-17T19:35:30.000Z');
+            writeClaudeSession(tempHome, 'agents-cli-test', agentsCliSessionId, agentsCliDir, 'Inspect the agents-cli session list', '2026-04-17T19:36:30.000Z');
+            const localResult = runAgents(['sessions'], swarmifyDir, tempHome);
+            expect(localResult.status).toBe(0);
+            const localOutput = outputOf(localResult);
+            expect(localOutput).toContain(swarmifySessionId.slice(0, 8));
+            expect(localOutput).not.toContain(agentsCliSessionId.slice(0, 8));
+            const allResult = runAgents(['sessions', '--all'], swarmifyDir, tempHome);
+            expect(allResult.status).toBe(0);
+            const allOutput = outputOf(allResult);
+            expect(allOutput).toContain(swarmifySessionId.slice(0, 8));
+            expect(allOutput).toContain(agentsCliSessionId.slice(0, 8));
+        }
+        finally {
+            fs.rmSync(tempHome, { recursive: true, force: true });
+        }
+    });
+});
+describe('agents sessions view', () => {
+    it('resolves explicit IDs across directories even when the default listing is scoped to cwd', () => {
+        const tempHome = fs.mkdtempSync(path.join(os.tmpdir(), 'agents-sessions-view-global-'));
+        try {
+            writeUpdateCache(tempHome);
+            const swarmifyDir = path.join(tempHome, 'work', 'swarmify');
+            const agentsCliDir = path.join(tempHome, 'work', 'agents-cli');
+            const siblingSessionId = '33333333-3333-4333-8333-333333333333';
+            writeClaudeSession(tempHome, 'swarmify-test', '44444444-4444-4444-8444-444444444444', swarmifyDir, 'Inspect the swarmify session list', '2026-04-17T19:35:30.000Z');
+            writeClaudeSession(tempHome, 'agents-cli-test', siblingSessionId, agentsCliDir, 'Review sibling repo state', '2026-04-17T19:36:30.000Z');
+            const result = runAgents(['sessions', 'view', siblingSessionId, '--transcript'], swarmifyDir, tempHome);
+            expect(result.status).toBe(0);
+            const output = outputOf(result);
+            expect(output).toContain('Review sibling repo state');
+            expect(output).not.toContain(`No session found matching: ${siblingSessionId}`);
+        }
+        finally {
+            fs.rmSync(tempHome, { recursive: true, force: true });
+        }
+    });
+    it('resolves Claude /resume history IDs to the resumed transcript', () => {
+        const tempHome = fs.mkdtempSync(path.join(os.tmpdir(), 'agents-sessions-view-'));
+        try {
+            writeUpdateCache(tempHome);
+            const projectRoot = path.join(tempHome, 'work', 'swarmify');
+            const transcriptCwd = path.join(projectRoot, 'extension');
+            const transcriptId = '92267176-d991-45c2-a8e5-e851e30a203b';
+            const historyOnlyId = 'f6a6cd2d-2138-41c4-b653-d2881ce9cdd3';
+            fs.mkdirSync(path.join(tempHome, '.claude', 'projects', 'swarmify-test'), { recursive: true });
+            fs.writeFileSync(path.join(tempHome, '.claude', 'history.jsonl'), JSON.stringify({
+                display: '/resume',
+                timestamp: Date.parse('2026-04-17T19:30:00.000Z'),
+                project: projectRoot,
+                sessionId: historyOnlyId,
+            }) + '\n', 'utf-8');
+            fs.mkdirSync(transcriptCwd, { recursive: true });
+            fs.writeFileSync(path.join(tempHome, '.claude', 'projects', 'swarmify-test', `${transcriptId}.jsonl`), [
+                JSON.stringify({
+                    type: 'user',
+                    timestamp: '2026-04-17T19:00:00.000Z',
+                    cwd: transcriptCwd,
+                    sessionId: transcriptId,
+                    version: '2.1.110',
+                    gitBranch: 'main',
+                    message: { role: 'user', content: 'Earlier context' },
+                }),
+                JSON.stringify({
+                    type: 'assistant',
+                    timestamp: '2026-04-17T19:00:05.000Z',
+                    cwd: transcriptCwd,
+                    sessionId: transcriptId,
+                    version: '2.1.110',
+                    gitBranch: 'main',
+                    message: {
+                        role: 'assistant',
+                        content: [{ type: 'text', text: 'Earlier reply' }],
+                    },
+                }),
+                JSON.stringify({
+                    type: 'attachment',
+                    timestamp: '2026-04-17T19:30:30.000Z',
+                    cwd: transcriptCwd,
+                    sessionId: transcriptId,
+                    version: '2.1.110',
+                    gitBranch: 'main',
+                    attachment: {
+                        type: 'hook_success',
+                        hookName: 'SessionStart:resume',
+                        hookEvent: 'SessionStart',
+                    },
+                }),
+                JSON.stringify({
+                    type: 'user',
+                    timestamp: '2026-04-17T19:30:45.000Z',
+                    cwd: transcriptCwd,
+                    sessionId: transcriptId,
+                    version: '2.1.110',
+                    gitBranch: 'main',
+                    message: { role: 'user', content: 'Continue from where we left off' },
+                }),
+                JSON.stringify({
+                    type: 'assistant',
+                    timestamp: '2026-04-17T19:31:00.000Z',
+                    cwd: transcriptCwd,
+                    sessionId: transcriptId,
+                    version: '2.1.110',
+                    gitBranch: 'main',
+                    message: {
+                        role: 'assistant',
+                        content: [{ type: 'text', text: 'Loaded resumed transcript' }],
+                    },
+                }),
+            ].join('\n') + '\n', 'utf-8');
+            const result = runAgents(['sessions', 'view', historyOnlyId, '--transcript'], repoRoot, tempHome);
+            expect(result.status).toBe(0);
+            const output = outputOf(result);
+            expect(output).toContain(`Resolved Claude history entry ${historyOnlyId} to transcript ${transcriptId}.`);
+            expect(output).toContain('Loaded resumed transcript');
+            expect(output).not.toContain(`No transcript session found matching: ${historyOnlyId}`);
+        }
+        finally {
+            fs.rmSync(tempHome, { recursive: true, force: true });
+        }
+    });
+});
+//# sourceMappingURL=sessions.test.js.map

package/dist/commands/__tests__/sessions.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessions.test.js","sourceRoot":"","sources":["../../../src/commands/__tests__/sessions.test.ts"],"names":[],"mappings":"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"}

package/dist/commands/commands.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../src/commands/commands.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAoCzC,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAgd/D"}
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../src/commands/commands.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA4CzC,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAoe/D"}

package/dist/commands/commands.js

@@ -4,12 +4,12 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import { checkbox } from '@inquirer/prompts';
-import { AGENTS, ALL_AGENT_IDS, resolveAgentName, formatAgentError, } from '../lib/agents.js';
+import { AGENTS, ALL_AGENT_IDS, resolveAgentName, formatAgentError, agentLabel, } from '../lib/agents.js';
 import { cloneRepo } from '../lib/git.js';
 import { discoverCommands, resolveCommandSource, installCommandCentrally, uninstallCommand, listCentralCommands, listInstalledCommandsWithScope, getCommandInfo, } from '../lib/commands.js';
 import { listInstalledVersions, getGlobalDefault, syncResourcesToVersion, promptAgentVersionSelection, getVersionHomePath, } from '../lib/versions.js';
 import { recordVersionResources } from '../lib/state.js';
-import { isPromptCancelled, formatPath } from './utils.js';
+import { isPromptCancelled, formatPath, isInteractiveTerminal, parseCommaSeparatedList, printWithPager, requireInteractiveSelection, } from './utils.js';
 export function registerCommandsCommands(program) {
     const commandsCmd = program
         .command('commands')
@@ -45,10 +45,10 @@ export function registerCommandsCommands(program) {
             const defaultLabel = isDefault ? ' default' : '';
             const versionStr = chalk.gray(` (${version}${defaultLabel})`);
             if (commands.length === 0) {
-                console.log(`  ${chalk.bold(agent.name)}${versionStr}: ${chalk.gray('none')}`);
+                console.log(`  ${chalk.bold(agentLabel(agent.id))}${versionStr}: ${chalk.gray('none')}`);
             }
             else {
-                console.log(`  ${chalk.bold(agent.name)}${versionStr}:`);
+                console.log(`  ${chalk.bold(agentLabel(agent.id))}${versionStr}:`);
                 const userCommands = commands.filter((c) => c.scope === 'user');
                 const projectCommands = commands.filter((c) => c.scope === 'project');
                 if (userCommands.length > 0 && (options.scope === 'all' || options.scope === 'user')) {
@@ -74,13 +74,13 @@ export function registerCommandsCommands(program) {
             const defaultVer = getGlobalDefault(agentId);
             if (installedVersions.length === 0) {
                 // Not version-managed, show from effective home
-                console.log(chalk.bold(`Installed Commands for ${agent.name}\n`));
+                console.log(chalk.bold(`Installed Commands for ${agentLabel(agent.id)}\n`));
                 const commands = listInstalledCommandsWithScope(agentId, cwd).filter((c) => options.scope === 'all' || c.scope === options.scope);
                 if (commands.length === 0) {
-                    console.log(`  ${chalk.bold(agent.name)}: ${chalk.gray('none')}`);
+                    console.log(`  ${chalk.bold(agentLabel(agent.id))}: ${chalk.gray('none')}`);
                 }
                 else {
-                    console.log(`  ${chalk.bold(agent.name)}:`);
+                    console.log(`  ${chalk.bold(agentLabel(agent.id))}:`);
                     const userCommands = commands.filter((c) => c.scope === 'user');
                     if (userCommands.length > 0) {
                         console.log(`    ${chalk.gray('User:')}`);
@@ -91,18 +91,18 @@ export function registerCommandsCommands(program) {
                 }
                 return;
             }
-            console.log(chalk.bold(`Installed Commands for ${agent.name}\n`));
+            console.log(chalk.bold(`Installed Commands for ${agentLabel(agent.id)}\n`));
             let versionsToShow;
             if (requestedVersion === 'default') {
                 if (!defaultVer) {
-                    console.log(chalk.yellow(`  No default version set for ${agent.name}. Run: agents use ${agentId}@<version>`));
+                    console.log(chalk.yellow(`  No default version set for ${agentLabel(agent.id)}. Run: agents use ${agentId}@<version>`));
                     return;
                 }
                 versionsToShow = [defaultVer];
             }
             else if (requestedVersion) {
                 if (!installedVersions.includes(requestedVersion)) {
-                    console.log(chalk.red(`  Version ${requestedVersion} not installed for ${agent.name}.`));
+                    console.log(chalk.red(`  Version ${requestedVersion} not installed for ${agentLabel(agent.id)}.`));
                     console.log(chalk.gray(`  Installed versions: ${installedVersions.join(', ')}`));
                     return;
                 }
@@ -137,10 +137,10 @@ export function registerCommandsCommands(program) {
                 // Version managed but no default
                 const commands = listInstalledCommandsWithScope(aid, cwd).filter((c) => options.scope === 'all' || c.scope === options.scope);
                 if (commands.length === 0) {
-                    console.log(`  ${chalk.bold(agent.name)}: ${chalk.gray('none')}`);
+                    console.log(`  ${chalk.bold(agentLabel(aid))}: ${chalk.gray('none')}`);
                 }
                 else {
-                    console.log(`  ${chalk.bold(agent.name)}:`);
+                    console.log(`  ${chalk.bold(agentLabel(aid))}:`);
                     const userCommands = commands.filter((c) => c.scope === 'user');
                     if (userCommands.length > 0) {
                         console.log(`    ${chalk.gray('User:')}`);
@@ -157,6 +157,7 @@ export function registerCommandsCommands(program) {
         .command('add [source]')
         .description('Install commands from a repo or local path')
         .option('-a, --agents <list>', 'Comma-separated agents to install to')
+        .option('--names <list>', 'Comma-separated command names from ~/.agents/commands/')
         .option('-y, --yes', 'Skip prompts and use defaults')
         .action(async (source, options) => {
         try {
@@ -171,35 +172,54 @@ export function registerCommandsCommands(program) {
                     console.log(chalk.cyan('  agents commands add gh:user/repo'));
                     return;
                 }
-                // Build choices with descriptions
-                const choices = centralCommands.map((name) => {
-                    const cmdPath = path.join(os.homedir(), '.agents', 'commands', `${name}.md`);
-                    let description = '';
-                    if (fs.existsSync(cmdPath)) {
-                        const content = fs.readFileSync(cmdPath, 'utf-8');
-                        const match = content.match(/description:\s*(.+)/i) || content.match(/description\s*=\s*"([^"]+)"/);
-                        if (match)
-                            description = match[1].trim();
+                const requestedNames = parseCommaSeparatedList(options.names);
+                let selectedNames;
+                if (requestedNames.length > 0) {
+                    const missing = requestedNames.filter((name) => !centralCommands.includes(name));
+                    if (missing.length > 0) {
+                        console.log(chalk.red(`Unknown command(s): ${missing.join(', ')}`));
+                        console.log(chalk.gray(`Available: ${centralCommands.join(', ')}`));
+                        process.exit(1);
                     }
-                    return {
-                        value: name,
-                        name: description ? `${name}  ${chalk.gray(description.slice(0, 50))}` : name,
-                    };
-                });
-                const selected = await checkbox({
-                    message: 'Select commands to install',
-                    choices: [
-                        { value: '__all__', name: chalk.bold('Select All') },
-                        ...choices,
-                    ],
-                });
-                if (selected.length === 0) {
-                    console.log(chalk.gray('No commands selected.'));
-                    return;
+                    selectedNames = requestedNames;
+                }
+                else {
+                    if (!isInteractiveTerminal()) {
+                        requireInteractiveSelection('Selecting commands from ~/.agents/commands/', [
+                            'agents commands add --names README,debug --agents codex',
+                            'agents commands add gh:user/repo --agents codex',
+                        ]);
+                    }
+                    // Build choices with descriptions
+                    const choices = centralCommands.map((name) => {
+                        const cmdPath = path.join(os.homedir(), '.agents', 'commands', `${name}.md`);
+                        let description = '';
+                        if (fs.existsSync(cmdPath)) {
+                            const content = fs.readFileSync(cmdPath, 'utf-8');
+                            const match = content.match(/description:\s*(.+)/i) || content.match(/description\s*=\s*"([^"]+)"/);
+                            if (match)
+                                description = match[1].trim();
+                        }
+                        return {
+                            value: name,
+                            name: description ? `${name}  ${chalk.gray(description.slice(0, 50))}` : name,
+                        };
+                    });
+                    const selected = await checkbox({
+                        message: 'Select commands to install',
+                        choices: [
+                            { value: '__all__', name: chalk.bold('Select All') },
+                            ...choices,
+                        ],
+                    });
+                    if (selected.length === 0) {
+                        console.log(chalk.gray('No commands selected.'));
+                        return;
+                    }
+                    selectedNames = selected.includes('__all__')
+                        ? centralCommands
+                        : selected.filter((s) => s !== '__all__');
                 }
-                const selectedNames = selected.includes('__all__')
-                    ? centralCommands
-                    : selected.filter((s) => s !== '__all__');
                 commands = selectedNames.map((name) => ({ name, description: '' }));
                 fromCentral = true;
             }
@@ -269,7 +289,9 @@ export function registerCommandsCommands(program) {
                 }
             }
             else {
-                const result = await promptAgentVersionSelection(ALL_AGENT_IDS, { skipPrompts: options.yes });
+                const result = await promptAgentVersionSelection(ALL_AGENT_IDS, {
+                    skipPrompts: options.yes || !isInteractiveTerminal(),
+                });
                 selectedAgents = result.selectedAgents;
                 versionSelections = result.versionSelections;
             }
@@ -322,6 +344,11 @@ export function registerCommandsCommands(program) {
                 console.log(chalk.yellow('No commands installed.'));
                 return;
             }
+            if (!isInteractiveTerminal()) {
+                requireInteractiveSelection('Selecting commands to remove', [
+                    'agents commands remove README',
+                ]);
+            }
             try {
                 const selected = await checkbox({
                     message: 'Select commands to remove',
@@ -351,7 +378,7 @@ export function registerCommandsCommands(program) {
             let removed = 0;
             for (const agentId of agents) {
                 if (uninstallCommand(agentId, cmdName)) {
-                    console.log(`  ${chalk.red('-')} ${AGENTS[agentId].name}: ${cmdName}`);
+                    console.log(`  ${chalk.red('-')} ${agentLabel(agentId)}: ${cmdName}`);
                     removed++;
                 }
             }
@@ -371,6 +398,11 @@ export function registerCommandsCommands(program) {
                 console.log(chalk.yellow('No commands installed'));
                 return;
             }
+            if (!isInteractiveTerminal()) {
+                requireInteractiveSelection('Selecting a command to view', [
+                    'agents commands view README',
+                ]);
+            }
             try {
                 const { select } = await import('@inquirer/prompts');
                 name = await select({
@@ -405,21 +437,7 @@ export function registerCommandsCommands(program) {
         if (command.content) {
             const rendered = renderMarkdown(command.content);
             const contentLines = command.content.split('\n');
-            // Pipe through less for scrolling if content is large
-            if (contentLines.length > 40) {
-                const { spawnSync } = await import('child_process');
-                const less = spawnSync('less', ['-R'], {
-                    input: rendered,
-                    stdio: ['pipe', 'inherit', 'inherit'],
-                });
-                // Fallback to direct output if less fails
-                if (less.status !== 0) {
-                    console.log(rendered);
-                }
-            }
-            else {
-                console.log(rendered);
-            }
+            printWithPager(rendered, contentLines.length);
         }
     });
 }