@phnx-labs/agents-cli 1.19.1 → 1.20.0

package/CHANGELOG.md

@@ -1,5 +1,72 @@
 # Changelog
 
+## 1.20.0
+
+**Routines (overdue detection + catchup)**
+
+- Detect routines whose most recent scheduled fire was missed (laptop off, daemon crashed, reboot). The daemon logs them on startup and pops a native desktop notification (`osascript` on macOS, `notify-send` on Linux).
+- `agents routines list` annotates overdue rows with `(overdue)` and prints a footer pointing at the catchup command.
+- New `agents routines catchup` command: lists overdue routines and fires them in the background under the scheduler. `--dry-run` lists without triggering.
+- `JobScheduler.schedule` now sets croner's `catch: true` and forwards `timezone` defensively, so a synchronous throw in one job's callback can't kill the whole cron loop.
+
+**Landing page (agents-cli.sh)**
+
+- Expanded the homepage with seven new sections: rotate accounts (`--rotate`), parallel teams (`agents teams`), browser automation, cross-agent session search, routines/cron, keychain secrets, and machine-to-machine sync (`agents drive`).
+- Rewrote meta description + lede to spell out the actual feature set (pin versions, swap models, rotate accounts, drive a browser, spawn parallel teams, schedule on cron) instead of just "same interface, on your machine."
+
+**Codex (commands-as-skills sync fix)**
+
+- Fix recurring "N commands new" prompt on `agents view codex` for Codex >= 0.117.0. `getActuallySyncedResources` now detects converted command-skills via the `agents_command` marker in `~/.codex/skills/<name>/SKILL.md` instead of only scanning the empty legacy `prompts/` directory.
+- Summary and selection prompts are version-aware: the static `COMMANDS_CAPABLE_AGENTS` gate is replaced by `supports(agent, 'commands', version)` so the "X commands" line only appears for versions that can actually take them.
+- Generalize `shouldInstallCommandAsSkill` beyond Codex — any agent where commands are gated off and skills are on (e.g. Grok) now gets the same automatic slash-command → skill conversion at install/sync time.
+
+**Grok Build (first-class support)**
+
+- Add `grok` as a first-class supported agent (AgentId + full registry entry using official `~/.grok/README.md` paths).
+- Implement proper binary resolution from `~/.grok/downloads/`.
+- Add `GROK_HOME` isolation to generated shims for true versioned config (skills, hooks, plugins, agents/, MCP, memory, etc.).
+- Extend `installVersion` to support Grok via its official installer script (`curl ... -s <version>`).
+- Update shims, exec templates, MCP path helpers, session helpers, unmanaged detection, and docs.
+- `agents add grok@<ver>`, `agents use grok@<ver>`, resource sync, and shims now work end-to-end for Grok Build.
+
+**Browser**
+
+- `agents browser start --record` convenience flag for one-shot recording sessions.
+- Auto-discover per-site `SKILL.md` on `browser start` so skills appear under the active task without manual wiring.
+- Auto-pick a Chromium-family browser when `--profile` is omitted; the limitation is surfaced in `--help` and the auto-pick error.
+- No more stacktraces when the daemon is down or CDP is unreachable — error paths print a single human-readable line.
+- Drop the Playwright `bundled-chromium` devdependency.
+
+**Secrets / Keychain**
+
+- `agents secrets list` and `agents run --secrets <bundle>` collapse to one Touch ID prompt per bundle instead of one per key. Previously every secret in a bundle would re-prompt for keychain unlock.
+
+**Sessions**
+
+- Extract `groupActiveSessions` into a tested helper for `--active` window grouping.
+- Propagate `windowid` from live-terminals into the active session record.
+
+**Copilot**
+
+- Emit `COPILOT_HOME` in the shim and exec env builder for versioned isolation.
+- Wire the Copilot session dir and `.jsonl` extension into the sessions reader.
+
+**OpenClaw**
+
+- Carry OpenClaw user data forward on version switch.
+
+**Teams**
+
+- Warn loudly when `--after` teammates reference a name whose watch process never launched, instead of silently sitting in pending state.
+
+**Plugins**
+
+- Use `'directory'` source discriminator (not `'local'`) for marketplace registration so plugins reload correctly.
+
+**Dependencies**
+
+- Bump `@inquirer/prompts` 7.10.1 → 8.5.1, `diff` 8.0.4 → 9.0.0, `tsx` 4.22.2 → 4.22.3, `actions/setup-node` 4.4.0 → 6.4.0.
+
 ## 1.18.6
 
 **Claude**

package/README.md

@@ -27,6 +27,8 @@
   <a href="https://github.com/openclaw/openclaw" title="OpenClaw"><img src="assets/harnesses/openclaw.svg" height="36" alt="OpenClaw" /></a>
   &nbsp;&nbsp;&nbsp;&nbsp;
   <a href="https://github.com/NousResearch/hermes-agent" title="Hermes Agent"><img src="assets/harnesses/hermes.png" height="32" alt="Hermes Agent" /></a>
+  &nbsp;&nbsp;&nbsp;&nbsp;
+  <a href="https://x.ai" title="Grok Build (xAI)"><strong>Grok</strong></a>
 </p>
 
 https://agents-cli.sh/demo.mp4
@@ -79,7 +81,7 @@ agents:
   codex: "0.116.0"
 ```
 
-Think `requirements.txt` for CLI coding agents, on steroids. A shim reads `agents.yaml` from the project root and routes `claude` / `codex` / `gemini` to the right version automatically. Each version gets its own isolated home -- switching backs up config and re-syncs resources.
+Think `requirements.txt` for CLI coding agents, on steroids. A shim reads `agents.yaml` from the project root and routes `claude` / `codex` / `gemini` / `grok` (and others) to the right version automatically. Each version gets its own isolated home -- switching backs up config and re-syncs resources.
 
 ```bash
 agents add claude@2.0.65     # Install a specific version
@@ -154,9 +156,9 @@ Supports plan (read-only) and edit modes, effort levels, JSON output for scripti
 agents run claude "review this diff" --acp --json
 ```
 
-`--acp` routes through the [Agent Client Protocol](https://agentclientprotocol.com/) so you get a unified event stream -- `agent_message_chunk`, `tool_call`, `plan_update`, `stop_reason` -- instead of writing a parser per CLI. File writes and shell commands flow through agents-cli, which means `--mode plan` becomes a real sandbox: the write RPC is denied, not just unused.
+`--acp` routes through the [Agent Client Protocol](https://github.com/zed-industries/agent-client-protocol) so you get a unified event stream -- `agent_message_chunk`, `tool_call`, `plan_update`, `stop_reason` -- instead of writing a parser per CLI. File writes and shell commands flow through agents-cli, which means `--mode plan` becomes a real sandbox: the write RPC is denied, not just unused.
 
-ACP adapters are documented for claude, codex, gemini, cursor, opencode, and openclaw. Other harnesses keep running on the direct-exec path.
+ACP adapters are documented for claude, codex, gemini, cursor, opencode, openclaw, and grok. Other harnesses keep running on the direct-exec path.
 
 ---
 
@@ -281,7 +283,7 @@ A workflow is a directory:
 ---
 name: Code Review
 description: Evidence-grounded PR review with file:line citations.
-model: claude-opus-4-7
+model: opus
 tools:
   - Read
   - Grep
@@ -296,15 +298,70 @@ Resolution is project > user > system: a `<repo>/.agents/workflows/<name>/` over
 
 ---
 
+## Plugins
+
+Bundle skills, commands, hooks, MCP servers, settings, and permissions under a single manifest. One source dir at `~/.agents/plugins/<name>/`, mirrored into every installed Claude / OpenClaw version automatically.
+
+```bash
+# Install from a git URL or local path
+agents plugins install hivemind@https://github.com/activeloopai/hivemind.git
+agents plugins install ./my-plugin
+
+# Apply to one agent (default version) or all supported
+agents plugins sync rush-toolkit claude
+agents plugins sync rush-toolkit
+```
+
+A plugin is a directory with a manifest:
+
+```
+~/.agents/plugins/my-plugin/
+  .claude-plugin/plugin.json       # required: { name, version, description }
+  skills/<name>/SKILL.md           # optional
+  commands/*.md                    # optional
+  hooks/hooks.json                 # optional — executable surface
+  .mcp.json                        # optional — executable surface
+  bin/, scripts/, settings.json    # optional — executable surface
+  permissions/                     # optional — executable surface
+```
+
+On sync, agents-cli copies the plugin into each version home's marketplace (`<home>/.claude/plugins/marketplaces/agents-cli/plugins/<name>/`), registers the synthetic marketplace, and flips `settings.json#enabledPlugins[<name>@agents-cli] = true` so Claude / OpenClaw load it.
+
+### Executable-surface gate
+
+Plugins that ship `hooks/`, `.mcp.json`, `bin/`, `scripts/`, `settings.json` (non-permissions), or `permissions/` can execute code on session events. agents-cli requires explicit consent before flipping `enabledPlugins`:
+
+```bash
+# Hooks-bearing plugins copy in but stay disabled by default
+agents plugins install hivemind@https://github.com/activeloopai/hivemind.git \
+  --allow-exec-surfaces
+
+# Same gate on re-sync (e.g., after upstream updates)
+agents plugins sync hivemind claude --allow-exec-surfaces
+```
+
+Skills, commands, and subagents are declarative and never trip the gate. The gate is per-plugin, per-install: consenting to hivemind doesn't grant blanket exec-surface trust to anything else.
+
+### Version portability
+
+Plugins live in the user repo (`~/.agents/plugins/`), not inside any single version home. Switching Claude via `agents use claude@<v>` re-syncs the plugin into the new version automatically — no re-install. New Claude versions added later pick it up on their first sync. Project-level `<repo>/.agents/plugins/<name>/` overrides a same-named user plugin (resolution is project > user > system, same as every other resource).
+
+---
+
 ## Browser
 
 Give agents access to a real browser — no relay extension, no cloud service, no Playwright getting blocked.
 
 ```bash
-# Create an isolated profile for automation
+# First run: omit --profile and we auto-pick the first installed Chromium-family
+# browser. macOS prefers Chrome > Brave > Edge > Chromium > Comet; Linux prefers
+# Chrome > Chromium > Brave > Edge; Windows prefers Edge (always preinstalled) >
+# Chrome > Brave. The auto-picked profile is saved as "default" for later runs.
+export AGENTS_BROWSER_TASK=$(agents browser start --url https://app.example.com)
+
+# Or pin a named profile to a specific browser (chrome, comet, brave, chromium,
+# edge, or custom) when you want isolation from "default".
 agents browser profiles create work --browser chrome
-
-# Start a task once, then bind it to this shell — every later command picks it up.
 # `start` writes the resolved name (e.g. `swift-crab-falcon-a3f92b1c`) to stdout
 # and human-friendly commentary to stderr, so $(...) capture stays clean.
 export AGENTS_BROWSER_TASK=$(agents browser start --profile work --url https://app.example.com)
@@ -384,6 +441,9 @@ agents browser profiles create cloud \
 
 ## Secrets
 
+> **Platform:** `agents secrets` requires macOS Keychain or Linux libsecret.
+> On Windows (non-WSL), use environment variables or a `.env` file instead.
+
 ```bash
 # API keys in Keychain, not in .env files.
 agents secrets create prod-stripe
@@ -414,7 +474,7 @@ agents secrets list                              # npm-tokens is already there;
 agents run claude "..." --secrets npm-tokens     # injects NPM_TOKEN automatically
 ```
 
-Under the hood, synced bundles route writes through a notarized helper app (`AgentsKeychain.app`) that holds the entitlement macOS requires for `kSecAttrSynchronizable`. Bundles created with `--no-icloud-sync` stay device-local.
+Under the hood, synced bundles route writes through a notarized helper app (`Agents CLI.app`) that holds the entitlement macOS requires for `kSecAttrSynchronizable`. Bundles created with `--no-icloud-sync` stay device-local.
 
 Bundle definitions sync via iCloud Keychain too — no `agents repo push` needed for secrets, no recreate step on each Mac. Nothing about secrets ever lives in plaintext on disk.
 
@@ -538,7 +598,7 @@ Every agent run, version install, browser launch, and secrets access is logged t
 }
 ```
 
-**What's logged:** Operation type, agent, version, timing, truncated prompts (first 200 chars), exit codes, errors. **What's NOT logged:** Full prompts, outputs, file contents, secret values (only bundle names).
+**What's logged:** Operation type, agent, version, timing, truncated prompts (first 200 chars), exit codes, errors, and secret bundle/key names with caller context. **What's NOT logged:** Full prompts, outputs, file contents, or secret values.
 
 **Permissions:** Logs directory is `0700` (owner-only), files are `0600`. Only you can read them.
 
@@ -603,7 +663,7 @@ Codex command sync is version-aware: Codex `0.116.x` and older receive slash com
 
 ### Why use `agents` instead of `claude` / `codex` / `gemini` directly?
 
-Claude Code, Codex CLI, and Gemini CLI each have their own config format, MCP setup, version management, and skill system. If you use more than one, you maintain N copies of everything. `agents` gives you one interface, one config source, and one place to pin versions -- plus features the individual CLIs don't ship: cross-agent pipelines, shared teams, unified session search, and project-pinned versions like `.nvmrc`.
+Claude Code, Codex CLI, Gemini CLI, Grok Build, and others each have their own config format, MCP setup, version management, and skill system. If you use more than one, you maintain N copies of everything. `agents` gives you one interface, one config source, and one place to pin versions -- plus features the individual CLIs don't ship: cross-agent pipelines, shared teams, unified session search, and project-pinned versions like `.nvmrc`.
 
 ### Is it free?
 

package/dist/commands/browser.js

@@ -1,12 +1,12 @@
 import * as fs from 'fs';
 import * as path from 'path';
-import { listProfiles, getProfile, createProfile, deleteProfile, getProfileRuntimeDir, extractConfiguredPort, findFreeProfilePort, getEndpointPresets, } from '../lib/browser/profiles.js';
+import { listProfiles, getProfile, createProfile, deleteProfile, ensureDefaultBrowserProfile, getProfileRuntimeDir, extractConfiguredPort, findFreeProfilePort, getEndpointPresets, } from '../lib/browser/profiles.js';
 import { findBrowserPath, getPortOccupant } from '../lib/browser/chrome.js';
 import { listProfileCacheDirs, removeProfileCache, listAllProfileSnapshots, } from '../lib/browser/runtime-state.js';
 import { DEFAULT_VIEWPORT } from '../lib/browser/devices.js';
 import { discoverBrowserWsUrl, verifyBrowserIdentity } from '../lib/browser/cdp.js';
 import { parseTargetFilter } from '../lib/browser/service.js';
-import { sendIPCRequest } from '../lib/browser/ipc.js';
+import { BrowserDaemonNotRunningError, formatBrowserDaemonNotRunningError, sendIPCRequest, } from '../lib/browser/ipc.js';
 import { browserTaskPicker } from './browser-picker.js';
 import { isInteractiveTerminal } from './utils.js';
 import { registerCommandGroups, setHelpSections } from '../lib/help.js';
@@ -59,8 +59,11 @@ export function registerBrowserCommand(program) {
       # Create a Chrome profile pointed at a CDP endpoint
       agents browser profiles create work --browser chrome --endpoint http://localhost:9222
 
-      # Start a session against a profile
-      agents browser start work
+      # Start a session — auto-picks the first installed Chromium-family browser
+      agents browser start
+
+      # Or pin to a specific profile
+      agents browser start --profile work
 
       # Drive the page
       agents browser navigate https://example.com
@@ -72,6 +75,12 @@ export function registerBrowserCommand(program) {
         notes: `
       Most agent workflows should use the 'browser' skill instead of raw subcommands.
       The skill wraps profile selection, snapshotting, and tunneling.
+
+      Browser support: Chromium-family only (Chrome, Comet, Chromium, Brave, Edge).
+      Safari and Firefox are not supported — they don't speak the Chrome DevTools
+      Protocol the way agents browser expects. On Windows, Edge is the default
+      because it's preinstalled. On macOS and Linux, Chrome is preferred when
+      installed; otherwise the first Chromium-family binary on disk wins.
     `,
     });
     registerProfilesCommands(browser);
@@ -346,7 +355,7 @@ function registerProfilesCommands(browser) {
             }
             else {
                 try {
-                    const { browser } = await discoverBrowserWsUrl(port);
+                    const { browser } = await discoverBrowserWsUrl(port, 'localhost', profile.name);
                     verifyBrowserIdentity(browser, profile.browser, port);
                     checks.push({
                         label: 'port',
@@ -437,39 +446,56 @@ function registerProfilesCommands(browser) {
 function registerTaskCommands(browser) {
     browser
         .command('start')
-        .description('Start a browser task with a profile')
-        .requiredOption('-p, --profile <name>', 'Browser profile to use')
+        .description('Start a browser task. Pass --profile <name>, or omit to auto-pick a Chromium-family browser already installed on this machine.')
+        .option('-p, --profile <name>', 'Browser profile to use (auto-picks from installed Chromium-family browsers if omitted)')
         .option(TASK_OPTION_FLAG, 'Task name (auto-generated if omitted)')
         .option('-e, --endpoint <name>', 'Endpoint preset (defaults to the profile\'s default)')
         .option('-u, --url <url>', 'Open URL in first tab')
+        .option('--no-skills', 'Skip auto-discovery of site-specific SKILL.md from ~/.agents/skills/browser/domain-skills/')
+        .option('--record', 'Start recording right after the tab opens (shorthand for `agents browser record start` as a follow-up)')
+        .option('--fps <n>', 'Recording frames per second (with --record; 1–30, default 5)', (v) => parseInt(v, 10))
+        .option('--duration <sec>', 'Recording duration cap in seconds (with --record; default 60)', (v) => parseInt(v, 10))
+        .option('--max-mb <mb>', 'Recording size cap in MB (with --record; default 25)', (v) => parseInt(v, 10))
         .action(async (opts) => {
+        let profileName = opts.profile;
+        if (!profileName) {
+            try {
+                const detected = await ensureDefaultBrowserProfile();
+                profileName = detected.name;
+            }
+            catch (err) {
+                console.error(err instanceof Error ? err.message : String(err));
+                process.exit(1);
+            }
+        }
         // Pre-check the profile locally so we fail fast with a helpful error
         // instead of round-tripping a generic "Profile not found" through the daemon.
-        const profile = await getProfile(opts.profile);
+        const profile = await getProfile(profileName);
         if (!profile) {
-            console.error(`Profile "${opts.profile}" not found.`);
+            console.error(`Profile "${profileName}" not found.`);
             const all = await listProfiles();
             if (all.length > 0) {
                 console.error(`Available profiles: ${all.map((p) => p.name).join(', ')}`);
             }
-            console.error(`Create one with: agents browser profiles create ${opts.profile} --browser <chrome|comet|chromium|brave|edge|custom>`);
+            console.error(`Create one with: agents browser profiles create ${profileName} --browser <chrome|comet|chromium|brave|edge|custom>`);
             process.exit(1);
         }
         // Pre-check the endpoint name too — same fail-fast rationale.
         if (opts.endpoint) {
             const presets = getEndpointPresets(profile);
             if (!presets[opts.endpoint]) {
-                console.error(`Endpoint "${opts.endpoint}" not found on profile "${opts.profile}". ` +
+                console.error(`Endpoint "${opts.endpoint}" not found on profile "${profileName}". ` +
                     `Available: ${Object.keys(presets).join(', ')}`);
                 process.exit(1);
             }
         }
         const response = await sendIPCRequest({
             action: 'start',
-            profile: opts.profile,
+            profile: profileName,
             taskName: opts.task,
             url: opts.url,
             endpoint: opts.endpoint,
+            skipDomainSkill: opts.skills === false,
         });
         if (!response.ok) {
             console.error(response.error);
@@ -488,6 +514,36 @@ function registerTaskCommands(browser) {
         }
         console.error(`Tip: export AGENTS_BROWSER_TASK=${response.task}`);
         console.error('Try: agents browser screenshot | agents browser console --level error');
+        // Surface the matched domain-skill (if any) so an agent driving the
+        // task picks up site-specific selectors and gotchas before it starts
+        // clicking. Header is recognizable so an agent parsing the stream can
+        // extract the skill content; suffix repeats the skill name for greps.
+        if (response.skill) {
+            console.error('');
+            console.error(`--- domain-skill: ${response.skill.name} (${response.skill.hostname}) ---`);
+            console.error(response.skill.content);
+            console.error(`--- end domain-skill: ${response.skill.name} ---`);
+        }
+        // --record convenience: fire record-start right after the tab opens so
+        // the user gets a single-command capture flow. Failures here are
+        // reported but don't fail the start — the task is already running.
+        if (opts.record) {
+            const recordResponse = await sendIPCRequest({
+                action: 'record-start',
+                task: response.task,
+                tabId: response.tabId,
+                fps: opts.fps,
+                duration: opts.duration,
+                maxMb: opts.maxMb,
+            });
+            if (!recordResponse.ok) {
+                console.error(`Recording failed to start: ${recordResponse.error}`);
+            }
+            else {
+                console.error(`Recording at ${recordResponse.fps} fps (cap ${recordResponse.durationCapSec}s / ${recordResponse.maxMb} MB) -> ${recordResponse.path}`);
+                console.error('Stop with: agents browser record stop');
+            }
+        }
     });
     browser
         .command('done')
@@ -798,10 +854,26 @@ function registerTaskCommands(browser) {
         .option('-p, --profile <name>', 'Filter by profile')
         .option('--json', 'Output machine-readable JSON')
         .action(async (opts) => {
-        const response = await sendIPCRequest({
-            action: 'status',
-            profile: opts.profile,
-        });
+        let response;
+        try {
+            response = await sendIPCRequest({
+                action: 'status',
+                profile: opts.profile,
+            }, { autoStartDaemon: false });
+        }
+        catch (err) {
+            if (err instanceof BrowserDaemonNotRunningError) {
+                const message = formatBrowserDaemonNotRunningError();
+                if (opts.json) {
+                    console.log(JSON.stringify({ ok: false, error: message }));
+                }
+                else {
+                    console.error(message);
+                }
+                process.exit(1);
+            }
+            throw err;
+        }
         if (!response.ok) {
             if (opts.json) {
                 console.log(JSON.stringify({ ok: false, error: response.error }));

package/dist/commands/cli.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `agents cli` — manage declarative CLI binary installs.
+ *
+ * Each entry under <repo>/cli/<name>.yaml declares a CLI tool the user wants on
+ * the host PATH (e.g. higgsfield, gh, glab). On a fresh machine `agents cli
+ * install` runs the first install method whose package manager is available
+ * (npm > brew > script > binary, in declared order).
+ *
+ * This is a sibling to `agents mcp` but one layer down: MCP wires servers into
+ * agent configs; CLI puts binaries on the user's normal PATH. CLI manifests are
+ * NOT copied into per-agent version homes — they are global to the user.
+ */
+import type { Command } from 'commander';
+export declare function registerCliCommands(program: Command): void;

package/dist/commands/cli.js

@@ -0,0 +1,244 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import chalk from 'chalk';
+import { confirm } from '@inquirer/prompts';
+import { listCliManifests, listCliStatus, resolveCliManifest, installCli, describeMethod, selectInstallMethod, isCliInstalled, } from '../lib/cli-resources.js';
+import { getUserAgentsDir } from '../lib/state.js';
+import { isPromptCancelled } from './utils.js';
+function userCliDir() {
+    return path.join(getUserAgentsDir(), 'cli');
+}
+/** Render the status table — one row per declared CLI. */
+function printStatus(rows) {
+    if (rows.length === 0) {
+        console.log(chalk.gray('No CLIs declared.'));
+        console.log(chalk.gray(`Create one with: agents cli add <name>`));
+        return;
+    }
+    const nameWidth = Math.max(4, ...rows.map((r) => r.manifest.name.length));
+    for (const row of rows) {
+        const status = row.installed
+            ? chalk.green('installed')
+            : chalk.yellow('missing');
+        const name = row.manifest.name.padEnd(nameWidth);
+        const source = chalk.gray(`[${row.manifest.source}]`);
+        const desc = row.manifest.description ? '  ' + chalk.gray(row.manifest.description) : '';
+        console.log(`  ${name}  ${status}  ${source}${desc}`);
+    }
+}
+export function registerCliCommands(program) {
+    const cliCmd = program
+        .command('cli')
+        .description('Declare and install host CLI binaries (gh, higgsfield, glab, ...)')
+        .addHelpText('after', `
+CLI manifests live in <repo>/cli/<name>.yaml and declare how to install a
+binary on the host. On a fresh machine, 'agents cli install' runs the first
+compatible method (npm > brew > script > binary) for every declared entry.
+
+Examples:
+  # See which declared CLIs are installed on this host
+  agents cli list
+
+  # Install everything that's missing
+  agents cli install
+
+  # Install one
+  agents cli install higgsfield
+
+  # Show the manifest detail
+  agents cli view higgsfield
+
+  # Exit 0 if all declared CLIs are installed (use in CI / setup scripts)
+  agents cli check
+
+When to use:
+  - After 'agents pull' on a new machine, to materialize host binaries
+  - In a team setup: commit cli/ entries so teammates get the same toolchain
+`);
+    cliCmd
+        .command('list')
+        .description('Show all declared CLIs and whether each is installed on this host')
+        .action(() => {
+        const { statuses, errors } = listCliStatus(process.cwd());
+        printStatus(statuses);
+        for (const err of errors) {
+            console.log(chalk.red(`  parse error: ${err.file}: ${err.reason}`));
+        }
+    });
+    cliCmd
+        .command('check')
+        .description('Exit 0 if every declared CLI is installed, 1 otherwise')
+        .action(() => {
+        const { statuses, errors } = listCliStatus(process.cwd());
+        const missing = statuses.filter((s) => !s.installed);
+        if (errors.length > 0) {
+            for (const err of errors) {
+                console.error(chalk.red(`parse error: ${err.file}: ${err.reason}`));
+            }
+            process.exit(1);
+        }
+        if (missing.length === 0) {
+            console.log(chalk.green(`All ${statuses.length} declared CLI(s) installed.`));
+            return;
+        }
+        console.log(chalk.yellow(`Missing: ${missing.map((s) => s.manifest.name).join(', ')}`));
+        process.exit(1);
+    });
+    cliCmd
+        .command('install [name]')
+        .description('Install one (by name) or all missing declared CLIs')
+        .option('-y, --yes', 'skip the confirmation prompt')
+        .option('--dry-run', 'print install commands without executing them')
+        .option('--force', 'reinstall even when the check command currently passes')
+        .action(async (nameArg, opts) => {
+        let targets;
+        if (nameArg) {
+            const manifest = resolveCliManifest(nameArg, process.cwd());
+            if (!manifest) {
+                console.error(chalk.red(`No CLI manifest named "${nameArg}".`));
+                console.error(chalk.gray(`Looked in: ${userCliDir()}`));
+                process.exit(1);
+            }
+            targets = [manifest];
+        }
+        else {
+            const { manifests, errors } = listCliManifests(process.cwd());
+            for (const err of errors) {
+                console.error(chalk.red(`parse error: ${err.file}: ${err.reason}`));
+            }
+            if (manifests.length === 0) {
+                console.log(chalk.gray('No CLIs declared. Nothing to install.'));
+                return;
+            }
+            targets = manifests;
+        }
+        // Filter out already-installed unless --force
+        const work = targets.filter((m) => opts.force || !isCliInstalled(m));
+        if (work.length === 0) {
+            console.log(chalk.green(`All ${targets.length} declared CLI(s) already installed.`));
+            return;
+        }
+        // Preview + confirm
+        console.log(chalk.bold('\nWill install:'));
+        for (const m of work) {
+            const method = selectInstallMethod(m);
+            const action = method ? describeMethod(method) : chalk.red('no compatible install method');
+            console.log(`  ${chalk.cyan(m.name.padEnd(20))} ${chalk.gray(action)}`);
+        }
+        console.log('');
+        if (!opts.yes && !opts.dryRun) {
+            try {
+                const proceed = await confirm({ message: 'Proceed?', default: true });
+                if (!proceed) {
+                    console.log(chalk.gray('Cancelled.'));
+                    return;
+                }
+            }
+            catch (err) {
+                if (isPromptCancelled(err)) {
+                    console.log(chalk.gray('Cancelled.'));
+                    return;
+                }
+                throw err;
+            }
+        }
+        // Execute
+        let failures = 0;
+        for (const m of work) {
+            console.log(chalk.bold(`\n→ ${m.name}`));
+            const result = installCli(m, { dryRun: opts.dryRun });
+            if (result.output)
+                console.log(chalk.gray(result.output));
+            if (result.error) {
+                console.log(chalk.red(`  ${result.error}`));
+                failures++;
+                continue;
+            }
+            if (opts.dryRun)
+                continue;
+            if (result.installed) {
+                console.log(chalk.green(`  installed (${describeMethod(result.method)})`));
+                if (m.postInstall) {
+                    console.log(chalk.gray(m.postInstall.trim().split('\n').map((l) => '  ' + l).join('\n')));
+                }
+            }
+            else {
+                console.log(chalk.yellow(`  install command ran but \`${m.check}\` still fails — check the output above`));
+                failures++;
+            }
+        }
+        if (failures > 0)
+            process.exit(1);
+    });
+    cliCmd
+        .command('view <name>')
+        .description('Show the parsed manifest detail')
+        .action((name) => {
+        const manifest = resolveCliManifest(name, process.cwd());
+        if (!manifest) {
+            console.error(chalk.red(`No CLI manifest named "${name}".`));
+            process.exit(1);
+        }
+        console.log(chalk.bold.cyan(manifest.name));
+        if (manifest.description)
+            console.log('  ' + chalk.gray(manifest.description));
+        if (manifest.homepage)
+            console.log('  ' + chalk.gray(manifest.homepage));
+        console.log('  ' + chalk.gray(`source: ${manifest.source}`));
+        console.log('  ' + chalk.gray(`file: ${manifest.path}`));
+        console.log('');
+        console.log(chalk.bold('  check'));
+        console.log('    ' + manifest.check);
+        console.log('');
+        console.log(chalk.bold('  install methods'));
+        for (const method of manifest.install) {
+            console.log('    ' + describeMethod(method));
+        }
+        if (manifest.postInstall) {
+            console.log('');
+            console.log(chalk.bold('  post_install'));
+            for (const line of manifest.postInstall.trim().split('\n')) {
+                console.log('    ' + line);
+            }
+        }
+        console.log('');
+        console.log(`  status: ${isCliInstalled(manifest) ? chalk.green('installed') : chalk.yellow('missing')}`);
+    });
+    cliCmd
+        .command('add <name>')
+        .description('Scaffold a new manifest at ~/.agents/cli/<name>.yaml')
+        .option('--npm <pkg>', 'declare an npm install method')
+        .option('--brew <formula>', 'declare a brew install method')
+        .option('--script <url>', 'declare a curl|sh install method')
+        .option('--description <text>', 'one-line description')
+        .option('--homepage <url>', 'project homepage')
+        .action((name, opts) => {
+        const dir = userCliDir();
+        fs.mkdirSync(dir, { recursive: true });
+        const target = path.join(dir, `${name}.yaml`);
+        if (fs.existsSync(target)) {
+            console.error(chalk.red(`Already exists: ${target}`));
+            process.exit(1);
+        }
+        const methods = [];
+        if (opts.npm)
+            methods.push(`  - npm: "${opts.npm}"`);
+        if (opts.brew)
+            methods.push(`  - brew: ${opts.brew}`);
+        if (opts.script)
+            methods.push(`  - script: ${opts.script}`);
+        if (methods.length === 0) {
+            methods.push(`  - npm: "${name}"`);
+        }
+        const lines = [
+            `name: ${name}`,
+            ...(opts.description ? [`description: ${opts.description}`] : []),
+            ...(opts.homepage ? [`homepage: ${opts.homepage}`] : []),
+            `check: ${name} --version`,
+            `install:`,
+            ...methods,
+        ];
+        fs.writeFileSync(target, lines.join('\n') + '\n');
+        console.log(chalk.green(`Created ${target}`));
+    });
+}