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