CLI Reference (`adapters`)

**Specification v1.0** | @a5c-ai/adapters-cli

**SCOPE EXTENSION:** hermes-agent (@NousResearch/hermes-agent) is included as a 10th supported agent per explicit project requirements from the project owner. It extends the original scope document's 9 built-in agents. All hermes-specific content in this spec is marked with this same scope extension note.

---

1. Overview

The adapters binary is the CLI surface of the @a5c-ai/adapters project. It exposes every capability of the SDK -- running agents, inspecting adapters, managing sessions, configuring agents, handling authentication, working with plugins, and tracking costs -- through a single command-line interface.

The CLI and SDK are co-equal surfaces that share the same core layer and behave identically. Every CLI command maps to a specific SDK method. This specification defines the CLI completely and precisely: a developer should be able to implement the binary from this document alone.

1.1 Package Coordinates

The binary is installed as part of @a5c-ai/adapters (the convenience meta-package) or standalone via @a5c-ai/adapters-cli. It depends on @a5c-ai/comm-adapter and @a5c-ai/adapters-codecs.

# Via meta-package
npm install -g @a5c-ai/adapters

# Standalone CLI
npm install -g @a5c-ai/adapters-cli

# Zero-install
npx @a5c-ai/adapters
npx @a5c-ai/adapters run claude "hello"

1.2 Cross-References

---

2. Invocation Syntax

adapters [command] [subcommand] [positional-args...] [flags...]

When invoked without a command, adapters prints a help summary and exits with code 0.

When invoked with an unrecognized command, adapters prints an error message with suggestions and exits with code 2.

---

3. Global Flags

Global flags are accepted by every command. They are parsed before command-specific flags and override corresponding environment variables and config file values.

3.1 Flag Parsing Rules

• Long flags use --kebab-case (e.g., --thinking-effort, --config-dir).
• Short flags are single-character prefixed with - (e.g., -a, -m, -i, -q, -y).
• Boolean flags do not take a value (--json enables JSON mode; --no-stream disables streaming).
• Repeatable flags accept multiple values by specifying the flag multiple times (e.g., --tag build --tag test).
• --env flags use KEY=VALUE syntax (e.g., --env ANTHROPIC_API_KEY=sk-...).
• -- terminates flag parsing; all subsequent arguments are treated as positional.

---

4. Exit Codes

The adapters binary uses the following exit codes. These are the only exit codes produced by the CLI itself. When adapters run is used, the agent subprocess exit code is available in the JSONL output but does not propagate as the adapters process exit code unless the agent crashed.

4.1 Exit Code Mapping

The CLI maps ErrorCode values from the SDK to exit codes as shown above. When multiple errors occur, the exit code reflects the first fatal error. Non-fatal errors (e.g., RATE_LIMITED with a successful retry) do not affect the exit code.

The following ErrorCode values map to exit code 1 (General error) as they have no dedicated exit code:

Note: CONFIG_LOCK_ERROR maps to exit code 7 (same as CONFIG_ERROR), not exit code 1, since it is a config-related error. It is not listed in the exit code 1 table above.

---

5. Output Modes

The CLI supports three output modes, selected by flags and context.

5.1 Human-Readable (Default)

When stdout is a TTY and --json is not set, the CLI produces formatted, colored output:

• **Tables**: aligned columns with headers for list commands (adapters list, sessions list, models list, etc.).
• **Streaming text**: for adapters run, agent text output is printed to stdout as it arrives. Tool calls, thinking, and file operations are printed to stderr with visual indicators.
• **Progress indicators**: spinners and status lines for long-running operations (install, plugin operations).
• **Color**: ANSI color codes for emphasis, status indicators, and error highlighting. Disabled by --no-color, NO_COLOR env var, or non-TTY stdout.

5.2 JSON (`--json`)

When --json is set on non-streaming commands (e.g., adapters list --json, sessions list --json, models list --json), the CLI outputs a single JSON object or array to stdout:

{
  "ok": true,
  "data": [ ... ]
}

On error:

{
  "ok": false,
  "error": {
    "code": "AGENT_NOT_FOUND",
    "message": "No adapter registered for agent 'foo'",
    "recoverable": false
  }
}

5.3 JSONL Event Stream (`adapters run --json`)

When --json is set on adapters run, the CLI outputs one JSON object per line to stdout. Each line is a serialized AgentEvent object as defined in 04-agent-events.md. The final line is always a RunResult object with type: "run_result".

{"type":"session_start","runId":"01J...","agent":"claude","timestamp":1718000000000,"sessionId":"abc123","resumed":false}
{"type":"text_delta","runId":"01J...","agent":"claude","timestamp":1718000000100,"delta":"Hello","accumulated":"Hello"}
{"type":"message_stop","runId":"01J...","agent":"claude","timestamp":1718000000200,"text":"Hello, world!"}
{"type":"run_result","runId":"01J...","agent":"claude","model":"claude-sonnet-4-20250514","sessionId":"abc123","text":"Hello, world!","exitCode":0,"exitReason":"completed","durationMs":1200,"turnCount":1}

When --debug is combined with --json, each event includes the raw field containing the unparsed agent output line.

Human-readable progress (spinners, status) is suppressed in JSONL mode. Diagnostic messages go to stderr.

---

6. `adapters run` -- Run an Agent

Invoke an agent with a prompt. This is the primary command.

6.1 Syntax

adapters run [<agent>] [<prompt>] [flags...]

Both <agent> and <prompt> are optional positional arguments:

• If <agent> is omitted, the default agent from config is used (GlobalConfig.defaultAgent or --agent global flag).
• If --prompt / -p is provided, it supplies the initial prompt and takes precedence over positional prompt text.
• If no explicit prompt is provided and stdin is not a TTY, the prompt is read from stdin (see Section 14).
• If no explicit prompt is provided and stdin is a TTY and --interactive is not set, the CLI prints an error and exits with code 2.
• If both are provided as positionals, the first argument is parsed as an agent name if it matches a registered adapter; otherwise, the entire positional is treated as the prompt and the default agent is used.

6.2 Flags

SDK-Only RunOptions (No CLI Flag)

The following RunOptions fields are intentionally not exposed as CLI flags:

6.3 Mutual Exclusion

The following flag combinations are invalid and produce exit code 2:

• --session + --no-session
• --session + --fork
• --fork + --no-session
• --yolo + --deny
• --stream + --no-stream

6.4 Flag-to-RunOptions Mapping

The CLI constructs a RunOptions object from flags. Resolution order (highest precedence first):

1. Explicit CLI flags. 2. Profile values (if --profile is set). 3. Project config values (.adapters/config.json). 4. Global config values (~/.adapters/config.json). 5. Adapter defaults.

This matches the resolution order defined in 02-run-options-and-profiles.md, Section 7.

6.5 Behavior

1. The CLI calls createClient() with global flag overrides. 2. Resolves the initial prompt from --prompt, positional args, or stdin. 3. Constructs RunOptions from flags, profile, and config. 4. Calls adapter.run(options) to obtain a RunHandle. 5. By default, the initial prompt is delivered to stdin-capable harnesses over stdin so the harness stays interactive. When --prompt and --non-interactive are both set, adapters instead uses the harness's one-shot prompt flag/path. 6. Consumes events from the RunHandle: - **Human mode**: prints text deltas to stdout, tool calls and thinking to stderr. - **JSONL mode** (--json): writes each AgentEvent as one JSON line to stdout. - **Quiet mode** (-q): suppresses everything except the final message_stop text. 7. On approval_request events (when approvalMode is 'prompt' and not --yolo/--deny): - **Interactive terminal**: prompts the user on stderr, reads response from stdin. - **Non-interactive** (pipe, no TTY): auto-denies with a warning to stderr. 8. On input_required events: - **Interactive terminal**: prompts on stderr, reads from stdin. - **Non-interactive**: emits the event in JSONL mode; otherwise errors. 9. Awaits RunResult. Prints cost summary to stderr (unless --quiet). 10. Exits with the appropriate exit code (see Section 4).

6.6 API Mapping

6.7 Examples

# Basic run
adapters run claude "explain this codebase"

# Run with thinking and model override
adapters run claude --model claude-sonnet-4-20250514 --thinking-effort high "refactor auth module"

# Ephemeral run with auto-approve
adapters run codex --no-session --yolo "add unit tests for utils.ts"

# Resume session
adapters run claude --session abc123 "continue from where we left off"

# Fork session
adapters run claude --fork abc123 "try a different approach"

# JSONL output for piping
adapters run gemini --json "list all TODO items" | jq 'select(.type == "text_delta") | .delta'

# With tags for cost tracking
adapters run claude --tag feature/auth --tag sprint-42 "implement oauth flow"

# Using a profile
adapters run --profile careful "review this PR"

# Quiet mode -- only final text
adapters run claude -q "what is 2+2"

---

6b. `adapters launch` -- Launch a Harness with Provider Flexibility

Start (or resume) an interactive or non-interactive coding agent session with full stdin/stdout passthrough. Unlike adapters run, which normalizes output into the AgentEvent stream, adapters launch is a **transparent proxy** — the user interacts directly with the harness as if they invoked it natively. Its key additional capability is unified provider resolution: you can point any supported harness at any LLM provider, with adapters-proxy bridging the gap when the harness cannot speak the provider's native wire protocol.

See launcher for the archived launcher specification and provider & model configuration for the archived provider-configuration design.

6b.1 Syntax

adapters launch <harness> [provider] [flags...]

**Positional arguments:**

6b.2 Flags

Provider Configuration

Proxy Control

Session Control

Execution Mode

Bridge Control

Harness Passthrough

General

6b.3 Supported Provider IDs

6b.4 Supported Transport IDs

6b.5 Native Support Matrix

This matrix shows which harness+provider combinations work **without** a proxy. Use --with-proxy-if-needed for combinations marked with a cross.

Cells marked "No" require --with-proxy-if-needed. Cells marked "Via ANTHROPIC_BASE_URL" or "OpenAI-compat" work with an env var workaround but a proxy is recommended for reliability.

6b.6 Examples

# Interactive Claude Code with default provider (Anthropic direct)
adapters launch claude

# Interactive Claude Code via Bedrock (native, no proxy needed)
adapters launch claude bedrock --region us-east-1

# Interactive Claude Code via Vertex (native)
adapters launch claude vertex --project my-gcp-project --region us-central1

# Interactive Codex via Bedrock (proxy required: codex speaks OpenAI, bedrock speaks Anthropic)
adapters launch codex bedrock --region us-east-1 \
  --model anthropic.claude-sonnet-4-20250514-v1:0 \
  --with-proxy-if-needed

# Non-interactive (one-shot) run via Vertex
adapters launch claude vertex --project my-project --region us-central1 \
  -p "Explain the authentication flow in this codebase" \
  --max-turns 3

# Interactive Codex via Ollama (local, no proxy needed with --oss flag)
adapters launch codex ollama --model qwen3:32b

# Interactive Claude Code via Ollama (proxy bridges Ollama to Anthropic transport)
adapters launch claude ollama --model qwen3:32b --with-proxy-if-needed

# Use a named provider profile from ~/.adapters/providers.json
adapters launch claude --profile work-bedrock

# Dry run: see what would be executed without running it
adapters launch codex bedrock --region us-east-1 --model anthropic.claude-sonnet-4-20250514-v1:0 \
  --with-proxy-if-needed --dry-run

# Passthrough raw harness args after --
adapters launch claude api -- --bare --verbose

6b.7 Non-Interactive vs Interactive Mode

**Interactive mode** (default, no --prompt): stdin, stdout, and stderr are passed through directly to the harness. The user interacts with the harness TUI natively. adapters only manages the proxy lifecycle and process signals.

**Non-interactive mode** (--prompt is set): the prompt is delivered to the harness via its native mechanism (e.g., --print for claude, exec for codex, --prompt for gemini). stdout and stderr are still passed through raw. The process exits when the harness completes its response. Suitable for scripting and CI/CD.

6b.8 Error Codes

---

7. `adapters install` -- Install Agent CLIs

Install or display installation instructions for agent CLI binaries.

7.1 Syntax

adapters install <agent> [flags...]

<agent> is required. Must be one of the ten built-in agent names: claude, codex, gemini, copilot, cursor, opencode, pi, omp, openclaw, hermes.

7.2 Flags

7.3 Behavior

1. Resolves the adapter for <agent>. 2. Reads AgentCapabilities.installMethods filtered by the current platform (process.platform). 3. If --method is specified, selects only the matching install method. Exits with code 2 if no method matches. 4. For each matching install method: a. Checks prerequisites (InstallMethod.prerequisiteCheck) if defined. Prints a warning if the prerequisite is not met. b. Prints the install command to stdout. c. Unless --dry-run: prompts for confirmation (unless --yes), then executes the command as a child process, streaming stdout/stderr to the terminal. 5. After installation, runs adapter.adapters.detect(agent) to verify the install succeeded and prints the detected version.

7.4 Install Methods per Agent

7.5 API Mapping

7.6 Examples

# Install Claude Code
adapters install claude

# See what would be installed without running
adapters install --dry-run gemini

# Force npm method
adapters install opencode --method npm

# Non-interactive install
adapters install codex --yes

# Install hermes (Python agent)
adapters install hermes

---

8. `adapters adapters` -- Adapter Discovery

List and inspect registered adapters and their installation state.

8.1 Syntax

adapters adapters list [flags...]
adapters adapters detect <agent> [flags...]

8.2 `adapters adapters list`

Lists all registered adapters with their installation status, version, and authentication state.

**Flags:**

**Output columns (human mode):**

**API mapping:** adapter.adapters.list() combined with adapter.adapters.installed() for the installed/version/auth columns.

8.3 `adapters adapters detect <agent>`

Detect a single agent: checks installation, resolves the binary path, detects the version, and checks authentication state.

**Flags:**

**Output (human mode):** Key-value pairs:

Agent:     claude
Installed: yes
Path:      /usr/local/bin/claude
Version:   1.2.3
Min version: 1.0.0
Meets min:  yes
Auth:      authenticated
Model:     claude-sonnet-4-20250514

**API mapping:** adapter.adapters.detect('claude') returns InstalledAgentInfo.

8.4 Error Behavior

• Unknown agent name: exit code 3 (AGENT_NOT_FOUND).
• Agent not installed (for detect): prints the detection result showing installed: false, exits with code 0 (detection succeeded; the result is "not installed").

---

9. `adapters capabilities` -- Agent Capabilities

Display the capabilities manifest for an agent, optionally scoped to a specific model.

9.1 Syntax

adapters capabilities <agent> [flags...]

9.2 Flags

9.3 Behavior

• Without --model: prints agent-level capabilities (AgentCapabilities) as defined in 06-capabilities-and-models.md, Section 2.
• With --model: prints the union of agent-level and model-level capabilities (ModelCapabilities) for the specified model.

**Output (human mode):** Grouped key-value display organized by category (session, streaming, tool calling, thinking, output, skills, plugins, process, auth, install).

**API mapping:**

9.4 Error Behavior

• Unknown agent: exit code 3 (AGENT_NOT_FOUND).
• Unknown model (with --model): exit code 1, error message listing available models.

---

10. `adapters models` -- Model Registry

List, inspect, and refresh model metadata for agents.

10.1 Syntax

adapters models list <agent> [flags...]
adapters models get <agent> <model-id> [flags...]
adapters models refresh <agent> [flags...]
adapters models current <agent> [flags...]
adapters models set <agent> <model-id> [--provider <provider>] [flags...]

10.2 `adapters models list <agent>`

List all models available for an agent.

**Flags:**

**Output columns (human mode):**

**API mapping:** adapter.models.catalog('claude') returns the per-adapter model catalog with default-entry metadata.

10.3 `adapters models get <agent> <model-id>`

Show detailed capabilities for a single model.

**Flags:**

**Output (human mode):** Key-value display showing all ModelCapabilities fields.

**API mapping:** adapter.models.model('claude', 'claude-sonnet-4-20250514') returns ModelCapabilities | null.

10.4 `adapters models refresh <agent>`

Refresh the model list from the agent's remote source (where applicable).

**API mapping:** adapter.models.refresh('claude').

10.5 `adapters models current <agent>`

Show the configured model, adapter default, and effective model selection for an agent.

**API mapping:** adapter.config.getModelSelection('claude') plus adapter.models.model(...) for effective-model details.

10.6 `adapters models set <agent> <model-id>`

Validate and persist the configured model for an agent. Optional --provider records the selected provider for configurable/local-provider adapters.

**API mapping:** adapter.models.validate('claude', 'sonnet') followed by adapter.config.setModelSelection('claude', { model, provider }).

10.7 Error Behavior

• Unknown agent: exit code 3 (AGENT_NOT_FOUND).
• Unknown model (for get): exit code 1, error message listing available models.

---

11. `adapters plugin` -- Native Plugin Management

Unified interface for managing native agent plugins through CLI delegation. Commands delegate to each agent's native plugin system (e.g., claude plugins, copilot plugin, gemini extensions). All subcommands are capability-gated: invoking on an agent where native plugin CLI commands don't exist produces exit code 6 (CAPABILITY_ERROR).

11.1 Syntax

adapters plugin list <agent> [flags...]
adapters plugin install <agent> <plugin-id> [flags...]
adapters plugin uninstall <agent> <plugin-id> [flags...]
adapters plugin update <agent> <plugin-id> [flags...]
adapters plugin marketplace <agent> [subcommand] [flags...]

11.2 `adapters plugin list <agent>`

List installed plugins for an agent via native CLI.

**Flags:**

**API mapping:** Delegates to agent's native command (e.g., claude plugins list).

11.3 `adapters plugin install <agent> <plugin-id>`

Install a plugin via agent's native CLI.

**Flags:**

**API mapping:** Delegates to agent's native install command.

11.4 `adapters plugin uninstall <agent> <plugin-id>`

Uninstall a plugin via agent's native CLI.

**Flags:**

**API mapping:** Delegates to agent's native uninstall command.

11.5 `adapters plugin update <agent> <plugin-id>`

Update a plugin via agent's native CLI.

**API mapping:** Delegates to agent's native update command.

11.6 `adapters plugin marketplace <agent> [subcommand]`

Access agent's native plugin marketplace commands.

**API mapping:** Delegates to agent's marketplace commands (e.g., claude plugins marketplace).

11.7 Plugin Support per Agent

11.8 Examples

# List installed plugins via native CLI
adapters plugin list claude
adapters plugin list gemini

# Install plugins via native marketplace
adapters plugin install claude @anthropic/frontend-design
adapters plugin install copilot github/copilot-agent

# Access native marketplace
adapters plugin marketplace claude
adapters plugin marketplace copilot

---

12. `adapters mcp` -- MCP Server Management

Unified interface for managing Model Context Protocol servers across all agents. MCP servers provide cross-agent capabilities and integrations. All agents support MCP servers.

12.1 Syntax

adapters mcp list <agent> [flags...]
adapters mcp install <agent> <mcp-server> [flags...]
adapters mcp uninstall <agent> <mcp-server> [flags...]

12.2 `adapters mcp list <agent>`

List installed MCP servers for an agent.

**Flags:**

**Output columns (human mode):**

12.3 `adapters mcp install <agent> <mcp-server>`

Install an MCP server for an agent.

**Flags:**

12.4 `adapters mcp uninstall <agent> <mcp-server>`

Uninstall an MCP server from an agent.

**Flags:**

12.5 MCP Server Registry

All MCP servers are available from the official registry at https://modelcontextprotocol.io.

12.6 Examples

# List MCP servers for an agent
adapters mcp list claude
adapters mcp list cursor

# Install MCP server globally
adapters mcp install claude filesystem
adapters mcp install gemini postgres

# Install MCP server to project
adapters mcp install claude web-browser --project

# Remove MCP server
adapters mcp uninstall claude filesystem

---

13. `adapters sessions` -- Session Management

Read-only access to agent session data. The CLI delegates to SessionManager (see 07-session-manager.md, Section 2). Session data is never modified by these commands.

12.1 Syntax

adapters sessions list <agent> [flags...]
adapters sessions show <agent> <session-id> [flags...]
adapters sessions search <query> [flags...]
adapters sessions export <agent> <session-id> [flags...]
adapters sessions diff <agent>:<id> <agent>:<id> [flags...]
adapters sessions resume <agent> <session-id> [flags...]
adapters sessions fork <agent> <session-id> [flags...]

12.2 `adapters sessions list <agent>`

List sessions for an agent.

**Flags:**

**Output columns (human mode):**

**API mapping:** adapter.sessions.list('claude', { since, until, model, tags, limit, sort }) returns SessionSummary[].

12.3 `adapters sessions show <agent> <session-id>`

Display the full content of a session.

**Flags:**

**API mapping:** adapter.sessions.export('claude', 'abc123', 'markdown').

12.4 `adapters sessions tail <agent> [session-id]`

This command is not part of the current public CLI surface.

@a5c-ai/comm-adapter does not currently expose a truthful live session-watch API. Earlier drafts described adapter.sessions.watch(), but that contract was removed rather than shipping synthetic AgentEvent payloads derived from arbitrary session-file changes.

12.5 `adapters sessions search <query>`

Full-text search across sessions.

**Flags:**

**API mapping:** adapter.sessions.search({ text: query, agent, since, until }) returns SessionSummary[].

12.6 `adapters sessions export <agent> <session-id>`

Export a session to a file or stdout.

**Flags:**

**Output:** The exported session content is written to stdout. Redirect to a file as needed.

**API mapping:** adapter.sessions.export('claude', 'abc123', 'json') returns string.

12.7 `adapters sessions diff <agent>:<id> <agent>:<id>`

Compute a structural diff between two sessions. Sessions may belong to the same or different agents.

**Syntax:** Each argument uses the unified ID format <agent>:<native-session-id>.

adapters sessions diff claude:abc123 claude:def456
adapters sessions diff claude:abc123 gemini:xyz789

**API mapping:** adapter.sessions.diff({ agent: 'claude', sessionId: 'abc123' }, { agent: 'gemini', sessionId: 'xyz789' }) returns SessionDiff.

12.8 `adapters sessions resume <agent> <session-id>`

Resume a session by starting a new interactive run that continues from the specified session.

**Behavior:** Equivalent to adapters run <agent> --session <session-id> --interactive. Enters REPL mode (see Section 13).

**API mapping:** adapter.run({ agent, sessionId, ... }) with interactive REPL loop.

12.9 `adapters sessions fork <agent> <session-id>`

Fork a session and enter an interactive run on the new branch.

**Behavior:** Equivalent to adapters run <agent> --fork <session-id> --interactive. Enters REPL mode.

**API mapping:** adapter.run({ agent, forkSessionId: sessionId, ... }) with interactive REPL loop.

12.10 Error Behavior

• Unknown agent: exit code 3 (AGENT_NOT_FOUND).
• Unknown session ID: exit code 8 (SESSION_NOT_FOUND).
• Corrupt session file: exit code 1 (PARSE_ERROR), with diagnostic message to stderr.

---

13. Interactive REPL Mode (`adapters run -i`)

When --interactive / -i is set on adapters run, the CLI enters a Read-Eval-Print Loop for multi-turn conversation with the agent.

13.1 Entry Conditions

REPL mode is entered when:

• adapters run -i is invoked (with or without an initial prompt).
• adapters sessions resume is invoked.
• adapters sessions fork is invoked.

13.2 REPL Behavior

1. If an initial prompt is provided, it is sent as the first turn. 2. After the agent completes its response, the CLI prints a prompt indicator (for example, adapters>) and waits for user input on stdin. 3. User input is sent to the running agent via RunHandle.continue(prompt). 4. Tool approval requests are handled inline: the CLI prints the request and prompts for [y]es / [n]o / [a]lways on stderr. 5. The loop continues until: - The user types /exit or /quit. - The user presses Ctrl+D (EOF on stdin). - The user presses Ctrl+C twice within 1 second. - The agent terminates.

13.3 REPL Commands

The following slash commands are recognized within the REPL:

SDK frontends built on the same live-run surface can also defer follow-up prompts with RunHandle.queue() and RunHandle.steer(). The bundled TUI maps /queue ..., /steer ..., and /steer-tool ... onto those APIs when a run is already active.

13.4 REPL + JSONL

When -i and --json are combined, the REPL reads prompts from stdin (one per line) and emits JSONL events to stdout. This enables programmatic multi-turn conversation. The REPL terminates on stdin EOF.

---

14. Pipe and Stdin Support

The CLI supports pipe-based workflows for composability with Unix tools.

14.1 Reading Prompt from Stdin

When adapters run is invoked without a prompt argument and stdin is not a TTY, the entire stdin is read and used as the prompt:

echo "refactor this function" | adapters run claude
cat prompt.txt | adapters run gemini --json
git diff | adapters run codex "review this diff"

When both a positional prompt and stdin are provided, the positional prompt takes precedence and stdin is ignored.

14.2 JSONL Output for Piping

JSONL output (--json) is designed for consumption by downstream tools:

# Extract only text deltas
adapters run claude "explain X" --json | jq 'select(.type == "text_delta") | .delta'

# Monitor tool calls
adapters run codex "fix tests" --json | jq 'select(.type | startswith("tool_"))'

# Extract final text
adapters run gemini "summarize" --json | jq 'select(.type == "run_result") | .text'

14.3 TTY Detection

The CLI detects whether stdin and stdout are TTYs using process.stdin.isTTY and process.stdout.isTTY:

---

15. `adapters cost` -- Cost Reporting

Aggregate and display cost data across runs.

15.1 Syntax

adapters cost report [flags...]

15.2 Flags

15.3 Output (Human Mode)

A formatted table showing cost breakdowns per grouping:

Cost Report (last 30 days)
──────────────────────────────────────────
Agent       Runs    Input$    Output$    Total
claude        42    $1.23      $3.45     $4.68
codex         15    $0.50      $1.20     $1.70
gemini         8    $0.10      $0.30     $0.40
──────────────────────────────────────────
Total         65    $1.83      $4.95     $6.78

15.4 API Mapping

---

16. `adapters config` -- Configuration Management

Read, write, and validate agent configuration files through the unified ConfigManager interface. See 08-config-and-auth.md, Section 2 for the full ConfigManager specification.

16.1 Syntax

adapters config get <agent> [field] [--scope global|project] [--json]
adapters config set <agent> <field> <value> [--scope global|project]
adapters config schema <agent> [--json]
adapters config validate <agent> [--json]
adapters config mcp list <agent> [--json]
adapters config mcp add <agent> [--scope global|project]
adapters config mcp remove <agent> <server-name> [--scope global|project]
adapters config reload [agent]

Common Config Flags

16.2 `adapters config get <agent> [field]`

Read configuration for an agent. If field is omitted, prints the full merged config. If field is provided (dot-notation), prints only that field's value.

**API mapping:**

16.3 `adapters config set <agent> <field> <value>`

Write a single field to the agent's native config file.

<value> is parsed as JSON if it starts with {, [, ", or is a number/boolean literal. Otherwise it is treated as a plain string.

**API mapping:** adapter.config.setField('claude', 'model', 'claude-sonnet-4-20250514').

**Error behavior:**

• Unknown agent: exit code 3 (AGENT_NOT_FOUND).
• Invalid field/value: exit code 2 (VALIDATION_ERROR).
• File write failure: exit code 7 (CONFIG_ERROR).
• Lock contention: exit code 7 (CONFIG_LOCK_ERROR), message indicates retry.

16.4 `adapters config schema <agent>`

Print the configuration schema for an agent, showing all recognized fields, their types, defaults, and valid ranges.

**API mapping:** adapter.config.schema('claude') returns AgentConfigSchema.

16.5 `adapters config validate <agent>`

Validate the current config file(s) for an agent against the schema. Prints validation results: field-level errors and warnings.

**API mapping:** adapter.config.validate('claude', adapter.config.get('claude')) returns ValidationResult.

16.6 `adapters config mcp list <agent>`

List MCP servers configured for an agent.

**API mapping:** adapter.config.getMcpServers('claude') returns McpServerConfig[].

16.7 `adapters config mcp add <agent>`

Add an MCP server to the agent's config. The CLI prompts for server name, command, args, and environment variables interactively. In non-interactive mode (piped stdin), reads a JSON McpServerConfig from stdin.

**API mapping:** adapter.config.addMcpServer('claude', serverConfig).

**Error behavior:**

• Agent does not support MCP: exit code 6 (CAPABILITY_ERROR).
• Server name already exists: exit code 7 (CONFIG_ERROR).

16.8 `adapters config mcp remove <agent> <server-name>`

Remove an MCP server from the agent's config by name.

**API mapping:** adapter.config.removeMcpServer('claude', 'my-server').

16.9 `adapters config reload [agent]`

**Spec-level addition:** This command is not in the scope document's CLI listing (scope §21) but is specified in 08-config-and-auth.md Section 2 and Section 15.1. It maps to the ConfigManager.reload() method added by that spec.

Invalidate the config cache and re-read from disk. If agent is omitted, reloads all agents.

This is useful when external processes (the agent's own CLI, manual editing) have modified config files since the last read.

**API mapping:** adapter.config.reload('claude') or adapter.config.reload().

16.10 Examples

# Read full config
adapters config get claude

# Read single field
adapters config get claude model

# Set a field
adapters config set claude model claude-sonnet-4-20250514

# View schema
adapters config schema codex

# Validate current config
adapters config validate gemini

# List MCP servers
adapters config mcp list claude

# Remove an MCP server
adapters config mcp remove claude my-custom-server

# Reload after external edit
adapters config reload claude

---

17. `adapters profiles` -- Profile Management

Manage named RunOptions presets. Profiles are stored as JSON files in ~/.adapters/profiles/ (global) or .adapters/profiles/ (project). See 02-run-options-and-profiles.md, Section 10 for the full ProfileManager specification.

17.1 Syntax

adapters profiles list [flags...]
adapters profiles show <name>
adapters profiles set <name> [run-flags...]
adapters profiles delete <name> [flags...]
adapters profiles apply <name>

17.2 `adapters profiles list`

List all available profiles from both global and project directories.

**Flags:**

**Output columns (human mode):**

**API mapping:** adapter.profiles.list({ scope }) returns ProfileEntry[].

17.3 `adapters profiles show <name>`

Display the resolved contents of a profile (merged global + project).

**API mapping:** adapter.profiles.show(name) returns ResolvedProfile.

17.4 `adapters profiles set <name> [run-flags...]`

Create or update a profile. The profile data is derived from the provided run flags. Any flag accepted by adapters run (except per-run ephemeral flags) can be used.

**Per-run ephemeral flags that are rejected** (per 02-run-options-and-profiles.md, Section 10.3):

--cwd, --env, --run-id, --attach, --fork, --no-session, --project-id, --interactive, --quiet.

**Note:** --system and --system-mode are NOT rejected — systemPrompt and systemPromptMode are valid profile fields (spec 02 §10.2).

These flags correspond to RunOptions fields that are per-run ephemeral and excluded from profile storage: cwd, env, runId, attachments, systemPrompt, systemPromptMode, forkSessionId, noSession, projectId, plus CLI-only flags --interactive and --quiet.

**Flags:**

**API mapping:** adapter.profiles.set(name, profileData, { scope }).

**Examples:**

# Create a "fast" profile
adapters profiles set fast --agent claude --model claude-sonnet-4-20250514 --yolo --max-turns 5

# Create a "careful" profile
adapters profiles set careful --agent claude --thinking-effort high --deny

# Create global profile
adapters profiles set shared-fast --scope global --agent gemini --max-tokens 4096

17.5 `adapters profiles delete <name>`

Delete a profile.

**Flags:**

**API mapping:** adapter.profiles.delete(name, { scope }).

17.6 `adapters profiles apply <name>`

Resolve a profile and print the resulting RunOptions values. Does not start a run. Useful for previewing what a profile produces.

**API mapping:** adapter.profiles.apply(name) returns Partial<RunOptions>.

17.7 Error Behavior

• Unknown profile: exit code 9 (PROFILE_NOT_FOUND).
• Invalid profile data: exit code 2 (VALIDATION_ERROR).

---

18. `adapters auth` -- Authentication

Check and guide authentication state for agents. The CLI never writes credentials or modifies auth state -- it only inspects and provides guidance.

18.1 Syntax

adapters auth check [agent]
adapters auth setup <agent>

18.2 `adapters auth check [agent]`

Check authentication state. If agent is omitted, checks all agents.

**Flags:**

**Output (human mode, single agent):**

Agent:    claude
Status:   authenticated
Method:   api-key
Identity: user@example.com
Checked:  2025-01-15T10:30:00Z

**Output (human mode, all agents):**

**API mapping:**

18.3 `adapters auth setup <agent>`

Print setup guidance for authenticating with an agent. Does not perform authentication itself.

**Output:** Structured guidance including:

• Required steps (numbered list).
• Environment variables to set.
• Commands to run.
• Documentation links.
• Platform-specific notes.

**API mapping:** adapter.auth.getSetupGuidance('claude') returns AuthSetupGuidance.

18.4 Error Behavior

• Unknown agent: exit code 3 (AGENT_NOT_FOUND).
• auth check with unauthenticated result: exits with code 0 (the check succeeded; the result is "unauthenticated"). The status is reported in the output.

---

18b. `adapters skill` -- Skill Management

File-convention only (no native harness command). Skills are folders containing a SKILL.md plus assets, installed under per-harness conventions.

adapters skill list <agent> [--global|--project]
adapters skill add <agent> <source-folder> [--name <n>] [--force] [--global|--project]
adapters skill remove <agent> <name> [--global|--project]
adapters skill where <agent>
adapters skill agents           # list supported harnesses

Supported harnesses: claude, codex, cursor, opencode, gemini, copilot. Paths: $HOME/.<agent>/skills/ (global) or <cwd>/.<agent>/skills/ (project).

---

18c. `adapters agent` -- Sub-agent Management

File-convention only. Copies agent definition files (markdown/yaml/json) into per-harness sub-agent directories.

adapters agent list <agent> [--global|--project]
adapters agent add <agent> <source> [--name <n>] [--force] [--global|--project]
adapters agent remove <agent> <name> [--global|--project]
adapters agent where <agent>
adapters agent agents           # list supported harnesses

Supported: claude, claude-code, codex, cursor, opencode. Paths: $HOME/.<agent>/agents/ (global) or <cwd>/.<agent>/agents/ (project).

References:

• Claude: https://code.claude.com/docs/en/sub-agents
• Codex: https://developers.openai.com/codex/subagents#custom-agents

---

18d. `adapters hooks` -- Hook Management

Manage hook registrations and dispatch. Backed by HookConfigManager in core.

adapters hooks <agent> discover                      # native hook types
adapters hooks <agent> list
adapters hooks <agent> add <hookType> [--handler builtin|command|script] [--target <t>] [--id <id>] [--global]
adapters hooks <agent> remove <id> [--global]
adapters hooks <agent> set <id> [--priority N] [--enabled true|false] [--target <t>]
adapters hooks <agent> handle <hookType>             # stdin JSON → dispatch → result

Storage: $HOME/.adapters/hooks.json (global), <cwd>/.adapters/hooks.json (project).

---

19. `adapters init` -- Project Initialization

Create the .adapters/ directory in the current working directory with default configuration.

19.1 Syntax

adapters init [flags...]

19.2 Behavior

1. Creates .adapters/ in the current directory (or the directory specified by --project-dir). 2. Creates .adapters/config.json with an empty object {}. 3. Creates .adapters/profiles/ directory. 4. Prints confirmation to stdout. 5. If .adapters/ already exists, prints a message and exits with code 0 (idempotent).

19.3 Flags

---

20. Signal Handling

The CLI handles process signals for graceful shutdown and run control.

20.1 Unix (macOS, Linux)

20.2 Windows

Windows does not have POSIX signals. The CLI uses alternative mechanisms:

20.3 Zombie Prevention

All spawned child processes are registered in a cleanup list. On Node.js beforeExit and exit events, the CLI sends SIGKILL (Unix) or TerminateProcess (Windows) to any still-running children. This prevents zombie processes.

The grace period for graceful shutdown is configurable via AGENT_MUX_GRACE_PERIOD_MS environment variable (default: 5000ms).

---

21. Environment Variables

The following environment variables are recognized by the CLI. CLI flags take precedence over environment variables.

21.1 Resolution Order

For any configuration value, the resolution order is (highest precedence first):

1. CLI flags (e.g., --config-dir). 2. Environment variables (e.g., AGENT_MUX_CONFIG_DIR). 3. Project config file (.adapters/config.json). 4. Global config file (~/.adapters/config.json). 5. Adapter defaults.

This mirrors the SDK resolution order defined in 01-core-types-and-client.md, Section 4.1.1 and 02-run-options-and-profiles.md, Section 7.

---

22. Shell Completion

The CLI provides shell completion scripts for interactive use.

22.1 Generating Completion Scripts

# Bash
adapters --completions bash > ~/.local/share/bash-completion/completions/adapters
# or
adapters --completions bash >> ~/.bashrc

# Zsh
adapters --completions zsh > ~/.zfunc/_amux
# or add to .zshrc: fpath=(~/.zfunc $fpath); autoload -Uz compinit; compinit

# Fish
adapters --completions fish > ~/.config/fish/completions/adapters.fish

# PowerShell
adapters --completions powershell >> $PROFILE

22.2 Completion Scope

Completions are provided for:

• Top-level commands (run, install, adapters, capabilities, models, plugin, mcp, sessions, cost, config, profiles, auth, init).
• Subcommands (e.g., plugin list, mcp install, config mcp add).
• Flag names and their valid values (e.g., --agent completes to registered agent names, --thinking-effort completes to low, medium, high, max).
• Agent names (positional argument for many commands).
• Model IDs (for --model flag, dynamically queried from the model registry).
• Profile names (for --profile flag).

---

23. Error Output Format

23.1 Human-Readable Errors

In human mode, errors are printed to stderr with the following format:

error: <message>
  code: <ErrorCode>
  agent: <agent> (when applicable)
  hint: <actionable guidance> (when available)

Example:

error: Agent 'cursor' does not support native plugin CLI commands
  code: CAPABILITY_ERROR
  agent: cursor
  hint: Agents with native plugin CLI: claude, gemini, codex, copilot, opencode

23.2 JSON Errors

In JSON mode (--json), errors are emitted as a JSON object to stdout:

{
  "ok": false,
  "error": {
    "code": "CAPABILITY_ERROR",
    "message": "Agent 'cursor' does not support native plugin CLI commands",
    "agent": "cursor",
    "recoverable": false
  }
}

23.3 JSONL Run Errors

During adapters run --json, errors appear as typed events in the JSONL stream:

{"type":"error","runId":"01J...","agent":"claude","timestamp":1718000000000,"code":"AUTH_ERROR","message":"Authentication required","recoverable":false}

The type field matches the error event types defined in 04-agent-events.md: auth_error, rate_limit_error, context_exceeded, crash, error.

23.4 Canonical Error Codes

All error codes used by the CLI are defined in 01-core-types-and-client.md, Section 3.1:

---

24. Platform-Specific Notes

24.1 Windows

• **Signal handling**: Windows lacks POSIX signals. See Section 20.2 for the alternative mechanisms used.
• **TTY detection**: process.stdin.isTTY and process.stdout.isTTY work correctly on Windows terminals (cmd.exe, PowerShell, Windows Terminal). ConPTY is used for PTY-based agents.
• **PTY support**: node-pty uses ConPTY on Windows 10 1809+ for agents requiring PTY (OpenClaw, some interactive modes).
• **Path handling**: All internal paths use forward slashes. CLI output uses the platform-native separator. Config file paths (--config-dir, --project-dir) accept both forward and backslashes on Windows.
• **Color support**: ANSI color codes are supported in Windows Terminal and PowerShell 7+. Legacy cmd.exe may not render colors correctly; --no-color is recommended in that environment.
• **Hermes on Windows**: Hermes requires WSL2 on Windows. The hermes adapter detects whether WSL2 is available and spawns hermes through wsl when running on native Windows. If WSL2 is not detected, the adapter reports installed: false with guidance to install WSL2.
• **omp on Windows**: omp has partial Windows support (see adapters-scope.md, Section 23). Some features may not work correctly on Windows.
• **Shell completion**: PowerShell completion is supported via Register-ArgumentCompleter. See Section 22.1.

24.2 macOS

• **Homebrew**: Several agents offer Homebrew install methods (claude, opencode). The adapters install command prefers Homebrew on macOS when available.
• **Config paths**: Global config at ~/ ($HOME, typically /Users/<user>/).

24.3 Linux

• **XDG compliance**: Some agents store config in XDG-compliant locations (e.g., ~/.config/ for Gemini, Copilot, OpenCode). The adapters handle this transparently.
• **Config paths**: Global config at ~/ ($HOME, typically /home/<user>/).

---

25. Command Summary

Quick reference of all commands and their SDK method mappings.

---

26. Version and Help

# Print version
adapters --version
adapters -V

# Print help
adapters --help
adapters -h

# Command-specific help
adapters run --help
adapters plugin --help
adapters mcp --help

--version prints the package version of @a5c-ai/adapters-cli and exits with code 0.

--help prints the usage summary for the command or subcommand and exits with code 0. Help text includes a brief description, syntax, available flags, and examples.

---

27. Type Reference Summary

This section lists the key types referenced throughout the CLI spec and where they are defined.

---

Implementation Status (2026-04-12)

Five command surfaces have landed that extend the original spec. All are implemented under packages/cli/src/commands/.

`adapters install <agent> [--version V] [--force] [--dry-run] [--json]`

Invokes the adapter's install(). Emits an InstallResult. Non-zero exit if ok is false. Used by the Dockerfile with HARNESSES=<csv> to pre-install harnesses into an image.

`adapters update <agent> [--dry-run] [--json]`

Invokes the adapter's update(). Same result shape.

`adapters detect [<agent> | --all] [--json]`

Invokes detectInstallation(). With --all iterates every registered adapter; with a specific agent returns one record. Prints installed, version, path, notes.

`adapters detect-host [--json]`

Calls client.detectHost() and prints HostHarnessInfo { agent, confidence, source, matchedSignals } or "no harness detected". Confidence: high (≥ 2 env signals), medium (1 env signal), low (argv heuristic only).

`adapters remote install|update <host> [--mode ssh|docker|k8s|local] [--harness <agent>] [--force] [--json]`

Four-step bootstrap over the chosen invocation mode:

1. Probe adapters --version on target. 2. If missing or update/--force: npm install -g @a5c-ai/adapters-cli (or npm update -g). 3. adapters install <harness> (or adapters update <harness>) on target. 4. Verify with adapters detect --all --json.

Default --mode is ssh when <host> is given, else local. Default --harness is claude-code.

Global flags actually accepted

From packages/cli/src/parse-args.ts the recognized globals are: --agent/-a, --model/-m, --json, --debug, --config-dir, --project-dir, --no-color, --version/-V, --help/-h, --completions <shell>. The top-level commands: run, install, uninstall, update, detect, detect-host, remote, adapters, capabilities, models, plugin, mcp, sessions, cost, config, profiles, auth, init, version, help.