@phnx-labs/agents-cli 1.18.5 → 1.19.0

package/dist/commands/pty.js

@@ -19,61 +19,65 @@ 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';
+import { setHelpSections } from '../lib/help.js';
 /** Register the `agents pty` command tree. */
 export function registerPtyCommands(program) {
     const pty = program
         .command('pty')
-        .description('Drive interactive terminal programs from AI agents. Use this for REPLs, TUIs, or anything needing a real terminal.')
-        .addHelpText('after', `
-Typical session workflow:
-  # Start a new terminal session (returns a session ID)
-  SID=$(agents pty start)
+        .description('Drive interactive terminal programs from AI agents. Use this for REPLs, TUIs, or anything needing a real terminal.');
+    setHelpSections(pty, {
+        examples: `
+      # Start a session (returns a session ID)
+      SID=$(agents pty start)
 
-  # Run a command (non-blocking, returns immediately)
-  agents pty exec $SID "python3"
+      # Run a command (non-blocking)
+      agents pty exec $SID "python3"
 
-  # Wait a moment, then see what's on screen (clean text, no ANSI)
-  sleep 1 && agents pty screen $SID
+      # Wait, then see what's on screen (clean text, no ANSI)
+      sleep 1 && agents pty screen $SID
 
-  # Send input (supports escape sequences: \\n \\t \\e \\xHH)
-  agents pty write $SID "print('hello')\\n"
+      # Type input (supports escapes: \\n \\t \\e \\xHH)
+      agents pty write $SID "print('hello')\\n"
 
-  # Read the output again
-  agents pty screen $SID
+      # Read again
+      agents pty screen $SID
 
-  # Clean up when done
-  agents pty stop $SID
+      # Clean up
+      agents pty stop $SID
+    `,
+        notes: `
+      Use cases:
+        - Drive REPLs (python, node, irb) from agent code
+        - Automate TUI programs (npm init, interactive wizards)
+        - Test CLI tools that require a real PTY
+        - Run the 'agents' CLI itself from another agent
 
-Use cases:
-  - Drive REPLs (python, node, irb) from agent code
-  - Automate TUI programs (npm init, interactive wizards)
-  - Test CLI tools that require a real PTY
-  - Run the 'agents' CLI itself from another agent
-
-The PTY server auto-starts on first use and runs in the background.
-Use 'agents pty server status' to check health.
-`);
+      The PTY server auto-starts on first use and runs in the background.
+      Health: 'agents pty server status'.
+    `,
+    });
     // --- Session lifecycle ---
-    pty
+    const startCmd = pty
         .command('start')
         .description('Start a new PTY session and return its ID. The session persists until you stop it.')
         .option('-r, --rows <n>', 'Terminal height in rows', '24')
         .option('-c, --cols <n>', 'Terminal width in columns', '120')
         .option('-s, --shell <shell>', 'Shell to launch (defaults to $SHELL, e.g., zsh, bash)')
         .option('-d, --cwd <dir>', 'Working directory for the shell')
-        .option('--json', 'Output full session metadata as JSON')
-        .addHelpText('after', `
-Examples:
-  # Start a session and capture its ID
-  SID=$(agents pty start)
+        .option('--json', 'Output full session metadata as JSON');
+    setHelpSections(startCmd, {
+        examples: `
+      # Start a session and capture its ID
+      SID=$(agents pty start)
 
-  # Start a Python REPL in a specific directory
-  agents pty start --shell python3 --cwd /tmp
+      # Start a Python REPL in a specific directory
+      agents pty start --shell python3 --cwd /tmp
 
-  # Start a wider terminal for TUI programs
-  agents pty start --cols 160 --rows 40
-`)
-        .action(async (opts) => {
+      # Start a wider terminal for TUI programs
+      agents pty start --cols 160 --rows 40
+    `,
+    });
+    startCmd.action(async (opts) => {
         const params = {
             rows: parseInt(opts.rows, 10),
             cols: parseInt(opts.cols, 10),
@@ -94,23 +98,24 @@ Examples:
             console.log(res.id);
         }
     });
-    pty
+    const execCmd = pty
         .command('exec <id> <command>')
         .description('Send a command to a PTY session. Returns immediately (non-blocking). Use screen or read to see output.')
         .option('--wait <ms>', 'Wait this many milliseconds then return the screen (convenience for quick commands)', '0')
-        .option('--json', 'Output as JSON')
-        .addHelpText('after', `
-Examples:
-  # Run a command and return immediately
-  agents pty exec $SID "ls -la"
+        .option('--json', 'Output as JSON');
+    setHelpSections(execCmd, {
+        examples: `
+      # Run a command and return immediately
+      agents pty exec $SID "ls -la"
 
-  # Run a command and wait 500ms to see output
-  agents pty exec $SID "git status" --wait 500
+      # Run a command and wait 500ms to see output
+      agents pty exec $SID "git status" --wait 500
 
-  # Start a long-running process (returns right away)
-  agents pty exec $SID "npm run dev"
-`)
-        .action(async (id, command, opts) => {
+      # Start a long-running process (returns right away)
+      agents pty exec $SID "npm run dev"
+    `,
+    });
+    execCmd.action(async (id, command, opts) => {
         const res = await ptyRequest('exec', id, { command });
         if (!res.ok) {
             console.error(chalk.red(res.error));
@@ -132,20 +137,21 @@ Examples:
             console.log(JSON.stringify(res));
         }
     });
-    pty
+    const readCmd = pty
         .command('read <id>')
         .description('Read raw output from the PTY (includes ANSI codes). Use screen for clean text instead.')
         .option('-m, --ms <ms>', 'Wait up to this many milliseconds for new output (50-5000)', '200')
-        .option('--json', 'Output as JSON')
-        .addHelpText('after', `
-Examples:
-  # Read pending output (wait up to 200ms)
-  agents pty read $SID
+        .option('--json', 'Output as JSON');
+    setHelpSections(readCmd, {
+        examples: `
+      # Read pending output (wait up to 200ms)
+      agents pty read $SID
 
-  # Read with longer wait for slow commands
-  agents pty read $SID --ms 1000
-`)
-        .action(async (id, opts) => {
+      # Read with longer wait for slow commands
+      agents pty read $SID --ms 1000
+    `,
+    });
+    readCmd.action(async (id, opts) => {
         const ms = parseInt(opts.ms, 10);
         const res = await ptyRequest('read', id, { ms });
         if (!res.ok) {
@@ -160,29 +166,30 @@ Examples:
                 process.stdout.write(res.output);
         }
     });
-    pty
+    const writeCmd = pty
         .command('write <id> <input>')
         .description('Send keystrokes to the PTY (like typing into the terminal). Processes escape sequences by default.')
         .option('--raw', 'Send input literally without processing \\n \\t \\e \\xHH escape codes')
-        .option('--json', 'Output as JSON')
-        .addHelpText('after', `
-Examples:
-  # Send Enter key
-  agents pty write $SID "\\n"
+        .option('--json', 'Output as JSON');
+    setHelpSections(writeCmd, {
+        examples: `
+      # Send Enter key
+      agents pty write $SID "\\n"
 
-  # Type a command and press Enter
-  agents pty write $SID "ls -la\\n"
+      # Type a command and press Enter
+      agents pty write $SID "ls -la\\n"
 
-  # Send Ctrl-C (interrupt signal)
-  agents pty write $SID "\\x03"
+      # Send Ctrl-C (interrupt signal)
+      agents pty write $SID "\\x03"
 
-  # Send Escape key
-  agents pty write $SID "\\e"
+      # Send Escape key
+      agents pty write $SID "\\e"
 
-  # Send literal backslash-n (not newline)
-  agents pty write $SID "\\\\n" --raw
-`)
-        .action(async (id, input, opts) => {
+      # Send literal backslash-n (not newline)
+      agents pty write $SID "\\\\n" --raw
+    `,
+    });
+    writeCmd.action(async (id, input, opts) => {
         const processed = opts.raw ? input : unescapeInput(input);
         const res = await ptyRequest('write', id, { input: processed });
         if (!res.ok) {
@@ -193,21 +200,23 @@ Examples:
             console.log(JSON.stringify(res));
         }
     });
-    pty
+    const screenCmd = pty
         .command('screen <id>')
         .description('Render the terminal screen as clean text (no ANSI codes). This is what a human sees looking at the terminal.')
-        .option('--json', 'Output as JSON (includes cursor position and dimensions)')
-        .addHelpText('after', `
-Examples:
-  # See what's currently on screen
-  agents pty screen $SID
-
-  # Get screen with cursor position as JSON
-  agents pty screen $SID --json
+        .option('--json', 'Output as JSON (includes cursor position and dimensions)');
+    setHelpSections(screenCmd, {
+        examples: `
+      # See what's currently on screen
+      agents pty screen $SID
 
-Use this (not read) when you want clean text for an LLM to parse.
-`)
-        .action(async (id, opts) => {
+      # Get screen with cursor position as JSON
+      agents pty screen $SID --json
+    `,
+        notes: `
+      Use this (not read) when you want clean text for an LLM to parse.
+    `,
+    });
+    screenCmd.action(async (id, opts) => {
         const res = await ptyRequest('screen', id);
         if (!res.ok) {
             console.error(chalk.red(res.error));
@@ -220,21 +229,22 @@ Use this (not read) when you want clean text for an LLM to parse.
             console.log(res.screen);
         }
     });
-    pty
+    const signalCmd = pty
         .command('signal <id> [signal]')
-        .description('Send a POSIX signal to the running process. Defaults to INT (Ctrl-C).')
-        .addHelpText('after', `
-Examples:
-  # Send Ctrl-C (interrupt)
-  agents pty signal $SID INT
+        .description('Send a POSIX signal to the running process. Defaults to INT (Ctrl-C).');
+    setHelpSections(signalCmd, {
+        examples: `
+      # Send Ctrl-C (interrupt)
+      agents pty signal $SID INT
 
-  # Terminate gracefully
-  agents pty signal $SID TERM
+      # Terminate gracefully
+      agents pty signal $SID TERM
 
-  # Force kill
-  agents pty signal $SID KILL
-`)
-        .action(async (id, signal) => {
+      # Force kill
+      agents pty signal $SID KILL
+    `,
+    });
+    signalCmd.action(async (id, signal) => {
         const res = await ptyRequest('signal', id, { signal: signal || 'INT' });
         if (!res.ok) {
             console.error(chalk.red(res.error));
@@ -259,14 +269,16 @@ Examples:
         }
         console.log(`${res.cols}x${res.rows}`);
     });
-    pty
+    const stopCmd = pty
         .command('stop <id>')
-        .description('Stop a PTY session and clean up. The session ID becomes invalid.')
-        .addHelpText('after', `
-Example:
-  agents pty stop $SID
-`)
-        .action(async (id) => {
+        .description('Stop a PTY session and clean up. The session ID becomes invalid.');
+    setHelpSections(stopCmd, {
+        examples: `
+      # Stop a session by ID
+      agents pty stop $SID
+    `,
+    });
+    stopCmd.action(async (id) => {
         const res = await ptyRequest('stop', id);
         if (!res.ok) {
             console.error(chalk.red(res.error));
@@ -274,15 +286,17 @@ Example:
         }
     });
     // --- Session listing ---
-    pty
+    const listCmd = pty
         .command('list')
         .description('List all active PTY sessions (running or idle).')
-        .option('--json', 'Output as JSON')
-        .addHelpText('after', `
-Example:
-  agents pty list
-`)
-        .action(async (opts) => {
+        .option('--json', 'Output as JSON');
+    setHelpSections(listCmd, {
+        examples: `
+      # List all active sessions
+      agents pty list
+    `,
+    });
+    listCmd.action(async (opts) => {
         const res = await ptyRequest('list');
         if (!res.ok) {
             console.error(chalk.red(res.error));

package/dist/commands/pull.js

@@ -16,6 +16,7 @@ import * as path from 'path';
 import { installVersion, listInstalledVersions, getGlobalDefault, setGlobalDefault, getVersionHomePath, syncResourcesToVersion, getAvailableResources, getActuallySyncedResources, getNewResources, hasNewResources, promptNewResourceSelection, promptResourceSelection, resolveConfiguredAgentTargets, } from '../lib/versions.js';
 import { ensureShimCurrent, isShimsInPath, addShimsToPath, getPathSetupInstructions, switchConfigSymlink, switchHomeFileSymlinks, } from '../lib/shims.js';
 import { parseHookManifest, registerHooksToSettings } from '../lib/hooks.js';
+import { setHelpSections } from '../lib/help.js';
 import { select } from '@inquirer/prompts';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 /**
@@ -45,37 +46,40 @@ function migratePromptcutsToRoot(agentsDir) {
 }
 /** Register the `agents pull` command. */
 export function registerPullCommand(program) {
-    program
+    const pullCmd = program
         .command('pull [agent]')
-        .description('Pull your user repo at ~/.agents/ and refresh installed agent versions.')
+        .description('Sync your user repo at ~/.agents/ and refresh installed agent CLIs. (Deprecated — prefer \'agents repo pull\' and \'agents setup\'.)')
         .option('-y, --yes', 'Auto-sync all resources without prompting')
-        .option('--skip-clis', 'Pull config changes but do not install or upgrade agent CLIs')
-        .addHelpText('after', `
-Examples:
-  # First time: clone the system repo into ~/.agents-system/
-  agents pull
+        .option('--skip-clis', 'Pull config changes but do not install or upgrade agent CLIs');
+    setHelpSections(pullCmd, {
+        examples: `
+      # First time: clone the system repo into ~/.agents-system/
+      agents pull
 
-  # Sync only one agent's config
-  agents pull claude
+      # Sync only one agent's config
+      agents pull claude
 
-  # Non-interactive sync (for scripts / CI)
-  agents pull -y
+      # Non-interactive (scripts / CI)
+      agents pull -y
 
-When to use:
-  - Initial setup: clone the system repo to a new machine
-  - Daily sync: pull the latest system skills, commands, or MCP servers
-  - Per-agent: sync just one agent's config without touching others
+      # Sync config without touching installed CLI versions
+      agents pull --skip-clis
+    `,
+        notes: `
+      Deprecated. Use:
+        agents setup       first-time setup
+        agents repo pull   force-sync now
+        agents repo push   push your user repo
 
-What it syncs:
-  - CLI versions listed in agents.yaml
-  - Commands, skills, hooks from the repo
-  - MCP server configs
-  - Memory/rules files
-  - Permissions groups
-
-Skip CLI installs with --skip-clis when you only want config updates, not version changes.
-`)
-        .action(async (arg1, options) => {
+      What it syncs:
+        - CLI versions listed in agents.yaml
+        - Commands, skills, hooks
+        - MCP server configs
+        - Memory/rules files
+        - Permissions groups
+    `,
+    });
+    pullCmd.action(async (arg1, options) => {
         // Deprecation banner — `agents pull` is on its way out. agents-cli now
         // auto-syncs the system repo in the background and surfaces upstream
         // changes for user/extra repos as one-line notices. Repo lifecycle is

package/dist/commands/repo.js

@@ -6,6 +6,7 @@ import * as os from 'os';
 import simpleGit from 'simple-git';
 import { confirm, input } from '@inquirer/prompts';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
+import { setHelpSections } from '../lib/help.js';
 const HOME = os.homedir();
 /**
  * Resolve a target argument to an absolute path.
@@ -56,38 +57,35 @@ async function getShortCommit(repoDir) {
 export function registerRepoCommands(program) {
     const repoCmd = program
         .command('repo')
-        .description('Manage extra DotAgent repos alongside ~/.agents/ (for private or team skills)')
-        .addHelpText('after', `
-Managed extras live at ~/.agents-<alias>/ as peer dirs to ~/.agents/. User-owned
-repos can also live anywhere and be registered by path. Their skills, commands,
-and hooks merge into agent version homes after the user repo's — so ~/.agents/
-wins on name collisions.
+        .description('Manage extra DotAgent repos alongside ~/.agents/ (for private or team skills).');
+    setHelpSections(repoCmd, {
+        examples: `
+      # Scaffold an editable repo (default: ~/.agents/)
+      agents repo init
 
-Examples:
-  # Scaffold your own editable repo (default: ~/.agents/)
-  agents repo init
+      # Scaffold a named repo at ~/.agents-work/
+      agents repo init work
 
-  # Scaffold a named repo (creates ~/.agents-work/)
-  agents repo init work
+      # Register an existing repo (clones to ~/.agents-<alias>/)
+      agents repo add gh:yourname/.agents-work
 
-  # Scaffold at a custom path
-  agents repo init ~/my-agents
+      # Register with a custom alias
+      agents repo add git@github.com:acme/team-skills.git --as acme
 
-  # Add a private repo for work-only skills
-  agents repo add gh:yourname/.agents-work
+      # See what's registered
+      agents repo list
 
-  # Add with a custom alias
-  agents repo add git@github.com:acme/team-skills.git --as acme
+      # Temporarily disable without deleting
+      agents repo disable acme
+    `,
+        notes: `
+      Managed extras live at ~/.agents-<alias>/ as peer dirs to ~/.agents/. User-owned
+      repos can also live anywhere and be registered by path.
 
-  # Show all registered repos
-  agents repo list
-
-  # Temporarily disable without deleting
-  agents repo disable acme
-
-  # Unregister it
-  agents repo remove acme
-`);
+      Resolution: skills/commands/hooks merge into agent version homes after the user
+      repo's, so ~/.agents/ wins on name collisions.
+    `,
+    });
     repoCmd
         .command('init [target]')
         .description('Create a user-owned repo from a template and register it as an extra')

package/dist/commands/routines.js

@@ -17,6 +17,7 @@ import { safeJoin } from '../lib/paths.js';
 import { executeJob } from '../lib/runner.js';
 import { JobScheduler } from '../lib/scheduler.js';
 import { isInteractiveTerminal, requireInteractiveSelection } from './utils.js';
+import { setHelpSections } from '../lib/help.js';
 /** Start or reload the background scheduler so newly-added jobs fire on time. */
 function ensureSchedulerRunning() {
     if (isDaemonRunning()) {
@@ -75,36 +76,38 @@ async function pickJob(message, filter, alternatives = []) {
 export function registerRoutinesCommands(program) {
     const routinesCmd = program
         .command('routines')
-        .description('Schedule agents to run on a cron schedule or at a specific time. The scheduler auto-starts on first add.')
-        .addHelpText('after', `
-A routine is a YAML file that schedules an agent invocation. It specifies:
-  - which agent to run (claude, codex, gemini, etc.)
-  - when to run (cron schedule or one-shot time)
-  - what task to give the agent (the prompt)
-  - execution constraints (mode, effort, timeout)
+        .description('Schedule agents to run on a cron schedule or at a specific time. The scheduler auto-starts on first add.');
+    setHelpSections(routinesCmd, {
+        examples: `
+      # Cron routine: Claude every weekday at 9 AM (scheduler auto-starts)
+      agents routines add daily-standup --schedule "0 9 * * 1-5" --agent claude --prompt "Draft standup from git log"
 
-A background scheduler fires routines on their schedule. It auto-starts the first
-time you add a routine; control it manually with 'agents routines start|stop|status'.
+      # One-shot: Codex tomorrow at 2:30 PM, then never again
+      agents routines add hotfix-review --at "14:30" --agent codex --prompt "Review hotfix PR #42"
 
-Examples:
-  # Create a routine that runs Claude every weekday at 9 AM (scheduler auto-starts)
-  agents routines add daily-standup --schedule "0 9 * * 1-5" --agent claude --prompt "Draft standup update from git log"
+      # Create from YAML (for complex routines with multiple settings)
+      agents routines add weekly-report.yml
 
-  # One-shot routine: run Codex tomorrow at 2:30 PM, then never again
-  agents routines add hotfix-review --at "14:30" --agent codex --prompt "Review hotfix PR #42"
+      # List all routines and their next run times
+      agents routines list
 
-  # Create from a YAML file (for complex routines with multiple settings)
-  agents routines add weekly-report.yml
+      # Run a routine right now in the foreground (ignores schedule)
+      agents routines run daily-standup
 
-  # See all routines and their next run times
-  agents routines list
+      # Check whether the scheduler is running
+      agents routines status
+    `,
+        notes: `
+      A routine is a YAML file that schedules an agent invocation. It specifies:
+        - which agent to run (claude, codex, gemini, ...)
+        - when to run (cron schedule or one-shot time)
+        - what task to give the agent (the prompt)
+        - execution constraints (mode, effort, timeout)
 
-  # Check whether the scheduler is running
-  agents routines status
-
-  # Test a routine immediately in the foreground (ignores schedule)
-  agents routines run daily-standup
-`);
+      The background scheduler auto-starts the first time you add a routine.
+      Manage it with 'agents routines start|stop|status'.
+    `,
+    });
     routinesCmd
         .command('list')
         .description('See all scheduled jobs, when they run next, and their last execution status')
@@ -570,10 +573,10 @@ Examples:
         .option('-f, --follow', 'Stream log output in real time (like tail -f)')
         .action(async (options) => {
         if (options.follow) {
-            const { exec: execCb } = await import('child_process');
+            const { spawn } = await import('child_process');
             const { getDaemonDir } = await import('../lib/state.js');
             const logPath = path.join(getDaemonDir(), 'logs.jsonl');
-            const child = execCb(`tail -f "${logPath}"`);
+            const child = spawn('tail', ['-f', logPath]);
             child.stdout?.pipe(process.stdout);
             child.stderr?.pipe(process.stderr);
             child.on('exit', () => process.exit(0));