page:docs-user-guide-reference-adapters-cli
Adapters CLI Reference reference
Docs(../index.md) › Reference(./index.md) › Adapters CLI
Docs › Reference › Adapters CLI
Adapters CLI Reference
**Package:** @a5c-ai/adapters-cli · **Binary:** adapters · **Version:** 6.0.0 · **Node:** >=20.9.0
On this page
- In Plain English
- Technical Reference
- adapters run
- adapters install (and uninstall / update / detect)
- adapters auth
- adapters doctor
- Not Supported
---
In Plain English
**The adapters CLI lets you run any supported AI coding harness from your shell with one command - and manage its install, models, sessions, config, and auth in the same place.**
It is the host-side companion to Babysitter's Adapters runtime. Where the in-session /babysitter:* commands drive an orchestration run from *inside* a harness, adapters drives a harness from *outside* it.
A two-line taste:
npm install -g @a5c-ai/adapters-cli
adapters run claude "explain this codebase"That installs the CLI globally and runs the Claude harness with a single prompt. No plugin, no marketplace, no session setup required.
**Three CLIs, three jobs - don't conflate them.**
| CLI | Where it runs | What it does |
|-----|---------------|--------------|
|
adapters| Your shell (host-side) | Run/install/manage harnesses directly ||
babysitter| Your shell (host-side) | Core orchestration runtime (run:*,task:*,harness:install-plugin) ||
/babysitter:*| Inside a harness (in-session) | Drive an orchestration run from the chat surface |
---
Technical Reference
The adapters binary is published as @a5c-ai/adapters-cli and requires Node.js **>=20.9.0** (the rest of the Babysitter toolchain runs on Node >=20.0.0; the Adapters CLI pins a slightly higher floor). Install it globally:
npm install -g @a5c-ai/adapters-cli
adapters version
adapters doctoradapters doctor runs an environment health check and is the fastest way to confirm the CLI can see your harness binaries and credentials.
Global Options
These flags are accepted across commands:
| Flag | Type | Description |
|---|---|---|
--json | boolean | Emit JSON output where the command supports it |
--config-dir <dir> | string | Override the config directory |
--project-dir <dir> | string | Override the project directory |
--log-level <level> | string | Set log verbosity |
--log-file <path> | string | Write logs to a file |
--debug | boolean | Enable debug output |
--no-color | boolean | Disable ANSI colors |
--help, -h | boolean | Show help |
--version, -V | boolean | Print version |
Use
adapters help <command>for per-command help at any time.
---
`adapters run`
Run an agent with a prompt.
adapters run claude "explain this codebase"
adapters run codex --yolo --no-session "add tests"
adapters run --profile fast "review this PR"**Arguments:**
| Argument | Required | Description |
|---|---|---|
agent | no | Agent name (first positional, if registered) |
prompt | no | Prompt text (remaining positionals or stdin) |
**Options:**
| Flag | Type | Description |
|---|---|---|
--stream / --no-stream | boolean | Enable / disable streaming |
--thinking-effort <level> | string | low, medium, high, max |
--thinking-budget <n> | number | Thinking budget in tokens |
--thinking-override <v> | string | Thinking override |
--temperature <n> | number | Sampling temperature |
--top-p <n> | number | Top-p |
--top-k <n> | number | Top-k |
--max-tokens <n> | number | Maximum output tokens |
--max-output-tokens <n> | number | Maximum output tokens |
--max-turns <n> | number | Maximum agentic turns |
--session <id> | string | Resume session by ID |
--fork <id> | string | Fork session by ID |
--no-session | boolean | Ephemeral run (no session persisted) |
--system <text> | string | System prompt |
--system-mode <mode> | string | prepend, append, replace |
--cwd <dir> | string | Working directory |
--env <KEY=VALUE> | string (repeatable) | Environment variable |
--yolo | boolean | Auto-approve all tool calls |
--deny | boolean | Auto-deny all approval requests |
--timeout <ms> | number | Run timeout in ms |
--inactivity-timeout <ms> | number | Inactivity timeout in ms |
--output-format <fmt> | string | Output format |
--tag <tag> | string (repeatable) | Run tag |
--run-id <id> | string | Run ID |
--attach <ref> | string (repeatable) | Attach a file/resource |
--skill <name> | string (repeatable) | Skill to load |
--mcp-server <ref> | string (repeatable) | MCP server |
--project-id <id> | string | Project ID |
--profile <name> | string | Named profile to apply |
--prompt <text>, -p | string | Initial prompt text |
--non-interactive | boolean | Force headless one-shot mode (with --prompt) |
--interactive, -i | boolean | Enter interactive REPL mode |
--quiet, -q | boolean | Suppress non-essential output |
--use-mock-harness | boolean | Use mock harness (testing) |
--mock-scenario <name> | string | Mock scenario (testing) |
---
`adapters install` (and `uninstall` / `update` / `detect`)
Install, uninstall, update, or detect agent CLI binaries. The same command dispatches all four operations.
adapters install claude
adapters install claude --dry-run
adapters uninstall codex
adapters update codex
adapters detect claude --json**Argument:** agent.
**Options:**
| Flag | Type | Default | Description |
|---|---|---|---|
--force | boolean | false | Reinstall even if already present |
--dry-run | boolean | false | Print the planned command without executing |
--pkg-version <v> | string | - | Pin to a specific version (npm only) |
**Version pinning uses
--pkg-version, not--version.**--versionprints the CLI's own version.
---
`adapters adapters`
List and inspect registered adapters.
adapters adapters list
adapters adapters detect claude
adapters adapters info gemini**Subcommands:** list (default), detect, info. **Arguments:** subcommand, agent (for detect/info). **Options:** --json.
---
`adapters models`
List and inspect models.
adapters models list claude
adapters models info claude claude-sonnet-4-20250514**Subcommands:** list, info, get, refresh, current, set. **Arguments:** subcommand (required), agent (required), model (for info/get/set). **Options:** --provider <name>, --json.
---
`adapters sessions`
Manage agent sessions.
adapters sessions list claude
adapters sessions cost**Subcommands:** list (default), show, export, cost. **Arguments:** subcommand, agent, session-id (for show/export).
**Options:**
| Flag | Type | Description |
|---|---|---|
--since <date> | string | Filter sessions after this date |
--until <date> | string | Filter sessions before this date |
--model <id>, -m | string | Filter by model |
--tag <tag> | string (repeatable) | Filter by tag |
--limit <n> | number | Maximum results |
--sort <key> | string | Sort by: date, cost, turns |
--format <fmt> | string | Output format: json, jsonl, markdown |
--json | boolean | Output as JSON |
---
`adapters config`
Read and write agent configuration.
adapters config get claude model
adapters config set claude model claude-sonnet-4-20250514
adapters config schema codex**Subcommands:** get, set, schema, validate, reload. **Arguments:** subcommand (required), agent, field, value. **Options:** --json.
---
`adapters profiles`
Manage named RunOptions presets that you can apply with adapters run --profile <name>.
adapters profiles list
adapters profiles set fast --agent claude --yolo --max-turns 5
adapters profiles delete fast**Subcommands:** list (default), show, set, delete, apply. **Arguments:** subcommand, name. **Options:** --scope <scope> (global or project), --json.
---
`adapters auth`
Check and set up authentication.
adapters auth check
adapters auth check claude
adapters auth setup gemini**Subcommands:** check, setup. **Arguments:** subcommand (required), agent (optional for check). **Options:** --json.
---
`adapters plugin` (alias: `adapters plugins`)
Manage native agent plugins. Subcommand availability is validated at runtime against each agent's plugin capabilities and delegated to the native plugin command.
adapters plugin list claude
adapters plugin install claude filesystem-watcher
adapters plugin marketplace claude**Subcommands:** list, install, enable, disable, marketplace. **Arguments:** subcommand (required), agent (required), plugin (plugin name / marketplace cmd). **Options:** --json, --help.
---
`adapters mcp`
Manage MCP (Model Context Protocol) servers for an agent.
adapters mcp list claude
adapters mcp install claude filesystem**Subcommands:** list, install, uninstall. **Arguments:** subcommand (required), agent (required), server (for install/uninstall).
**Options:**
| Flag | Type | Default | Description |
|---|---|---|---|
--global | boolean | true (when --project absent) | Install/operate at global scope |
--project | boolean | - | Operate at project scope |
---
`adapters skill`
Manage skill folders for agents.
adapters skill list claude
adapters skill add claude ./skills/my-skill --global
adapters skill remove claude my-skill --project**Subcommands:** list, add, remove, where, agents. **Arguments:** subcommand (required), agent, source/name.
**Options:**
| Flag | Type | Default | Description |
|---|---|---|---|
--global | boolean | false | User-level skills dir |
--project | boolean | true | Project-level skills dir (default) |
--name <name> | string | - | Override copied skill name |
--force | boolean | false | Overwrite existing |
--json | boolean | false | Output as JSON |
---
`adapters agent`
Manage custom sub-agents for harnesses.
adapters agent list claude
adapters agent add claude ./my-agent.md --global
adapters agent remove claude my-agent.md --project**Subcommands:** list, add, remove, where, agents. **Arguments:** subcommand (required), agent, source/name.
**Options:**
| Flag | Type | Default | Description |
|---|---|---|---|
--global | boolean | false | User-level agents dir |
--project | boolean | true | Project-level agents dir (default) |
--name <name> | string | - | Override copied agent name |
--force | boolean | false | Overwrite existing |
--json | boolean | false | Output as JSON |
---
`adapters workspaces`
Manage temp workspaces and git worktrees.
adapters workspaces list
adapters workspaces create my-ws --repo ./repo --mode worktree
adapters workspaces delete my-ws --force**Subcommands:** list (default), create, archive, cleanup, recover, delete, sync-sessions. **Arguments:** subcommand, workspace/name.
**Options:**
| Flag | Type | Default | Description |
|---|---|---|---|
--repo <path> | string (repeatable) | - | Local cloned repository path |
--mode <mode> | string | worktree | worktree or symlink |
--name <name> | string | - | Workspace name |
--root <dir> | string | - | Override workspace root directory |
--force | boolean | false | Allow delete to clean up on disk first |
--json | boolean | false | Output as JSON |
---
`adapters launch`
Launch a harness with provider/model config and stdin/stdout passthrough. This is the path for routing a harness to a cloud provider (Bedrock, Vertex, Azure Foundry, Ollama, Anthropic, and more).
adapters launch claude bedrock --region us-east-1
adapters launch codex bedrock --with-proxy-if-needed -p "fix the bug"
adapters launch claude anthropic --dry-run**Arguments:** harness (required), provider (e.g. bedrock, vertex, ollama, anthropic).
**Options:**
| Flag | Type | Description |
|---|---|---|
--api-key <key> | string | API key for the provider |
--profile <name> | string | Profile |
--api-base <url> | string | Custom API endpoint |
--region <region> | string | Cloud region (Bedrock, Vertex) |
--project <id> | string | Cloud project (Vertex, Foundry) |
--resource-group <name> | string | Azure resource group |
--endpoint-name <name> | string | Endpoint name |
--transport <t>, -t | string | anthropic, openai-chat, openai-responses, google |
--auth-command <cmd> | string | External command that emits a bearer token |
--with-proxy-if-needed | boolean | Auto-launch proxy if harness can't speak provider natively |
--with-proxy | boolean | Force proxy even if not needed |
--no-proxy | boolean | Disable proxy (error if needed) |
--proxy-port <n> | number | Proxy listen port (0=auto) |
--proxy-log-level <level> | string | Proxy log level |
--resume <id>, -r | string | Resume session by ID |
--session-id <id>, -s | string | Explicit new session ID |
--prompt <text>, -p | string | Non-interactive mode with prompt |
--interactive, -i | boolean | Interactive mode |
--max-turns <n> | number | Turn limit |
--max-budget-usd <n> | number | Budget limit in USD |
--dry-run | boolean | Print the resolved plan as JSON, don't execute |
--provider-arg <arg> | string (repeatable) | Extra provider argument |
--observe | boolean | Observe mode |
--workspace <id> | string | Workspace identifier |
--workspace-create | boolean | Create workspace |
--workspace-mode <mode> | string | Workspace mode |
--workspace-repo <path> | string (repeatable) | Workspace repo |
--workspace-name <name> | string | Workspace name |
--yolo | boolean | Auto-approve tool calls |
--bridge-interactive | boolean | Bridge interactive mode |
--bridge-hooks | boolean | Bridge hooks |
---
`adapters detect-host`
Detect which agent harness this CLI is running under.
adapters detect-host
adapters detect-host --json**Options:** --json.
---
`adapters remote`
Install or update adapters on a remote host (SSH, Docker, Kubernetes, or local).
adapters remote install host.example.com --mode ssh --dry-run
adapters remote install my-pod --mode k8s --harness codex**Subcommands:** install, update. **Arguments:** subcommand (required), host (required - target host / pod / container).
**Options:**
| Flag | Type | Default | Description |
|---|---|---|---|
--mode <mode> | string | ssh | ssh \ |
--harness <agent> | string | claude | Agent to install after adapters |
--identity-file <path> | string | - | SSH key path (ssh mode) |
--port <n> | number | - | SSH port (ssh mode) |
--context <ctx> | string | - | Kubernetes context (k8s mode) |
--force | boolean | false | Reinstall even if already present |
--dry-run | boolean | false | Print planned commands without executing |
--json | boolean | false | Output as JSON |
---
`adapters hooks`
Manage and dispatch unified agent hooks. See Hooks for the conceptual model and per-harness hook tables.
adapters hooks discover
adapters hooks list
adapters hooks add --id trace-all --handler builtin --target trace**Subcommands:** discover, list, add, remove, set, handle. **Arguments:** agent, hookType (for handle).
**Options:**
| Flag | Type | Default | Description |
|---|---|---|---|
--handler <type> | string | builtin | builtin \ |
--target <target> | string | log | Handler target |
--priority <n> | string | 100 | Sort order (lower = earlier) |
--enabled <bool> | string | - | true \ |
--id <id> | string | - | Hook ID |
--global | boolean | false | Global scope |
--project | boolean | true | Project scope (default) |
--json | boolean | false | Output as JSON |
---
`adapters gateway`
Run the browser/mobile gateway service and manage its access tokens.
adapters gateway serve
adapters gateway tokens create --name phone --qr
adapters gateway status --url http://127.0.0.1:7878**Subcommands:** serve, tokens, status. **Arguments:** subcommand (required), tokens-subcommand (list, create, revoke under tokens).
**Options:**
| Flag | Type | Default | Description |
|---|---|---|---|
--config <path> | string | default gateway config path | Gateway config path (serve, tokens) |
--host <host> | string | - | Listen host (serve) |
--port <n> | number | - | Listen port (serve) |
--webui <path> | string | - | WebUI root (serve) |
--no-webui | boolean | false | Disable WebUI (serve) |
--url <url> | string | http://127.0.0.1:7878 | Gateway URL (status, tokens create) |
--name <name> | string | token@<hostname> | Token name (tokens create) |
--ttl-ms <n> | number | - | Token TTL in ms (tokens create) |
--qr | boolean | false | Render QR (tokens create) |
--id <id> | string | - | Token ID (tokens revoke) |
--json | boolean | false | Output as JSON |
---
`adapters doctor`
Run an environment health check. Run this first when something is not working.
adapters doctor
adapters doctor --json**Options:** --json.
---
`adapters tui`
Launch the Ink-based adapters TUI.
adapters tui
adapters tui --agent claude-code**Options:**
| Flag | Type | Default | Description |
|---|---|---|---|
--agent <name>, -a | string | claude-code | Default agent for new prompts |
--user-plugins-dir <dir> | string | $ADAPTERS_TUI_PLUGINS_DIR or ~/.adapters/tui-plugins | Override user-plugin discovery dir |
--no-user-plugins | boolean | false | Skip discovering user plugins |
---
`adapters version` / `adapters help`
adapters version
adapters --version
adapters help
adapters help runadapters version (and adapters --version) prints the CLI version. adapters help [command] shows main help or per-command help.
---
Not Supported
A handful of items appear in help text or are reserved internally but are **not** part of the supported command surface. Do not script against them:
adapters config --scope(config does not take a scope flag - useadapters profiles --scopeinstead)adapters install --version(use--pkg-versionto pin a version;--versionprints the CLI version)adapters mcp enable/adapters mcp disable(themcpcommand implementslist,install,uninstallonly)adapters hooks install(thehookscommand implementsdiscover,list,add,remove,set,handle)
---
Related Documentation
- Adapters - The conceptual guide to the Adapters runtime
- Adapter Types reference - All 20 adapter package types enumerated (Adapters is a family, not one thing)
- Adapters (ecosystem overview) - Introductory tour of the adapters family
- Installation - Installing the
adaptersCLI and harness plugins - CLI Reference - The core
babysitterorchestration CLI - Slash Commands - The in-session
/babysitter:*surface - CLI Examples - Worked command examples
---
Next steps
- **Next:** Configuration
- **Related:** Adapters (concept), Adapter Types reference, Install Matrix, CLI Reference