Command index
August 28, 2026 · View on GitHub
Every agents command and subcommand, with its argument names and one-line
description. Generated from the CLI's own command tree, so it never drifts from
what agents actually registers.
- Regenerate:
npm run gen:index(fromcli), or it is rebuilt on release. - Full option lists live in the machine-readable
command-index.json. agents <group> --helpshows the workflow-first help (examples + notes) for a group.
Excluded (same as agents --help): commands Commander marks hidden (e.g. remove/rm/purge
and internal subcommands), plus the deprecated aliases and tombstones registered inline in
src/index.ts (perms, exec, jobs, cron, check, resources, hq, _internal).
67 command groups · 548 commands.
accounts — Browse native logins and manage provider account bundles
agents accounts Browse native logins and manage provider account bundles
agents accounts add <name> Add a durable API key, setup token, or bearer token
agents accounts attach <account> <target> Attach a named account to a native installation or custom harness
agents accounts clear-default <agent> Return a harness to native login or balanced account selection
agents accounts detach <account> <target> Remove one account attachment
agents accounts label <source> [label] Label a native login by harness or <harness>@<version>; the label binds to the account identity, not the version
agents accounts list List credential accounts
agents accounts logout <target> Sign out a harness-native OAuth login. API-key / setup-token / bearer accounts use `accounts remove` instead.
agents accounts mint <harness> Mint a long-lived setup-token and seed it as a named account
agents accounts name <source> <name> Name a signed-in native installation without copying its OAuth credentials
agents accounts remove <name> Remove an account and its device-local credential
agents accounts rename <old> <new> Rename an account without changing its stable id
agents accounts set-default <agent> <name> Use this account for a harness when --account is omitted
agents accounts set-key <name> Rotate an account credential without changing its identity
agents accounts switch <harness> [account] Pick the default account for a harness
agents accounts sync <name> [device] Copy one provider account bundle to a worker device
agents accounts view <name> Show safe account metadata, custody, and attachments
add — Download and install agent CLI versions. Enables subsidized API usage through managed binaries.
agents add <specs...> Download and install agent CLI versions. Enables subsidized API usage through managed binaries.
artifacts — Publish agent-made artifacts (plans, reports, visuals) to a shareable link — managed if signed in, otherwise your Cloudflare R2.
agents artifacts Publish agent-made artifacts (plans, reports, visuals) to a shareable link — managed if signed in, otherwise your Cloudflare R2.
agents artifacts setup Provision (or join) the Cloudflare R2 + Worker endpoint that backs `agents artifacts share`.
agents artifacts share [file] Publish an HTML file to a shareable link — managed if signed in, otherwise your Cloudflare R2.
agents artifacts share analytics Show the Cloudflare Web Analytics status for this share endpoint.
agents artifacts share delete <targets...> Take down a published page (and by default its OG cover). Verifies the page 404s before reporting success. Nested alias: agents artifacts unshare.
agents artifacts share edit <target> Edit a published share's label or arbitrary metadata without republishing its body.
agents artifacts share join [baseUrl] Use an existing synced share endpoint and write token (no provisioning).
agents artifacts share list List the pages you've published to your share namespace (human table; --list-json for scripts).
agents artifacts share open <target> Open your own published page in the browser signed in as the owner, so the page's inline visibility control is live. Mints a one-time login ticket and appends it to the URL.
agents artifacts share revisions <target> Show the retained prior versions of a published slug, newest first (human table; --revisions-json for scripts).
agents artifacts share status Show the configured share endpoint and namespace.
agents artifacts share update Re-deploy the Worker script to the current template on an already-provisioned endpoint (idempotent).
agents artifacts share visibility <target> <level> Change an already-published page's visibility in place (public | unlisted | me | org). The slug/URL is preserved; the body is untouched, so no revision is created.
agents artifacts unshare <targets...> Alias of `agents artifacts share delete` — take down a published page (and by default its OG cover).
auth — Sign in to Phoenix ID — the account layer behind team spaces
agents auth Sign in to Phoenix ID — the account layer behind team spaces
agents auth login Sign in with the device-code flow
agents auth logout Clear this machine's session (no other device is affected)
agents auth mint <harness> Mint a long-lived setup-token and seed it as a named account
agents auth space Spaces — share work with teammates
agents auth space create <name> Create a space
agents auth space invite <email> Invite someone to a space
agents auth space list Spaces you belong to
agents auth space members [space] Who is in a space
agents auth space remove <email> Remove a member (or yourself) from a space
agents auth space role <email> <role> Change a member's role (owner only for admin)
agents auth whoami Show the signed-in account
browser — Launch and drive browser profiles via the Chrome DevTools Protocol. Power-tool for the browser skill.
agents browser Launch and drive browser profiles via the Chrome DevTools Protocol. Power-tool for the `browser` skill.
agents browser click [ref] Click an element by ref, or raw coordinates with --at X,Y
agents browser console Read console logs from a tab
agents browser devices List available device presets
agents browser done Complete a task and close its tabs (resolves from caller identity when --task is omitted)
agents browser download Set the download directory for a task (defaults to the profile's downloads dir)
agents browser errors Read page errors from a tab
agents browser evaluate [expression] Evaluate JavaScript in current tab
agents browser history Show recent browser task history
agents browser hover <ref> Hover over an element by ref
agents browser logs Read merged rush-app + rush-cli JSONL logs for a task
agents browser navigate [url] Navigate current tab to URL (creates a task and tab when none exist)
agents browser pdf [output] Export the current tab as PDF via CDP Page.printToPDF — auto-saved under sessions/<task>/ when [output] is omitted
agents browser press <key> Press a key (Enter, Tab, Escape, etc)
agents browser profiles Manage browser profiles
agents browser profiles claim [name] Move leftover central browser: profiles into this device's declaration file. Only profiles this machine can host are claimed; the rest stay central. Run on the machine that actually has the browser.
agents browser profiles create <name> Create a new browser profile on this device
agents browser profiles doctor <name> Diagnose a browser profile: where it is declared, binary, port, user-data-dir, onboarding state
agents browser profiles edit <name> Edit an existing profile in place (stays in the store it already lives in)
agents browser profiles list List all browser profiles and the devices declaring each one (WHERE)
agents browser profiles logins Show which login-gated services each profile has a live session for, the account signed in, and whether login creds are available in the profile's secrets bundle (reads cookie/username presence only, never decrypts).
agents browser profiles prune Remove dead profiles this device declares: browser not installed here, or never started
agents browser profiles remove <name> Remove a browser profile (drops YAML config + all cached runtime dirs)
agents browser profiles rename <from> <to> Rename a profile, moving its browser data with it (logins survive)
agents browser profiles seed Create a machine-local profile for each installed browser (named <browser>-local), so you can pick or use one instead of hand-crafting each. Idempotent — existing profiles are left untouched.
agents browser profiles show <name> Show profile details
agents browser profiles use [name] Pick the profile `agents browser start` uses when no --profile is passed. No name opens a picker on a TTY or prints the current default headlessly.
agents browser prune Close tabs for abandoned tasks — owning agent session exited, or idle past the window — and mark them done. The same reaper the daemon already runs every 5 minutes; use this to run it now.
agents browser ps List every browser/electron/tunnel process agents has tracked (alive or stale) — works without the daemon
agents browser record Record a video of the page
agents browser record start Start recording — auto-saved under sessions/<task>/recordings/. Bounded by --fps, --duration, --max-mb.
agents browser record stop Stop an in-progress recording
agents browser refs Get DOM refs for interactive elements
agents browser remote-control [state] Allow or deny other fleet machines driving THIS machine's browser over `browser --device` or `agents ssh …` (`agents browser` / `ag browser` / standalone `browser`). `on`/`off` to set (device-local, never synced); no argument prints the current value. Default off.
agents browser requests Read captured network requests. --format har emits a HAR 1.2 JSON document.
agents browser responsebody <url-pattern> Wait for and read a response body by URL pattern
agents browser screenshot Take a screenshot — auto-saved per task; --output only needed when you want a specific path
agents browser scroll Scroll the page by pixel amount (negatives scroll up/left)
agents browser sessions Browse a profile's captured screenshots, PDFs, recordings, and downloads, grouped by task
agents browser set Set browser emulation options
agents browser set device <device-name> Emulate a device (iPhone 14, iPad, MacBook Pro)
agents browser set viewport <width> <height> Set viewport size
agents browser show <url> Open a URL for a human to read: goes to browser.viewer (default: browser.profile), and binds no task
agents browser start Start a browser task. Pass --profile <name>; omit to use your configured default (set it with `agents browser use <name>` or `agents setup`). Page verbs (navigate/screenshot/…) create a task implicitly when none exists — start is for --profile/--url/--record/--title.
agents browser status Show running browser tasks
agents browser stop Stop a browser task and close its tabs; with --profile, detach the whole profile (close browser + drop cached connection); with --daemon, stop the browser daemon and clear a wedged socket
agents browser stream Keep one process and daemon IPC socket open; read NDJSON requests from stdin and write NDJSON responses
agents browser tab Manage tabs
agents browser tab add Open URL in new tab (becomes current)
agents browser tab close [tabId] Close tab(s) — omit tabId to close all
agents browser tab focus <tabId> Switch to tab (by ID, prefix, or URL substring)
agents browser tabs List tabs open for the current task
agents browser tasks List all browser tasks
agents browser type <ref> Type text into an element by ref
agents browser upload Upload file(s) — supports hidden file inputs, drag-drop targets, and OS chooser interception
agents browser use [name] Pick the profile `agents browser start` uses when no --profile is passed. No name opens a picker on a TTY or prints the current default headlessly.
agents browser wait Wait for a condition
agents browser waitdownload Wait for a download to complete
clis — Declare and install host CLI binaries (gh, higgsfield, glab, ...)
agents clis Declare and install host CLI binaries (gh, higgsfield, glab, ...)
agents clis add <name> Scaffold a new manifest at ~/.agents/clis/<name>.yaml
agents clis check Exit 0 if every declared CLI is installed, 1 otherwise
agents clis install [name] Install one (by name) or all missing declared CLIs
agents clis list Show all declared CLIs and whether each is installed on this host
agents clis view <name> Show the parsed manifest detail
commands — Extend agents with custom slash commands that ship behavior in markdown files
agents commands Extend agents with custom slash commands that ship behavior in markdown files
agents commands add [source] Install commands from a source (GitHub, local) or pick from central storage
agents commands list [agent] Show which slash commands are installed and which agent versions they are synced to
agents commands remove [name] Delete a command from agents (interactive picker if no name given)
agents commands view [name] Read the full content of a command file with markdown rendering
computer — Drive macOS apps via Accessibility, or a remote Windows device with --device — list, screenshot, click, type
agents computer Drive macOS apps via Accessibility, or a remote Windows device with --device — list, screenshot, click, type
agents computer apps List apps the daemon may drive (allow-listed + running)
agents computer ax-action Perform an arbitrary AX action (AXConfirm, AXCancel, AXRaise, ...) on an element
agents computer click Click an element (--id) or screen coordinate (--x --y)
agents computer describe Dump the accessibility tree (element ids feed click/type --id)
agents computer drag Drag from one coordinate to another
agents computer focus Set keyboard focus to an element (so type-text/key land there)
agents computer get-text Extract visible text from the app (or a subtree via --id)
agents computer key Send a key chord, e.g. "cmd+shift+s", "enter", "esc"
agents computer launch Launch an app by bundle id, path, or name
agents computer raise Bring an app (or a specific window) to the front — switches Spaces for fullscreen windows
agents computer reload Reload the allow-list policy (SIGHUP the local daemon) — or restart a remote Windows daemon with --device
agents computer right-click Right-click (context menu) an element or coordinate
agents computer run Autonomously drive an app from a natural-language task (embedded model loop over the computer verbs)
agents computer screenshot Capture a window (default: largest), enumerate windows (--list), or the whole display (--display)
agents computer scroll Scroll by a pixel delta at an element or coordinate
agents computer sessions Browse computer-driving history, grouped by run — one row per `agents computer` invocation
agents computer setup Install the helper — locally to /Applications/ (macOS), or to a remote Windows device with --device
agents computer start Activate the helper daemon — local launchd (macOS) or a remote Windows tunnel with --device
agents computer status Report install state, daemon state, and Accessibility trust — or a remote Windows daemon with --device
agents computer stop Deactivate the helper daemon — local launchd (macOS) or a remote Windows tunnel with --device
agents computer type Set a field value (--id) or paste at a coordinate (--x --y)
agents computer type-text Type an arbitrary unicode string into the focused field (focus first via click/focus)
agents computer wait Wait for a duration (--duration) or for an element (--id / --role/--label) to satisfy --until
config — Get, set, list, and unset run defaults, tier overrides, the projects root, device options, and spend caps.
agents config Get, set, list, and unset run defaults, tier overrides, the projects root, device options, and spend caps.
agents config budget Show spend caps and current spend-to-cap (issue #346)
agents config budget set <cap> <amount> Set a user-global cap. <cap> = per_run | per_day | per_project | per_agent.<agent> | on_exceed | require_confirm_over
agents config get <key> Get the current value of a config key
agents config list List configured config keys and their values
agents config set <key> <value> Set a config key
agents config unset <key> Unset a config key (restore default behavior)
daemon — The always-on daemon: secrets broker, browser IPC, watchdog, and the routines scheduler. Bare agents daemon shows status.
agents daemon The always-on daemon: secrets broker, browser IPC, watchdog, and the routines scheduler. Bare `agents daemon` shows status.
agents daemon disable Persist daemon.enabled: false — nothing auto-starts the daemon until re-enabled. Does not stop a running daemon.
agents daemon doctor One-shot health check: identity, duplicates, hosted services, scheduler. Non-zero exit on problems.
agents daemon enable Clear the daemon.enabled kill switch. Does not start the daemon by itself.
agents daemon funnel Manage Tailscale Funnel exposure for a fleet webhook receiver.
agents daemon funnel down <host> Disable Tailscale Funnel exposure for a public HTTPS port.
agents daemon funnel status <host> Show Tailscale Funnel status on a fleet host.
agents daemon funnel up <host> Expose a localhost webhook receiver through Tailscale Funnel.
agents daemon logs Read the daemon's own log (lifecycle + subsystem errors — not routine run output).
agents daemon reload Send SIGHUP to reload jobs and re-evaluate the scheduler.enabled gate, without a restart.
agents daemon restart Stop then start the daemon.
agents daemon services Every registered daemon service: live health, enabled state, and live enable/disable/restart.
agents daemon services disable <service> Disable a daemon service. Applies live for supervised services; a legacy service needs a restart.
agents daemon services enable <service> Enable a daemon service. Applies live for supervised services; a legacy service needs a restart.
agents daemon services list List every daemon service and whether it is enabled.
agents daemon services restart <service> Restart a supervised daemon service live, right now, outside its normal backoff schedule.
agents daemon start Start the daemon. Bypasses daemon.enabled — this is the deliberate override.
agents daemon status Identity (state/pid/uptime/binary), duplicate daemons, daemons running deleted code, and per-service health.
agents daemon stop Stop the daemon.
agents daemon webhooks Signed webhook receivers this box hosts as a supervised daemon service.
agents daemon webhooks add Declare a receiver on this box. Replaces any receiver already on the same port.
agents daemon webhooks list List the receivers declared for this box.
agents daemon webhooks remove <port> Stop hosting the receiver bound to this port.
devices — Registry of SSH device profiles (platform, user, address, auth), self-populated from Tailscale. Alias: fleet.
aliases: fleet
agents devices Registry of SSH device profiles (platform, user, address, auth), self-populated from Tailscale. Alias: fleet.
agents devices accounts Per device, one row per account: which harnesses share it, signed-in, quota, and ready. The identity lens on `agents devices harnesses`.
agents devices add <name> <target> Add a device manually (target is user@host or host).
agents devices apply Reconcile the fleet to a declared profile: install agents and sync config.
agents devices capture Snapshot the live environment (roster names, agents, browser, secret-bundle names, routines) into agents.yaml fleet:.
agents devices config [name] [key] [value...] Get, set, or unset a device’s settings (scheduler, agent cap, ssh overrides, auto-launch, notes). Bare opens an interactive settings menu (TTY) or prints the resolved config (piped). Per-device values live in the tracked devices/<name>/agents.yaml config: block; --fleet targets the fleet-wide defaults (central fleet.defaults.config) every device inherits unless it overrides the key.
agents devices describe <name> [text...] Show or set the one-line description of what a device is FOR ("gpu box — cuda 12.4"). Rendered as the tail column of `agents devices list` and synced fleet-wide. Same key as `agents devices config <name> description` — one store, two names.
agents devices harnesses Per device, one row per installed agent@version: account, signed-in, quota, and a single ready verdict. SSH-probes each online box.
agents devices ignore <name> Dismiss a node and record the decision in this box's device doc (fleet.ignored), unioned fleet-wide (also removes it locally).
agents devices ignored List dismissed tailscale nodes — what was dismissed, when, and on which machine.
agents devices lease Manage the disposable cloud boxes used by `agents run --lease`.
agents devices lease list List warm crabbox boxes you can reuse with `agents run --box <slug>`.
agents devices lease prune Stop expired, idle lease boxes that are holding your provider quota. Safe: never stops a box in active use.
agents devices lease setup One-time credential setup so `agents run --lease` works with no env var or flag.
agents devices lease stop <slug> Stop (release) a leased crabbox box now.
agents devices list List registered devices with platform, spec (cores/RAM/disk), live load/mem/disk headroom, role, and description.
agents devices login Log agent CLIs into fleet boxes over SSH: drive each box's device-code OAuth, scrape the URL + code, and surface every pending login in one local browser page. Default drives all codes at once; --interactive walks one box at a time (codes requested just-in-time so they don't expire).
agents devices pick Print the device automatic placement would choose for offloaded machine work (the suite, a build) — least-loaded, reachable, POSIX, never the box you are sitting at. Writes just the name to stdout so scripts can consume it.
agents devices ping Live auth health: complete a real request for every agent account across the fleet (unlike the cached "signed in" flag). Writes the shared auth-health cache read by `agents view` and `fleet status`.
agents devices ps List agent tasks dispatched to devices with `agents run --device <name> --no-follow`. Reconciles each still-`running` record against the remote before listing. View a log with `agents logs <id>`.
agents devices register <name> Register a discovered node and record the approval in this box's device doc (fleet.discovery), unioned fleet-wide.
agents devices remove <name> Remove a device from the registry.
agents devices render Render the registry to ssh_config. Prints to stdout, or use --write to update ~/.ssh/config.d/agents.
agents devices role [name] [role] Show or set what a device is for: worker (agents run here), personal (you sit here), or desktop (a headed always-on box — the release/credential home). Personal and desktop are never picked automatically. Marking any device worker makes `--device auto` an allowlist over the marked workers.
agents devices run <cmd...> Run a command on every online registered device. Offline devices are skipped. Alias surface: agents fleet run …
agents devices show <name> Show the full profile for one device.
agents devices snapshot One-process poll snapshot: install inventory + active sessions (optional feed/sync). Not the sync-status command — use `agents sync status` for drift.
agents devices status Fleet health at a glance: online/offline rollup, a NEEDS ATTENTION list (each with its fix command), and quiet per-device rows grouped by OS. Use --verbose for the full auth/CLI/sync grid.
agents devices stop <id> Terminate a running dispatched task from this machine (SIGTERM the remote process group; marks it failed/143).
agents devices sync Ingest `tailscale status --json` into device profiles. In a terminal, opens a checkbox to register/unregister nodes; with --yes, registers every non-ignored node.
agents devices unignore <name> Undo `ignore`: allow a node to be discovered and registered again.
agents devices update [version] Roll out agents-cli to every online registered device (`agents upgrade --yes` on each), then verify each box actually runs the new version. Offline devices are skipped.
doctor — Diagnose CLI availability, sync status, and resource divergence (optionally for a specific agent[@version]).
agents doctor [target] Diagnose CLI availability, sync status, and resource divergence (optionally for a specific agent[@version]).
events — Read the unified event stream (ops + activity + run dispatch)
agents events Read the unified event stream (ops + activity + run dispatch)
agents events audit Alias of `agents events --include runs` — dispatched-run outcomes
agents events audit list Alias of `agents events audit` / `agents events --include runs`
agents events audit verify Walk the legacy hash-chain file (pre-unification history only)
agents events emit Record events produced outside this process (reads JSONL on stdin)
agents events rotate Apply event retention and the storage ceiling immediately
agents events stats Show aggregate event statistics
feed — Operator inbox + agent status posts. Default is needs-you; agent progress = --filter updates
agents feed Operator inbox + agent status posts. Default is needs-you; agent progress = --filter updates
agents feed answer <attention-key> Atomically claim and deliver one answer to an open attention item
agents feed post <text...> Post a status update to the fleet activity stream (for agents)
agents feed watch Stream the canonical agent, attention, and activity projection as NDJSON
feedback — Open a pre-filled feedback Discussion or bug report
agents feedback [summary...] Open a pre-filled feedback Discussion or bug report
harness — Custom harnesses — name a (host CLI + model) combo and run it like a native agent type.
aliases: harnesses
agents harness Custom harnesses — name a (host CLI + model) combo and run it like a native agent type.
agents harness add [name] Create a custom harness from a host + model (or apply a built-in preset). Omit flags in a terminal for the interactive wizard.
agents harness edit <name> Edit an existing custom harness in place — model, endpoint, auth, version, description, fallback. Omit flags in a terminal for the interactive wizard.
agents harness fork [source] [name] Fork a native harness (claude, opencode, ...) or an existing custom one into a new named harness. Omit args in a terminal for the interactive wizard.
agents harness list List custom harnesses, addable presets, and native harnesses.
agents harness remove <name> Delete a custom harness (credentials stay on `agents accounts`; this only drops the named pin).
agents harness rename <old-name> <new-name> Rename a custom harness (updates forkedFrom lineage on any harness forked from it). Errors on a name collision.
agents harness view <name> Show one custom harness (host, model, provider, auth, path).
hooks — Automate workflows by running shell scripts in response to agent events
agents hooks Automate workflows by running shell scripts in response to agent events
agents hooks add [source] Install hooks from a source (GitHub, local) or pick from central storage
agents hooks list [agent] Show which hooks are installed and which events they respond to
agents hooks profile Per-hook timing + cache stats from recent invocations
agents hooks remove [name] Delete a hook from agents (interactive picker if no name given)
agents hooks view [name] Read the shell script content for a hook
humans — Inspect owner identity and notification channel config (humans.yaml)
agents humans Inspect owner identity and notification channel config (humans.yaml)
agents humans show Show config from humans.yaml
agents humans show owner Show the configured owner identity and notification channels
import — Import an existing unmanaged agent install into agents-cli
agents import <agent> Import an existing unmanaged agent install into agents-cli
insights — How work looks — behavioural report (default) or counter mix (mix, recipes)
agents insights How work looks — behavioural report (default) or counter mix (`mix`, recipes)
agents insights cost Roll up $ cost and duration across local agent sessions
agents insights mix [recipe] Counter recipes — harness/model mix, token ratios, resource frequency (sessions index + usage.db). Bare shows the board; pass a recipe id for one section.
agents insights output Productivity rollup — token burn vs shipped output (PRs, commits) across agents
agents insights perf Latency rollups from the disposable perf warehouse (hooks, commands, runs)
agents insights perf commands Slowest CLI command paths (command.end samples)
agents insights perf friction Sessions stuck repeatedly hitting the same guard block
agents insights perf hooks Per-hook timing + cache stats
agents insights perf run agent.run / perf.timing label rollups
agents insights query Raw usage-event query (usage.db)
inspect — Inspect one installed agent harness at one version (not a model), or a DotAgents repo — paths, capabilities, resources, and hook capable/on-disk/wired state.
agents inspect <target> Inspect one installed agent harness at one version (not a model), or a DotAgents repo — paths, capabilities, resources, and hook capable/on-disk/wired state.
install — Install a package: mcp:, skill:, plugin:, or GitHub (gh:user/repo) — one install path (Phase 5)
agents install <identifier> Install a package: mcp:, skill:, plugin:, or GitHub (gh:user/repo) — one install path (Phase 5)
logs — Show a run log, audit trail, or stats. Subcommands: audit, stats, rotate.
agents logs [id] Show a run log, audit trail, or stats. Subcommands: audit, stats, rotate.
agents logs audit Alias for `agents events --audit`
agents logs rotate Apply event retention and the storage ceiling immediately
agents logs stats Show aggregate audit statistics
mailboxes — Fleet comms — boxes, live cross-box traffic, threads, and routes across the agent mailbox spool
aliases: mailbox
agents mailboxes [id] Fleet comms — boxes, live cross-box traffic, threads, and routes across the agent mailbox spool
agents mailboxes prune Run a liveness sweep: archive pending messages in dead boxes and prune stale consumed mail.
mcp — Connect agents to external tools via Model Context Protocol servers
agents mcp Connect agents to external tools via Model Context Protocol servers
agents mcp add <name> [command_or_url...] Add an MCP server to the manifest (run "agents mcp register" afterward to apply)
agents mcp list [agent] Show which MCP servers are registered and which agent versions they are synced to
agents mcp remove [name] Unregister an MCP server from agents (interactive picker if no name given)
agents mcp trust Trust this project so its .agents/mcp/ servers may be registered and spawned
agents mcp untrust Revoke MCP trust for this project (its .agents/mcp/ servers stop auto-applying)
agents mcp view [name] Show MCP server configuration (command, scope, registered agents)
memory — Manage portable agent memory (facts, preferences, project knowledge)
agents memory Manage portable agent memory (facts, preferences, project knowledge)
agents memory add <name> Add or overwrite a user-layer memory fact
agents memory list List memory facts from project, user, and system layers
agents memory remove <name> Remove a user-layer memory fact
agents memory view <name> Print a memory fact (winning layer)
menubar — Manage AGI Menu (running sessions, agents awaiting input, routines)
agents menubar Manage AGI Menu (running sessions, agents awaiting input, routines)
agents menubar disable Stop and remove AGI Menu (stays off across upgrades)
agents menubar doctor Diagnose AGI Menu: install path, version skew, signing identity, stale process
agents menubar enable Install and start AGI Menu (launches at login)
agents menubar setup Configure AGI Menu end-to-end: one instance, started at login
agents menubar status Show whether AGI Menu is installed and running
message — Send a message to a running or parked agent (mailbox / PTY-select / resume by runtime).
agents message <target> <text> Send a message to a running or parked agent (mailbox / PTY-select / resume by runtime).
models — Show the cost-tier map (cheap|default|best|ultra) for installed harnesses; pin overrides with tier set.
agents models [agentSpec] Show the cost-tier map (cheap|default|best|ultra) for installed harnesses; pin overrides with `tier set`.
agents models set [selector] Set the default model/mode an agent version uses for `agents run`
agents models tier Override which model a cost tier resolves to (per harness, or per agent@version).
agents models tier clear <selector> [tier] Clear one tier (or all tiers) back to the auto guess.
agents models tier list List all configured tier overrides.
agents models tier set <selector> <tier> <model> Pin a tier to a model. selector: <agent> or <agent>@<version> (e.g. kimi, kimi@0.19.2).
modes — Show which permission modes (--mode plan|edit|auto|skip) a harness supports for agents run / teams add
agents modes [agentSpec] Show which permission modes (--mode plan|edit|auto|skip) a harness supports for agents run / teams add
monitors — Durable event-triggered watchers: watch a source, detect a change, fire an action. The daemon auto-starts on first add unless daemon.enabled is false.
agents monitors Durable event-triggered watchers: watch a source, detect a change, fire an action. The daemon auto-starts on first add unless daemon.enabled is false.
agents monitors add [nameOrPath] Create a monitor from inline flags or a YAML file. Auto-starts the daemon unless daemon.enabled is false.
agents monitors device [name] View or (re)pin the OWNER device — the single machine that evaluates + fires (exactly-once).
agents monitors edit [name] Open a monitor’s YAML in $EDITOR.
agents monitors list See all monitors across the fleet: source, condition, action, owner, last fire, and the box each lives on.
agents monitors logs [name] Show the latest action run’s status + report. --run for a specific run, --full for raw stdout.
agents monitors pause [name] Temporarily disable a monitor. Stops watching until resumed.
agents monitors remove [name] Delete a monitor. Stops watching; past fire history remains on disk.
agents monitors resume [name] Re-enable a paused monitor so the daemon watches it again.
agents monitors runs [name] See a monitor’s fire history: when it fired, the action, and the outcome.
agents monitors test [name] DRY-RUN: evaluate the source once and print the emitted event + whether it would fire. No action is taken.
agents monitors view [name] Show a monitor’s full YAML config plus its current watched-state and recent fires.
notify — [DEPRECATED] Deliver to the owner (alias of send --to owner). Use "agents feed post" for new code.
agents notify [text] [DEPRECATED] Deliver to the owner (alias of send --to owner). Use "agents feed post" for new code.
open — Resume a session from an agents:// deep link, or register/unregister/status the OS URL-scheme handler.
agents open [url] Resume a session from an agents:// deep link, or register/unregister/status the OS URL-scheme handler.
agents open register Register the agents:// URL scheme with the OS so artifact links resume sessions (idempotent).
agents open status Report whether the agents:// URL scheme handler is registered.
agents open unregister Remove the agents:// URL scheme handler.
permissions — Control what agents can access with allow/deny rules for bash, tools, and filesystem
agents permissions Control what agents can access with allow/deny rules for bash, tools, and filesystem
agents permissions add [source] Import permissions from an agent config, YAML, or GitHub, then apply to versions
agents permissions list [agent] Show permission sets in storage or active permissions for an agent version
agents permissions remove [name] Delete a permission set from ~/.agents/permissions/ (interactive picker if no name given)
agents permissions view [name] Read the allow and deny rules for a stored permission set
plugins — Bundle skills, hooks, and permissions into distributable packages
agents plugins Bundle skills, hooks, and permissions into distributable packages
agents plugins info [name] Show plugin metadata, resources, and installation status across agent versions
agents plugins install <spec> Install a plugin from a git URL or local path (format: name@source or source)
agents plugins list Show plugins in a table with sync status across agent versions
agents plugins marketplaces List plugin marketplaces — one per DotAgents repo with a plugins/ directory
agents plugins marketplaces add [target] Redirects to 'agents repo add' — marketplaces follow repos
agents plugins marketplaces disable [target] Redirects to 'agents repo disable' — marketplaces follow repos
agents plugins marketplaces enable [target] Redirects to 'agents repo enable' — marketplaces follow repos
agents plugins marketplaces install [target] Redirects to 'agents repo install' — marketplaces follow repos
agents plugins marketplaces remove [target] Redirects to 'agents repo remove' — marketplaces follow repos
agents plugins marketplaces rm [target] Redirects to 'agents repo rm' — marketplaces follow repos
agents plugins remove [name] Unsync a plugin from all agent versions and optionally delete its source directory
agents plugins update [name] Re-pull a plugin from its original source and re-sync to all versions
projects — Named multi-repo projects with a progress rollup.
agents projects Named multi-repo projects with a progress rollup.
agents projects add <name> Define a project. Infers root and repo from the current git repo when not given.
agents projects edit <name> Open the project YAML in $EDITOR (it is hand-editable regardless).
agents projects for-cwd [cwd] Resolve a directory to its defined project name (root or a repos[].path/subpath match). Defaults to the current directory.
agents projects import Import project definitions from Linear (via the `linear` CLI).
agents projects link <name> Attach an external tracker to a project definition (writes linear.projectId + name into the YAML; re-run to pick up a Linear rename).
agents projects list List defined projects (definitions only by default; no session scan).
agents projects pull <name> Fast-forward every fleet checkout of a named project to its remote default branch.
agents projects remove <name> Remove a project definition. Never touches the repo.
agents projects save Create or update one project from a complete ProjectDef JSON object on stdin.
agents projects set <name> Change one field on a project definition, preserving everything else.
agents projects status [name] Progress card for every project across the whole fleet, or one named project (alias: view). Named form also prints every milestone and the stored definition.
prune — Uninstall agent CLI versions. Moves version data to trash for recovery.
agents prune <specs...> Uninstall agent CLI versions. Moves version data to trash for recovery.
agents prune cleanup [target] Remove orphan resources, old versions, or routine runs
pty — Drive interactive terminal programs from AI agents. Use this for REPLs, TUIs, or anything needing a real terminal.
agents pty Drive interactive terminal programs from AI agents. Use this for REPLs, TUIs, or anything needing a real terminal.
agents pty exec <id> <command> Send a command to a PTY session. Returns immediately (non-blocking). Use screen or read to see output.
agents pty list List all active PTY sessions (running or idle).
agents pty read <id> Read raw output from the PTY (includes ANSI codes). Use screen for clean text instead.
agents pty resize <id> Resize a PTY session
agents pty screen <id> Render the terminal screen as clean text (no ANSI codes). This is what a human sees looking at the terminal.
agents pty server Manage the PTY sidecar server (auto-starts on first use, usually you do not need this).
agents pty server start Start the PTY server manually (auto-starts on first pty command anyway).
agents pty server status Check if the PTY server is running and how many sessions are active.
agents pty server stop Stop the PTY server and kill all active sessions.
agents pty signal <id> [signal] Send a POSIX signal to the running process. Defaults to INT (Ctrl-C).
agents pty start Start a new PTY session and return its ID. The session persists until you stop it.
agents pty stop <id> Stop a PTY session and clean up. The session ID becomes invalid.
agents pty write <id> <input> Send keystrokes to the PTY (like typing into the terminal). Processes escape sequences by default.
registry — Manage package registries
agents registry Manage package registries
agents registry add <type> <name> <url> Add a registry (type: mcp or skill)
agents registry config <type> [name] Configure a registry
agents registry disable <type> [name] Disable a registry
agents registry enable <type> [name] Enable a registry
agents registry list List configured registries
agents registry remove <type> [name] Remove a registry
repos — Manage extra DotAgent repos alongside ~/.agents/ (for private or team skills).
aliases: repo
agents repos Manage extra DotAgent repos alongside ~/.agents/ (for private or team skills).
agents repos add <source> Register an existing local repo or clone a remote repo into ~/.agents-<alias>/
agents repos disable <alias> Stop merging this repo during sync without deleting the clone
agents repos enable <alias> Re-enable a previously disabled extra repo
agents repos init [target] Create a user-owned repo from a template and register it as an extra
agents repos list [alias] Show all repos with resource-level sync (skills/commands/plugins to pull or push) and local changes.
agents repos pull [alias] [url] Pull updates and reconcile synced device decisions. Aliases: "system" (~/.agents/.system/), "user" (~/.agents/), or any registered extra. No arg pulls all. Pass a git URL to git-back a not-yet-cloned user repo: "agents repo pull user <url>".
agents repos push [alias] Commit and push the user repo or a user-owned extra. Refuses to push the system repo.
agents repos remove <alias> Unregister an extra repo. Managed clones are deleted; external paths are kept.
agents repos sync <alias> Git-sync a repo: pull (and push for user/extras). Aliases: "system", "user", or a registered extra.
agents repos view [name] Show one repo's contents: git state and per-kind resource counts. Omit the name for an interactive picker.
restore — Restore a soft-deleted agent version (e.g. "codex@0.141.0") removed via prune/remove
agents restore <target> Restore a soft-deleted agent version (e.g. "codex@0.141.0") removed via prune/remove
route — Named routers -- reusable, task-typed allowlists of harnesses x models/tiers x linked accounts.
agents route Named routers -- reusable, task-typed allowlists of harnesses x models/tiers x linked accounts.
agents route allow <name> <harness> <models...> Set (replace) a harness's eligible model/tier allowlist under a router.
agents route create <name> Create a named router with an initial harness + tier allowlist.
agents route link-account <name> <harness> <account> Link a durable credential account to a harness under a router.
agents route list List every configured router.
agents route remove <name> Remove a router.
agents route show <name> Show a router's harness/model/account allowlist, weights, and hijack flag.
agents route unlink-account <name> <harness> <account> Unlink a durable credential account from a harness under a router.
routines — Schedule agents to run on a cron schedule or at a specific time. The daemon starts at install/upgrade and on setup when daemon.enabled is not false; routines add also ensures it is running.
agents routines Schedule agents to run on a cron schedule or at a specific time. The daemon starts at install/upgrade and on setup when daemon.enabled is not false; routines add also ensures it is running.
agents routines add [nameOrPath] Create a new routine from a YAML file or inline flags. Starts the scheduler automatically if it is not already running.
agents routines catchup Run any routines that missed their last scheduled fire on demand. The daemon already does this every 5 minutes — use this to force a pass now. Detached: runs in the background under the scheduler.
agents routines devices [name] View or change the devices where a routine is enabled. Without flags, opens an interactive picker (requires a TTY).
agents routines disable [name] Disable a routine. Stops scheduling future runs; turn it back on with: agents routines enable <name>.
agents routines doctor [name] Check a routine's execution-context and harness readiness. Bare or --all checks every routine; --fix applies safe activation repairs (activate a now-ready paused routine; pause a broken active one).
agents routines edit [name] Edit a prefilled routine transactionally; invalid YAML never replaces the live definition.
agents routines enable [name] Enable a routine so the daemon schedules it. Also materialises a project routine (from the current project or a registered one) on first enable — one step, no separate opt-in.
agents routines list See all scheduled jobs, when they run next, and their last execution status
agents routines logs [name] Show a run’s concise summary — status + extracted report. --full for the raw stdout stream; --run for a specific past run.
agents routines prune Remove expired one-shot routines that already fired and still have a user-layer YAML file.
agents routines remove [name] Delete a routine. Stops scheduling future runs; past execution logs remain on disk.
agents routines report [name] Show the extracted report from the most recent execution. Reports are parsed from agent output on completion.
agents routines run [name] Execute a routine right now in the foreground. Ignores the schedule; useful for testing before enabling.
agents routines runs [name] See execution history: run IDs, completion status, and start times (up to last 10 runs)
agents routines scheduler-logs Read scheduler log output (for debugging why a routine did not fire). Use --follow to stream.
agents routines start Start the background scheduler. Usually unnecessary — it auto-starts when you add your first routine.
agents routines stats [name] Duration + outcome rollup per job: run count, failed, missed, avg/p50/p95 duration
agents routines status Show scheduler status, enabled routines, and when each one fires next.
agents routines stop Stop the background scheduler. Routines will not fire until you start it again.
agents routines sync [path] Refresh materialised project routines from their .agents/routines/*.yml sources. Definition-only — never changes what is enabled. With no path, refreshes every project you have enabled a routine from. Also runs automatically on daemon reload (SIGHUP).
agents routines view [name] Show the full YAML configuration for a routine
agents routines webhook Fire trigger-based routines from a single webhook payload (read from --file or stdin). One-shot: matches and fires, then exits.
rules — Control agent behavior by installing persistent instructions and rules
agents rules Control agent behavior by installing persistent instructions and rules
agents rules add [source] Install rule files from a source (GitHub, local path) or pick from central storage
agents rules list [agent] Show which rule files are installed. Pass agent@version to see a specific version.
agents rules remove [agent] Delete user-level rule files for an agent or version
agents rules switch <target> Choose the active rule preset for an agent version (persists in agents.yaml)
agents rules view [agent] Read the full content of a rule file with markdown rendering
run — Execute an agent. Pass a prompt for headless runs; omit it to launch the agent interactively. With --broadcast, run the same prompt/task across an agent × model matrix.
agents run [agent] [prompt] Execute an agent. Pass a prompt for headless runs; omit it to launch the agent interactively. With --broadcast, run the same prompt/task across an agent × model matrix.
search — Find packages (MCP servers, skills) across configured registries
agents search <query> Find packages (MCP servers, skills) across configured registries
secrets — Named bundles of env variables backed by macOS Keychain (device-local, biometry-gated). Inject into agents via agents run --secrets <name>.
agents secrets Named bundles of env variables backed by macOS Keychain (device-local, biometry-gated). Inject into agents via `agents run --secrets <name>`.
agents secrets activity [name] Show the recent value-free usage timeline (created / imported / exported / viewed / accessed / unlocked) for one bundle, or across all bundles
agents secrets add [bundle] [key] Add a variable to a bundle. Defaults to keychain-backed; pass --value for literal, --env/--file/--exec for refs.
agents secrets create [name] Create an empty bundle. Name it after what it holds — a website by domain (stripe.com, openai.ai), a desktop app by its binary suffix (slack.app, photoshop.exe) — and pass --description.
agents secrets delete [name] Delete a bundle and purge all its keychain items (use --keep-secrets to retain them).
agents secrets describe <name> [text...] Update the description of a bundle. Pass --clear to remove it.
agents secrets exec <bundle> [command...] Run a command with the bundle's secrets injected into the environment (use --device to resolve the bundle from a remote machine, ephemerally)
agents secrets export [bundle] Move a bundle without exposing it: push to remote machine(s) over SSH with --device, to a 1Password vault with --to-1password, or to an encrypted file with --to-file.
agents secrets generate [length] Generate a random password
agents secrets get <item> [key] Print one raw keychain item by name, for shell hooks/automation. Cross-platform. Bundle values are never printed — run commands under `agents secrets exec` instead.
agents secrets import [bundle] Import keys into a bundle from a .env file, a 1Password vault, or legacy iCloud Keychain bundles. The bundle is created if it does not exist. Values are stored in the bundle's backend (keychain by default).
agents secrets import-keyring Migrate agents-cli secrets from the OS keyring / Credential Manager into the encrypted file store (headless-safe). Dry-run by default.
agents secrets list [query] List configured secrets bundles, optionally filtered (use --device/--devices for other machines over SSH)
agents secrets lock [names...] Wipe bundles from the secrets-agent (forces Touch ID again next read). Default: all.
agents secrets mcp Run a stdio MCP server exposing get_secret(bundle, key) — hand credentials to an MCP-speaking agent by name at call time, never through the child process environment
agents secrets migrate Interactively migrate legacy YAML bundles into Keychain
agents secrets migrate-acl Refresh legacy keychain ACLs and re-home items stranded in a stale access group. Dry-run by default.
agents secrets openclaw-keychain Migrate supported OpenClaw credentials from plaintext config to macOS Keychain-backed SecretRefs
agents secrets openclaw-keychain migrate [config] Rewrite supported OpenClaw plaintext secrets to exec SecretRefs backed by macOS Keychain
agents secrets openclaw-keychain resolve OpenClaw exec SecretRef resolver for Keychain service ids
agents secrets policy <bundle> [policy] Show or set a bundle's prompt policy: hold (default, ask once per hold window — secrets.agent.holdMs, 7d by default), always (ask every time), or never (silent, NO biometry ACL). 'daily'/'session' are accepted aliases for 'hold'.
agents secrets pull [name] Decrypt a remote bundle from api.prix.dev and restore it into the local keychain.
agents secrets push [name] Encrypt a local bundle and upload it to api.prix.dev (replaces iCloud Keychain sync).
agents secrets rekey Replace enumerable keychain service names with opaque HMAC-hashed names (one-time; idempotent). macOS only.
agents secrets remote-list List bundles currently stored on api.prix.dev for this account.
agents secrets remove [bundle] [key] Remove a key from the bundle. Purges the keychain item if the ref was keychain:. Use --keep-secret to retain it.
agents secrets rename <old> <new> Rename a bundle. Moves the metadata and every keychain-backed value to the new name.
agents secrets rotate [bundle] [key] Rotate an existing keychain-backed secret (replaces the value, preserves metadata unless overridden).
agents secrets rotate-passphrase Re-key the encrypted file store under a new machine-local passphrase (atomic, headless-safe). Dry-run by default.
agents secrets set <item> Store a raw keychain item by name (for shell hooks/automation). Cross-platform; no bundle required.
agents secrets start Bring up the always-on daemon that hosts the secrets broker (macOS). Survives heavy load; reads connect instantly.
agents secrets status Show which bundles the secrets-agent currently holds and when they lock.
agents secrets stop Lock all bundles and retire any legacy standalone service. The always-on daemon (which hosts the broker) is left running.
agents secrets unlock [names...] Hold a bundle in the secrets-agent after one Touch ID, so concurrent runs read it without re-prompting (macOS). With --device, unlock FILE-backed bundle(s) on a remote (the passphrase prompt surfaces over the SSH TTY); keychain/biometry bundles are GUI-only and can't be remote-unlocked.
agents secrets vault Unlock or lock the age-encrypted synced-secrets file (~/.agents/vault.age)
agents secrets vault lock Forget the cached synced-secrets key
agents secrets vault unlock Unlock synced secrets for this shell session
agents secrets view [name] Show a bundle. Keychain values are masked by default — pass --reveal to see them.
send — Deliver a message through a channel provider (imessage, slack, desktop, mailbox, …). Prefer --text/--to flags.
agents send [text] Deliver a message through a channel provider (imessage, slack, desktop, mailbox, …). Prefer --text/--to flags.
sessions — Find, browse, and read agent conversation transcripts. Live roster: agents sessions --active.
agents sessions [query] Find, browse, and read agent conversation transcripts. Live roster: `agents sessions --active`.
agents sessions backfill Populate derived session data explicitly.
agents sessions backfill resources Derive historical skill/slash-command usage once into the local SQLite index.
agents sessions backfill tools Parse historical tool calls once into the local SQLite index.
agents sessions bookmark [ids...] Bookmark sessions so they are easy to find again — list them with --bookmarks, or `b` in the browser.
agents sessions detach <id> Send a live agent to the background — stop its terminal, keep it working headless
agents sessions export [selectors...] Bundle sessions (by id, query, or the parent selection flags like --since/-a) into a portable archive.
agents sessions fork <session> Branch a session into a new same-harness sibling, seeded with a recap so it continues the work. The original is untouched.
agents sessions import [bundle] Restore an export bundle (file, - for stdin, or --from-host <h>) into the local session store, deduping against what you already have.
agents sessions inject <sessionId> <text> Deliver text (+ Enter) into the terminal a running session lives in — nudge a stalled agent.
agents sessions insights How work looks — behavioural report (default) or counter mix (`mix`, recipes)
agents sessions insights mix [recipe] Counter recipes — harness/model mix, token ratios, resource frequency (sessions index + usage.db). Bare shows the board; pass a recipe id for one section.
agents sessions insights query Raw usage-event query (usage.db)
agents sessions migrate [session-id] Relocate a running session onto another machine (fleet worker, device, or ephemeral box), then stop the source here.
agents sessions migrations Show the migration ledger — sessions handed off to/from other machines.
agents sessions optimize Compact the session search index (FTS5), reclaiming bloat from repeated re-indexing
agents sessions preview <id> Show one rich session card without rendering the full transcript
agents sessions render <selectors...> Render one or more sessions as readable, redacted Markdown for review or sharing.
agents sessions resume [query] [prompt] Resume a session by id (strict), or multi-select history into terminal tabs/splits.
agents sessions share <session> Publish one session as a redacted, self-contained web page and print the link.
agents sessions stats Which skills/commands you actually invoke, and which installed ones are dead weight.
agents sessions stop <id> Stop a live agent outright — end its process and tear down its tmux/mux session
agents sessions tail [sessionId] Stream compact live lines from a session file as events are written. Long-running: Ctrl+C to stop. Claude and Codex only.
agents sessions trace <selectors...> Visualize a session as a trajectory — a tool-call timeline you can read at a glance. Opens a visual for a person; prints a compact trajectory for an agent.
agents sessions watch Stream canonical live and recoverable session row changes as NDJSON
setup — Set up agents-cli, or re-open the capability onboarding hub.
agents setup Set up agents-cli, or re-open the capability onboarding hub.
agents setup accounts Mint a Claude setup-token into a named account (unattended usage/probe).
agents setup alias Create shorthand binaries that expand to `agents <subcommand>`
agents setup alias add <name> [expansion...] Create an alias shim. If expansion is omitted, defaults to <name>.
agents setup alias list Show installed aliases
agents setup alias remove <name> Delete an alias shim
agents setup beta Enable or disable preview features like factory.
agents setup beta disable <features...> Disable one or more beta features.
agents setup beta enable <features...> Enable one or more beta features.
agents setup beta list Show available beta features and whether they are enabled.
agents setup browser Set up `agents browser` — detect an installed browser and create the default profile.
agents setup computer Set up `agents computer` (macOS) — install the signed helper and grant control permissions.
agents setup fleet Set up `agents fleet` — discover Tailscale devices, choose auth, render SSH config, and test connectivity.
agents setup mine White-label the CLI — mint your own personally-named binary (e.g. `jack`).
agents setup mine init <name> Mint your own branded CLI that runs every agents verb under <name>
agents setup mine list Show your brands and what each has turned off
agents setup mine remove <name> Remove a brand (its shim + config)
agents setup mine toggle <name> Enable/disable features for a brand
agents setup secrets Configure `agents secrets` defaults and optionally import existing secrets.
agents setup status Show setup readiness for core, browser, computer, secrets, accounts, fleet, share, watchdog, and preferences.
agents setup watchdog Choose the devices where the daemon watchdog pass runs.
skills — Add domain-specific capabilities to agents via packaged SKILL.md files
agents skills Add domain-specific capabilities to agents via packaged SKILL.md files
agents skills add [source] Install skills from a source (GitHub, local) or pick from central storage
agents skills list [agent] Show which skills are installed and which agent versions they are synced to
agents skills remove [name] Delete a skill from central storage (interactive picker if no name given)
agents skills view [name] Read skill metadata (name, description, rules count)
ssh — Connect to a registered device. Preflights reachability, picks the right shell, and authenticates (key or password-from-bundle).
agents ssh <name> [cmd...] Connect to a registered device. Preflights reachability, picks the right shell, and authenticates (key or password-from-bundle).
subagents — Install specialized agent definitions that parent agents can spawn for focused tasks
agents subagents Install specialized agent definitions that parent agents can spawn for focused tasks
agents subagents add <source> Install subagents from a source (GitHub, local path) and sync to agent versions
agents subagents list Show subagents in a table with sync status across agent versions
agents subagents remove [name] Delete a subagent from central storage and unsync from all agent versions
agents subagents view [name] Show details for a specific subagent (use "list" to see all)
sync — Make this machine current, or sync resources into one agent
agents sync [agentSpec] [repo] Make this machine current, or sync resources into one agent
agents sync status Unified sync status across the fleet — what is drifted, missing, or behind, with an option to sync it.
teams — Organize AI coding agents into teams that work in parallel on a shared task.
agents teams Organize AI coding agents into teams that work in parallel on a shared task.
agents teams active List every teammate running right now, across all teams (PID-alive check).
agents teams add <team> <teammate> <task> Add a teammate to work on a task. Runs in background; returns immediately. Use 'status' to check in.
agents teams create <team> Start a new team. No teammates yet; add them with `teams add`.
agents teams disband [team] Disband the team. Stops all teammates cleanly and removes the team registry entry.
agents teams doctor Check which agents are installed and available to join a team. Verifies CLI paths and shows an advisory sign-in hint.
agents teams list [query] List your teams, most recent activity first
agents teams logs [teammate] Show a teammate's concise session summary. --full (or -n <lines>) for the raw stdout. Accepts positional name, --teammate <name>, UUID, or UUID prefix.
agents teams message <team> <teammate> <message> Send a follow-up message to a teammate. A running teammate is steered via its mailbox; a stopped one is resumed — re-entering its own session with the message.
agents teams pr-watch [team] Watch the PRs a team opened and react autonomously: RED CI -> spawn a fix teammate with the failure logs; new review comment -> route a bugfix teammate. Both slot into the team DAG (visible in `teams status`).
agents teams remove [team] [teammate] Remove a stopped teammate's logs and metadata. Use 'stop' first to end a running teammate.
agents teams resume <team> <teammate> [message] Resume a stopped teammate (completed/failed/stopped) by re-entering its own session with a message as the next user turn. If the teammate is still running, the message is steered via its mailbox instead.
agents teams start [team] Launch ready teammates independently. Failed launch/placement and blocked --after dependencies persist in status; --watch keeps draining viable DAG branches.
agents teams status [team] Check in on a team: status, files touched, recent commands, last messages. Pass --verbose for the full per-teammate dump; --since for delta polling.
agents teams stop [team] [teammate] Stop a running teammate. Resume it later with `agents teams resume`. Cleans up worktree if no uncommitted changes.
tmux — Persistent terminal-multiplexer sessions for agents. Survive editor restarts, share with other tools.
agents tmux Persistent terminal-multiplexer sessions for agents. Survive editor restarts, share with other tools.
agents tmux attach <name> Attach to a running session. Replaces this shell with the tmux client until you detach (Ctrl-b d) or the agent exits (session is then torn down).
agents tmux capture <target> Print the contents of a pane. Target is "name" or "name:pane".
agents tmux check Check whether tmux is installed and report its version.
agents tmux has <name> Exit 0 if a session with this name exists, 1 otherwise. Useful in shell scripts.
agents tmux info <name> Show provenance for a session (cmd, cwd, created_at, source, labels).
agents tmux kill [name] Kill one tmux session, or pick from a list that shows each pane's last screen. Idempotent.
agents tmux kill-all Kill every session on the shared server and remove the socket. Requires --yes.
agents tmux list List live tmux sessions on the shared server (name, age, last screen line). Prunes stale meta files as a side effect.
agents tmux new <name> Start a detached tmux session running a command. The session persists until killed.
agents tmux send <target> <keys> Send keystrokes to a session. Target is "name" or "name:pane" (e.g. team:%2 or team:1).
agents tmux split <name> <direction> Split the active pane of a session. Direction: h (left/right) or v (top/bottom).
trace — Visualize a session as a trajectory — a tool-call timeline you can read at a glance. Opens a visual for a person; prints a compact trajectory for an agent.
agents trace <selectors...> Visualize a session as a trajectory — a tool-call timeline you can read at a glance. Opens a visual for a person; prints a compact trajectory for an agent.
traces — Sync this device's derived, redacted trajectories to your Phoenix account
agents traces Sync this device's derived, redacted trajectories to your Phoenix account
agents traces open Open the Phoenix Evals console
agents traces setup Provision the private Cloudflare Worker and R2 bucket for traces
agents traces status Show last sync time for this device
agents traces sync Push derived, redacted trajectories (incremental)
trash — Inspect and restore soft-deleted agent version directories
agents trash Inspect and restore soft-deleted agent version directories
agents trash list [agent] List soft-deleted version directories (optionally filtered to one agent)
uninstall — Completely remove agents-cli and restore your original agent configs. Reverses agents setup.
agents uninstall Completely remove agents-cli and restore your original agent configs. Reverses `agents setup`.
update — Move a frozen agent installation to a new release, keeping its name and every reference to it
agents update [target] Move a frozen agent installation to a new release, keeping its name and every reference to it
agents update list <agent> Show every frozen installation of an agent and the release each carries
upgrade — Upgrade agents-cli to the latest version (or a specific [version])
agents upgrade [version] Upgrade agents-cli to the latest version (or a specific [version])
use — Switch the active version for an agent. This is the only command that sets the default.
agents use <agent> [version] Switch the active version for an agent. This is the only command that sets the default.
view — Show what agent CLIs are installed and which versions you have. Inspect resources when you pass agent@version.
agents view [agent] Show what agent CLIs are installed and which versions you have. Inspect resources when you pass agent@version.
watchdog — Auto-nudge stalled agent terminals: detect stalls, resolve the exact split, inject "Continue." — no menu-bar needed.
agents watchdog Auto-nudge stalled agent terminals: detect stalls, resolve the exact split, inject "Continue." — no menu-bar needed.
agents watchdog history [sessionId] Show persisted Watchdog decisions and actions, newest first.
agents watchdog off Disable the daemon watchdog pass on this device.
agents watchdog on Enable the daemon watchdog pass on this device.
agents watchdog policy <sessionId> <policy> Set per-session policy: off (ignore) | keep (default) | handsoff (detect + flag, never inject).
agents watchdog rotate <state> Turn in-place rotate of rate-limited sessions on|off (watchdog.rotate in agents.yaml). Rotate-only: nudging stays on — unlike `watchdog off`, which disables the whole watchdog on this device.
agents watchdog status Show whether the daemon watchdog pass is enabled and where state is written.
webhooks — Run a localhost signed webhook receiver for routine triggers.
agents webhooks Run a localhost signed webhook receiver for routine triggers.
agents webhooks serve Receive signed GitHub/Linear/Slack webhooks on /hooks/<source> and fire matching routines and handlers.
workflows — Manage multi-agent pipeline workflows (WORKFLOW.md bundles)
agents workflows Manage multi-agent pipeline workflows (WORKFLOW.md bundles)
agents workflows add [source] Install workflows from a source (GitHub, local) or pick from central storage
agents workflows list [agent] Show installed workflows and which agent versions they are synced to
agents workflows remove [name] Remove a workflow from version homes (interactive picker if no name given)
agents workflows view [name] Read workflow details (description, subagents, model, MCP)