<!--
doc_metadata:
  runtime_scope: [local, claude, codex, opencode]
-->

# CLI Reference

Complete command reference for the Ouroboros CLI.

## Installation

> For install instructions, onboarding, and first-run setup, see **[Getting Started](getting-started.md)**.

## Usage

```bash
ouroboros [OPTIONS] COMMAND [ARGS]...
```

### Global Options

| Option | Description |
|--------|-------------|
| `-V, --version` | Show version and exit |
| `--install-completion` | Install shell completion |
| `--show-completion` | Show shell completion script |
| `--help` | Show help message |

---

## Quick Start

> For the full first-run walkthrough (interview → seed → execute), see **[Getting Started](getting-started.md)**.

---

## Commands Overview

| Command | Description |
|---------|-------------|
| `setup` | Detect runtimes and configure Ouroboros for your environment |
| `init` | Start interactive interview to refine requirements |
| `auto` | Run bounded goal → A-grade Seed → execution handoff pipeline |
| `job` | Inspect detached job status, waits, results, and event streams |
| `run` | Execute Ouroboros workflows |
| `qa` | Evaluate an artifact against a natural-language quality bar |
| `cancel` | Cancel stuck or orphaned executions |
| `config` | Manage Ouroboros configuration (show, switch backend, set values) |
| `uninstall` | Cleanly remove all Ouroboros configuration from your system |
| `status` | Check Ouroboros system status |
| `tui` | Interactive TUI monitor for real-time workflow monitoring |
| `monitor` | Shorthand for `tui monitor` |
| `mcp` | MCP server commands for Claude Desktop and other MCP clients |

---


## `ouroboros auto`

Run the full-quality auto pipeline from a single goal. This is the CLI equivalent of `ooo auto` in agent sessions.

```bash
ouroboros auto "Build a local-first habit tracker CLI"
```

**Options:**

| Option | Description |
|--------|-------------|
| `--resume TEXT` | Resume an existing auto session id |
| `--runtime TEXT` | Runtime backend for the **run-handoff** phase. Shipped values: `claude`, `codex`, `opencode`, `hermes`, `gemini`, `goose`, `kiro`, `copilot`, `pi`, `gjc`, `antigravity`, `grok`. Authoring phases (interview, seed generation, seed repair) **always run in-process** inside the Ouroboros MCP server in `ooo auto` flow — see [What `--runtime` controls in `ooo auto`](#what---runtime-controls-in-ooo-auto) below. |
| `--max-interview-rounds INTEGER` | Maximum automatic interview rounds; prevents unbounded interview loops |
| `--max-repair-rounds INTEGER` | Maximum Seed repair rounds; prevents unbounded repair loops |
| `--skip-run` | Stop after creating an A-grade Seed |
| `--show-ledger` | Print assumptions and non-goals captured during auto convergence |
| `--status` | Print the persisted state for `--resume <id>` without running |

Auto mode starts execution only after the generated Seed reaches A-grade. If a phase times out or hits a hard blocker, the command prints the auto session id and a resume command instead of hanging indefinitely.

### Detached `auto` wait and retrieve

Detached `auto` work is non-terminal tracked background work. Starting it does
not mean the workflow has completed; the returned `job_id` is a handle for a
tracked job whose lifecycle remains observable until it reaches a terminal
state such as `completed`, `failed`, or `cancelled`. Terminal results are read
from persisted job events; the in-memory handle TTL only bounds live registry
cleanup, not completed result retrieval.

CLI users wait and retrieve with the standard job surfaces:

```bash
ouroboros job status JOB_ID
ouroboros job wait JOB_ID
ouroboros job result JOB_ID
ouroboros job events JOB_ID --since 0 --limit 100
```

`ouroboros job events` is the low-cost external observability surface for
dashboards and schedulers. It opens `~/.ouroboros/ouroboros.db` read-only,
does not create schema or write WAL/checkpoint state, and prints cursor-paged
JSON for the job aggregate. Pass the returned `cursor` back as `--since` on
the next poll.

MCP clients use the matching job tools:

```text
ouroboros_job_status(job_id="JOB_ID")
ouroboros_job_wait(job_id="JOB_ID")
ouroboros_job_result(job_id="JOB_ID")
```

While a detached job is still running, its `running` lifecycle status is
non-terminal tracked background work. Treat status output as progress, not as
the final `auto` result. Retrieve the result only after the job reaches a
terminal lifecycle status. When CLI status reports `completed`,
`ouroboros job result JOB_ID` retrieves the stable completed `auto` result for
that job handle. When CLI status reports `failed`, the job is terminal and
still observable; `ouroboros job result JOB_ID` returns the stable failure
output or error details for that job handle, not a successful `auto` result.
Next steps are to inspect `ouroboros job status JOB_ID` and
`ouroboros job result JOB_ID`, then resume or retry from the surfaced auto
session, execution, or lineage handle when one is present.
When CLI status reports `cancelled`, the job is terminal and still observable;
`ouroboros job result JOB_ID` returns stable cancellation output or error
details for that job handle with the cancellation reason when one is available,
not a successful `auto` result. Next steps are to inspect
`ouroboros job status JOB_ID` and `ouroboros job result JOB_ID`, then restart
the detached auto flow or resume from the surfaced auto session, execution, or
lineage handle when one is present. The CLI prints the stable cancellation
output and exits non-zero because the terminal result is an error result.
When a terminal job is older than the in-memory handle TTL,
`ouroboros job result JOB_ID` still retrieves the persisted terminal result for
that job handle. `ouroboros job status JOB_ID` reports the stored terminal
lifecycle status, and result retrieval returns the durable result artifact rather
than an expiration error. Unknown or otherwise unavailable handles fail through
the CLI with a non-zero status and through MCP with an error response.
When CLI status cannot resolve the supplied handle, treat the detached work as
`invalid` or unavailable rather than as running or completed. The stable
observable status is the non-zero CLI exit plus the human-readable error for
that handle. Next steps are to check the copied `job_id`, inspect any surfaced
auto session, execution, or lineage handle, then restart the detached auto flow
when no valid handle can be recovered.

Example invalid CLI retrieval output:

```bash
$ ouroboros job result missing_detached_auto
Job handle not found: missing_detached_auto. Result unavailable.
```

Example completed CLI retrieval output:

```bash
$ ouroboros job result job_auto_docs_done
detached auto result artifact: seed.yaml
```

Example cancelled CLI retrieval output:

```bash
$ ouroboros job result job_auto_docs_cancelled
detached auto cancelled: user requested cancellation
```

Example expired CLI retrieval output:

```bash
$ ouroboros job result job_auto_docs_expired
detached auto result artifact: expired seed.yaml
```

> **`ooo auto` does not accept `--opencode-mode`.** OpenCode mode is
> selected once at install time via `ouroboros setup --opencode-mode
> <plugin|subprocess>` (recorded in `~/.ouroboros/config.yaml`); the auto
> CLI reads that persisted value but never exposes it as a flag.

### What `--runtime` controls in `ooo auto`

`ooo auto` runs four logical phases. `--runtime` selects the backend for the
**run-handoff** phase only. The three preceding *authoring* phases
(interview, seed generation, seed repair) **always run in-process** inside
the Ouroboros MCP server in `ooo auto` flow, regardless of `--runtime` or
the persisted `opencode_mode`. Both auto entry points
([`cli/commands/auto.py`](https://github.com/Q00/ouroboros/blob/main/src/ouroboros/cli/commands/auto.py)
and [`mcp/tools/auto_handler.py`](https://github.com/Q00/ouroboros/blob/main/src/ouroboros/mcp/tools/auto_handler.py))
demote a persisted `opencode_mode == "plugin"` to `subprocess` before
constructing the authoring handlers, because a `_subagent` envelope would
have no receiver outside an active OpenCode bridge plugin session.

| Phase                  | Handler                                                | `ooo auto` behaviour                                                                                                                                                       |
| ---------------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1. Interview authoring | `mcp.tools.authoring_handlers.InterviewHandler`        | In-process for every `--runtime` value. `opencode + plugin` is demoted to `subprocess` before the handler is constructed, so authoring never short-circuits to the bridge. |
| 2. Seed generation     | `mcp.tools.authoring_handlers.GenerateSeedHandler`     | Same rule as interview authoring — always in-process for `ooo auto`.                                                                                                       |
| 3. Seed repair         | `auto.seed_repairer.SeedRepairer`                      | In-process; never dispatched.                                                                                                                                               |
| 4. Run handoff         | `mcp.tools.execution_handlers.StartExecuteSeedHandler` | Routed through the runtime adapter selected by `--runtime`. **CLI entry point** (`ouroboros auto`) also demotes `opencode + plugin` to `subprocess` here, because the standalone CLI process is not the OpenCode session that owns the bridge plugin. **MCP entry point** (`mcp/tools/auto_handler.py`) keeps `plugin` for run-handoff because it is invoked from inside the OpenCode session. |

> **Why this matters:** `--runtime codex` does **not** mean "Codex performs
> the interview". The Ouroboros MCP server still owns the first authoring
> question and may time out before any Codex subagent is invoked. If
> `interview.start` blocks, the timeout originates from the in-process
> authoring path, not from the Codex CLI. Set realistic expectations when
> chaining `ooo auto` from external gateways.

#### Underlying MCP-handler dispatch (outside `ooo auto`)

The same `InterviewHandler` / `GenerateSeedHandler` classes can short-circuit
to a `_subagent` envelope **only when called directly from inside an
active OpenCode bridge plugin session** — not from `ooo auto`. The dispatch
gate lives in
[`should_dispatch_via_plugin()`](https://github.com/Q00/ouroboros/blob/main/src/ouroboros/mcp/tools/subagent.py)
and is exhaustively tested in
`tests/unit/mcp/tools/test_subagent.py::TestShouldDispatchViaPlugin`. This
truth table describes the gate function alone, not the auto flow:

| `runtime_backend` | `opencode_mode` | Gate result        |
| ----------------- | --------------- | ------------------ |
| `claude`          | (any)           | False (in-process) |
| `codex`           | (any)           | False (in-process) |
| `hermes`          | (any)           | False (in-process) |
| `gemini`          | (any)           | False (in-process) |
| `kiro`            | (any)           | False (in-process) |
| `copilot`         | (any)           | False (in-process) |
| `opencode`        | `subprocess`    | False (in-process) |
| `opencode`        | (unset/None)    | False (in-process — safe default) |
| `opencode`        | `plugin`        | True (dispatched via `_subagent`) — reachable from inside an OpenCode bridge plugin session, **not** from `ooo auto` |

---

## `ouroboros setup`

Detect available runtime backends and configure Ouroboros for your environment.

Ouroboros supports multiple runtime backends via a pluggable `AgentRuntime` protocol. The `setup` command auto-detects
which runtimes are available in your PATH (including Claude Code, Codex CLI, OpenCode, Hermes, Gemini, Kiro, Copilot, Goose, Pi, and GJC) and
configures `orchestrator.runtime_backend` accordingly. Additional runtimes can be registered
by implementing the protocol — see [Architecture](architecture.md#how-to-add-a-new-runtime-adapter).

```bash
ouroboros setup [OPTIONS]
```

**Options:**

| Option | Description |
|--------|-------------|
| `-r, --runtime TEXT` | Runtime backend to configure. Shipped values: `claude`, `codex`, `opencode`, `hermes`, `gemini`, `goose`, `kiro`, `copilot`, `pi`, `gjc`, `antigravity`, `grok`. Auto-detected if omitted |
| `--opencode-mode TEXT` | OpenCode integration mode: `plugin` (default, recommended — bridge plugin for interactive sessions) or `subprocess` (headless/CI). Mutually exclusive — see [OpenCode runtime guide](runtime-guides/opencode.md#configuration) |
| `--non-interactive` | Skip interactive prompts (for scripted installs) |
| `--mcp-mode TEXT` | Codex MCP config mode: `auto` (default), `preserve`, or `stdio` |

For Pi, setup also installs `~/.pi/agent/extensions/ouroboros-ooo-bridge.ts`.
Restart Pi or run `/reload` and interactive Pi/roach-pi sessions can dispatch
`ooo ...` commands into Ouroboros through the shared skill router.
For GJC, setup installs the GJC-side `ooo` bridge extension into
`<agent-dir>/extensions` and a renderer-generated skill capability guide into
`<agent-dir>/rules/ouroboros-skill-capability-guide.md`. Interactive GJC
sessions can dispatch `ooo ...` commands into Ouroboros after the extension is
loaded.

**Examples:**

```bash
# Auto-detect runtimes and configure interactively
ouroboros setup

# Explicitly select Codex CLI as runtime backend
ouroboros setup --runtime codex

# Explicitly select Claude Code as runtime backend
ouroboros setup --runtime claude

# Explicitly select Kiro CLI as runtime backend (writes ~/.kiro/settings/mcp.json)
ouroboros setup --runtime kiro

# Non-interactive setup (for CI or scripted installs)
ouroboros setup --non-interactive
```

**What setup does:**

- Scans PATH for `claude`, `codex`, `opencode`, `hermes`, `gemini`, `kiro-cli`, `copilot`, `goose`, `pi`, and `gjc` CLI binaries
- Prompts you to select a runtime if multiple are found (or auto-selects if only one)
- Writes `orchestrator.runtime_backend` to `~/.ouroboros/config.yaml`
- For Claude Code: registers the MCP server in `~/.claude/mcp.json`
- For Codex CLI: sets `orchestrator.codex_cli_path` and `llm.backend: codex` in `~/.ouroboros/config.yaml`
- For Codex CLI: installs managed Ouroboros rules into `~/.codex/rules/`
- For Codex CLI: installs managed Ouroboros skills into `~/.codex/skills/`
- For Codex CLI: registers the Ouroboros MCP/env block in `~/.codex/config.toml` when absent, refreshes setup-managed stdio blocks, and preserves user-managed URL/custom blocks by default
- For Codex CLI: installs managed `~/.codex/ouroboros-*.config.toml` profile-v2 anchors on current Codex releases, or legacy `[profiles.ouroboros-*]` anchors when the detected CLI still requires them
- For OpenCode: registers the Ouroboros MCP server in OpenCode's configuration
- For OpenCode (plugin mode): installs the bridge plugin into `<opencode_config_dir>/plugins/ouroboros-bridge/`
- For OpenCode: installs the runtime skill capability guide into global `AGENTS.md` in the active OpenCode config directory
- For Gemini CLI: installs the runtime skill capability guide into `~/.gemini/GEMINI.md`
- For Kiro CLI: sets `orchestrator.kiro_cli_path` and `llm.backend: kiro` in `~/.ouroboros/config.yaml`, and registers the Ouroboros MCP server in `~/.kiro/settings/mcp.json` with `OUROBOROS_RUNTIME=kiro` / `OUROBOROS_LLM_BACKEND=kiro` baked into the entry's `env` so `ooo <skill>` shortcuts route to the Kiro adapter on the very next `kiro-cli chat`. The detector prefers the resolved `ouroboros` binary over `uvx` to stay within Kiro's MCP init timeout
- For Kiro CLI: installs the runtime skill capability guide into `~/.kiro/steering/ouroboros-skill-capability-guide.md`
- For Copilot CLI: installs the runtime skill capability guide into `~/.copilot/ouroboros-instructions/AGENTS.md` and configures Ouroboros-launched Copilot child sessions to read it via `COPILOT_CUSTOM_INSTRUCTIONS_DIRS`
- For GJC: sets `orchestrator.gjc_cli_path` and `llm.backend: gjc` in `~/.ouroboros/config.yaml`
- For GJC: installs the `ooo` bridge extension into `<agent-dir>/extensions` and the renderer-generated skill capability guide into `<agent-dir>/rules/ouroboros-skill-capability-guide.md`

> **Codex config split:** put persistent Ouroboros per-role model overrides in `~/.ouroboros/config.yaml` (`clarification.default_model`, `llm.qa_model`, `evaluation.semantic_model`, `consensus.models`, `consensus.advocate_model`, `consensus.devil_model`, `consensus.judge_model`). `~/.codex/config.toml` is only the Codex MCP/env hookup file used by setup on current Codex releases; profile anchors live in `~/.codex/<profile>.config.toml`. If you run a long-lived URL-based Ouroboros MCP server, setup preserves that user-managed entry in the default `--mcp-mode auto`; use `--mcp-mode stdio` only when you intentionally want setup to replace it.

### Brownfield Subcommands

`ouroboros setup` also includes brownfield repository registration helpers:

```bash
ouroboros setup scan [SCAN_ROOT]
ouroboros setup list
ouroboros setup default
```

`ouroboros setup scan [SCAN_ROOT]` walks `scan_root` for valid seed git repositories and worktrees. When `SCAN_ROOT` is omitted, `scan_root` defaults to the current user's home directory. The filesystem walk is bounded to `scan_root`: dot-prefixed directories and known noisy directories such as `node_modules` are not walked as seed locations. Local repos, repos without remotes, and repos whose remotes are not named `origin` are all eligible.

Linked worktree expansion has a different boundary. For each normal repo root found under `scan_root` with a `.git` directory, Ouroboros runs `git worktree list --porcelain` and may register those linked worktrees even when their paths are outside `scan_root`, as long as Git reports them and the paths still exist. A linked worktree found under `scan_root` with a `.git` file is registered itself, but it is not used to register its main worktree or sibling worktrees outside `scan_root`. This keeps narrow scans scoped when a user intentionally passes one worktree as AI context. Existing registrations and default selections are preserved by upsert.

---

## `ouroboros init`

Start interactive interview to refine requirements (Big Bang phase).

**Shorthand:** `ouroboros init "context"` is equivalent to `ouroboros init start "context"`.
When the first argument is not a known subcommand (`start`, `list`), it is treated as the context for `init start`.

### `init start`

Start an interactive interview to transform vague ideas into clear, executable requirements.

```bash
ouroboros init [start] [OPTIONS] [CONTEXT]
```

**Arguments:**

| Argument | Description |
|----------|-------------|
| `CONTEXT` | Initial context or idea (interactive prompt if not provided) |

**Options:**

| Option | Description |
|--------|-------------|
| `-r, --resume TEXT` | Resume an existing interview by ID |
| `--state-dir DIRECTORY` | Custom directory for interview state files |
| `-o, --orchestrator` | Use Claude Code for the interview/seed flow; combine with `--runtime` to choose the workflow handoff backend |
| `--runtime TEXT` | Agent runtime backend for the workflow execution step after seed generation. Shipped values: `claude`, `codex`, `opencode`, `hermes`, `gemini`, `goose`, `kiro`, `copilot`, `pi`, `gjc`, `antigravity`, `grok`. Custom adapters registered in `runtime_factory.py` are also accepted. |
| `--llm-backend TEXT` | LLM backend for interview, ambiguity scoring, and seed generation (`claude_code`, `litellm`, `codex`, `copilot`, `opencode`, `gemini`, `goose`, `kiro`, `pi`, `gjc`) |
| `-d, --debug` | Show verbose logs including debug messages |

**Examples:**

```bash
# Shorthand (recommended) -- 'start' subcommand is implied
ouroboros init "I want to build a task management CLI tool"

# Explicit subcommand (equivalent)
ouroboros init start "I want to build a task management CLI tool"

# Start with Claude Code (no API key needed)
ouroboros init --orchestrator "Build a REST API"

# Specify runtime backend for the workflow step
ouroboros init --orchestrator --runtime codex "Build a REST API"

# Use Codex as the LLM backend for interview and seed generation
ouroboros init --llm-backend codex "Build a REST API"

# Resume an interrupted interview
ouroboros init start --resume interview_20260116_120000

# Interactive mode (prompts for input)
ouroboros init
```

### `init list`

List all interview sessions.

```bash
ouroboros init list [OPTIONS]
```

**Options:**

| Option | Description |
|--------|-------------|
| `--state-dir DIRECTORY` | Custom directory for interview state files |

---

## `ouroboros run`

Execute Ouroboros workflows.

**Shorthand:** `ouroboros run seed.yaml` is equivalent to `ouroboros run workflow seed.yaml`.
When the first argument is not a known subcommand (`workflow`, `resume`), it is treated as the seed file for `run workflow`.

**Default mode:** Orchestrator mode is enabled by default. `--no-orchestrator` exists for the legacy standard path, which is still placeholder-oriented.

### `run workflow`

Execute a workflow from a seed file.

```bash
ouroboros run [workflow] [OPTIONS] SEED_FILE
```

**Arguments:**

| Argument | Required | Description |
|----------|----------|-------------|
| `SEED_FILE` | Yes | Path to the seed YAML file |

**Options:**

| Option | Description |
|--------|-------------|
| `-o/-O, --orchestrator/--no-orchestrator` | Use the agent-runtime orchestrator for execution (default: enabled) |
| `--runtime TEXT` | Agent runtime backend override (`claude`, `codex`, `opencode`, `hermes`, `gemini`, `copilot`, `goose`, `kiro`, `pi`, `gjc`, `antigravity`, `grok`). Uses configured default if omitted |
| `-r, --resume TEXT` | Resume a previous orchestrator session by ID |
| `--mcp-config PATH` | Path to MCP client configuration YAML file |
| `--mcp-tool-prefix TEXT` | Prefix to add to all MCP tool names (e.g., `mcp_`) |
| `-s, --sequential` | Execute ACs sequentially instead of in parallel |
| `-n, --dry-run` | Validate seed without executing. **Currently only takes effect with `--no-orchestrator`.** In default orchestrator mode this flag is accepted but has no effect — the full workflow executes |
| `--no-qa` | Skip post-execution QA evaluation |
| `-d, --debug` | Show logs and agent thinking (verbose output) |

**Examples:**

```bash
# Run a workflow (shorthand, recommended)
ouroboros run seed.yaml

# Explicit subcommand (equivalent)
ouroboros run workflow seed.yaml

# Use Codex CLI as the runtime backend
ouroboros run seed.yaml --runtime codex

# With MCP server integration
ouroboros run seed.yaml --mcp-config mcp.yaml

# Resume a previous session
ouroboros run seed.yaml --resume orch_abc123

# Skip post-execution QA
ouroboros run seed.yaml --no-qa

# Debug output
ouroboros run seed.yaml --debug

# Sequential execution (one AC at a time)
ouroboros run seed.yaml --sequential
```

### `run resume`

Resume a paused or failed execution.

> **Current state:** `run resume` is a placeholder helper. For real orchestrator sessions, use `ouroboros run seed.yaml --resume <session_id>`.

```bash
ouroboros run resume [EXECUTION_ID]
```

**Arguments:**

| Argument | Description |
|----------|-------------|
| `EXECUTION_ID` | Execution ID to resume (uses latest if not specified) |

> **Note:** For orchestrator sessions, you can also use:
> ```bash
> ouroboros run seed.yaml --resume <session_id>
> ```

---

## `ouroboros cancel`

Cancel stuck or orphaned executions.

### `cancel execution`

Cancel a specific execution, all running executions, or interactively pick from active sessions.

```bash
ouroboros cancel execution [OPTIONS] [EXECUTION_ID]
```

**Arguments:**

| Argument | Description |
|----------|-------------|
| `EXECUTION_ID` | Session/execution ID to cancel. If omitted, enters interactive mode |

**Options:**

| Option | Description |
|--------|-------------|
| `-a, --all` | Cancel all running/paused executions |
| `-r, --reason TEXT` | Reason for cancellation (default: "Cancelled by user via CLI") |

**Examples:**

```bash
# Interactive mode - list active executions and pick one
ouroboros cancel execution

# Cancel a specific execution by session ID
ouroboros cancel execution orch_abc123def456

# Cancel all running executions
ouroboros cancel execution --all

# Cancel with a custom reason
ouroboros cancel execution orch_abc123 --reason "Stuck for 2 hours"
```

---

## `ouroboros config`

Manage Ouroboros configuration.

Running `ouroboros config` with no subcommand opens the settings GUI, which
includes one-click **routing presets** — multi-LLM stage-routing recommendations
that stage which agent runs each pipeline stage (interview → execute → evaluate
→ reflect). Click a preset, review the per-stage Agent cards, then **Save** to
persist into `orchestrator.runtime_profile.stages`. The shipped presets:

| Preset          | interview   | execute | evaluate    | reflect | Rationale                                                        |
|-----------------|-------------|---------|-------------|---------|------------------------------------------------------------------|
| `All Claude`    | claude      | claude  | claude      | claude  | Single-vendor baseline — one subscription, predictable           |
| `Claude+Verify` | claude      | claude  | antigravity | claude  | Cross-vendor verification — an independent vendor grades the work |
| `Tri-Vendor`    | claude      | claude  | antigravity | grok    | Maximum diversity across generate / verify / diverge             |
| `Codex Core`    | codex       | codex   | claude      | grok    | OpenAI-centric execution with a cross-vendor verify gate         |
| `Frugal Mix`    | antigravity | grok    | antigravity | codex   | Cost/speed-leaning mix (Gemini Flash via `agy`, fast Grok)       |

> The spine of these recommendations is **vendor diversity between the generate
> stage (execute) and the verify stage (evaluate)** — the same principle Ouroboros
> already encodes in `consensus.diversity_required`. A preset may reference a
> backend whose CLI is not installed; staging still works and the per-card
> warning flags it. Pick the preset closest to your subscriptions, then tune
> individual cards. Model-tier presets (Frugal / Balanced / Frontier) sit in a
> separate row and stage per-stage models rather than backends.

### `config show`

Display current configuration summary, or a specific section.

```bash
ouroboros config show [SECTION]
```

**Arguments:**

| Argument | Description |
|----------|-------------|
| `SECTION` | Configuration section to display (e.g., `orchestrator`, `llm`, `consensus`) |

**Examples:**

```bash
# Show configuration summary (backend, CLI path, DB, log level)
ouroboros config show

# Show only orchestrator section
ouroboros config show orchestrator
```

### `config backend`

Show or switch the runtime backend. This sets both `orchestrator.runtime_backend` and `llm.backend` together — they are always kept in sync for simplicity. Advanced users can decouple them with `config set`.

```bash
ouroboros config backend [BACKEND]
```

**Arguments:**

| Argument | Description |
|----------|-------------|
| `BACKEND` | Backend to switch to: `claude`, `codex`, `gemini`, `hermes`, or `goose`. Omit to show current. For `opencode`, use `ouroboros setup` instead |

**Examples:**

```bash
# Show current backend
ouroboros config backend

# Switch to Codex CLI
ouroboros config backend codex

# Switch to Claude Code
ouroboros config backend claude

# Switch to Hermes
ouroboros config backend hermes
```

### `config init`

Initialize Ouroboros configuration.

```bash
ouroboros config init
```

Creates `~/.ouroboros/config.yaml` and `~/.ouroboros/credentials.yaml` with default templates. Sets `chmod 600` on `credentials.yaml`. If the files already exist they are not overwritten.

### `config set`

Set a configuration value using dot notation.

```bash
ouroboros config set KEY VALUE
```

**Arguments:**

| Argument | Required | Description |
|----------|----------|-------------|
| `KEY` | Yes | Configuration key (dot notation) |
| `VALUE` | Yes | Value to set |

**Examples:**

```bash
# Change log level
ouroboros config set logging.level debug

# Override LLM backend separately from runtime backend
ouroboros config set llm.backend litellm
```

### `config validate`

Validate current configuration. Checks that the runtime backend is supported and the CLI binary path exists.

```bash
ouroboros config validate
```

---


## `ouroboros codex`

Manage Codex-specific Ouroboros integration artifacts.

### `codex refresh`

Refresh the packaged Codex-side Ouroboros rules and skills without changing MCP or Ouroboros config files.

```bash
ouroboros codex refresh
```

This command updates packaged `~/.codex/rules/ouroboros*.md` and `~/.codex/skills/ouroboros-*` artifacts. It does not modify `~/.codex/config.toml` or `~/.ouroboros/config.yaml`. It intentionally does not prune extra `ouroboros-*` files because prefix ownership can include user-managed artifacts.

## `ouroboros qa`

Run a general-purpose QA verdict over an artifact using the same implementation
as the `ouroboros_qa` MCP tool.

```bash
ouroboros qa ARTIFACT [OPTIONS]
```

`ARTIFACT` may be literal text or a path to a file. `--reference` and
`--seed-content` accept the same literal-or-file behavior.

**Options:**

| Option | Description |
|--------|-------------|
| `-q, --quality-bar TEXT` | Natural-language description of what PASS means |
| `-t, --artifact-type TEXT` | Artifact type, such as `code`, `api_response`, `document`, `screenshot`, `test_output`, or `custom` |
| `-r, --reference TEXT` | Optional reference text or path for comparison |
| `--pass-threshold FLOAT` | Score threshold for PASS verdict, from `0.0` to `1.0` |
| `--qa-session-id TEXT` | Existing QA session ID for iterative checks |
| `--seed-content TEXT` | Optional Seed YAML text or path for additional context |

**Exit codes:**

| Code | Meaning |
|------|---------|
| `0` | QA completed and the verdict passed |
| `1` | QA handler failed before producing a verdict |
| `2` | QA completed and the verdict did not pass |

## `ouroboros uninstall`

Cleanly remove all Ouroboros configuration from your system. Reverses everything `ouroboros setup` did.

```bash
ouroboros uninstall [OPTIONS]
```

**Options:**

| Option | Description |
|--------|-------------|
| `--keep-data` | Keep entire `~/.ouroboros/` directory (config, credentials, seeds, logs, DB) |
| `--dry-run` | Show what would be removed without actually deleting |
| `-y, --yes` | Skip confirmation prompt |

**Examples:**

```bash
# Interactive uninstall (shows what will be removed, asks for confirmation)
ouroboros uninstall

# Non-interactive
ouroboros uninstall -y

# Preview only
ouroboros uninstall --dry-run

# Remove MCP/artifacts but keep ~/.ouroboros/
ouroboros uninstall --keep-data
```

**What it removes:**

- `ouroboros` entry from `~/.claude/mcp.json`
- `[mcp_servers.ouroboros]` section from `~/.codex/config.toml`
- `~/.codex/rules/ouroboros*.md` and `~/.codex/skills/ouroboros-*`
- `<!-- ooo:START -->` … `<!-- ooo:END -->` block from `CLAUDE.md`
- OpenCode bridge plugin (`<opencode_config_dir>/plugins/ouroboros-bridge/`) and its entry in `opencode.jsonc`
- `.ouroboros/` directory in the current project
- `~/.ouroboros/` directory (unless `--keep-data`)

**What it does NOT remove:**

- The Python package — run `pip uninstall ouroboros-ai` or `uv tool uninstall ouroboros-ai` separately
- The Claude Code plugin — run `claude plugin uninstall ouroboros` separately
- Your project source code or git history

See [UNINSTALL.md](../UNINSTALL.md) for the full guide.

---

## `ouroboros status`

Check Ouroboros system status.

> **Current state:** `status auto`, `status run`, and `status health` are live read-only status surfaces. The `status executions` and `status execution` subcommands still return lightweight placeholder summaries and should not be treated as authoritative orchestration state.

### `status auto`

Show unified `ooo auto` + Ralph handoff status for an auto session.

```bash
ouroboros status auto AUTO_SESSION_ID
```

**Arguments:**

| Argument | Required | Description |
|----------|----------|-------------|
| `AUTO_SESSION_ID` | Yes | Auto session id to inspect, such as `auto_<hex>` |

### `status run`

Build a read-only Run/Stage/Step projection from persisted events. Provide at
least one selector: a positional `RUN_ID` (treated as the execution anchor),
`--execution-id`, or `--session-id`. The command is a thin surface over the
`ouroboros_query_projection` MCP tool — `--json` output is byte-identical to
what the MCP query returns for the same anchor.

```bash
ouroboros status run [RUN_ID] [--session-id TEXT] [--execution-id TEXT] [OPTIONS]
```

**Arguments:**

| Argument | Required | Description |
|----------|----------|-------------|
| `RUN_ID` | No | Positional execution anchor; maps to `execution_id`. Cannot be combined with `--session-id` or a conflicting `--execution-id` |

**Options:**

| Option | Description |
|--------|-------------|
| `--session-id TEXT` | Orchestrator session ID to project; required unless `RUN_ID` or `--execution-id` is provided. May be combined with `--execution-id` when the MCP projection handler needs session narrowing |
| `--execution-id TEXT` | Execution aggregate ID to project; required unless `RUN_ID` or `--session-id` is provided. May be combined with `--session-id` for session narrowing |
| `--seed-id TEXT` | Optional seed ID override for projection labels |
| `--limit INTEGER` | Optional event count safety cap |
| `--json` | Emit machine-readable projection JSON |

**Exit codes** (Wave-1 #946 S2 contract):

| Code | Meaning |
|------|---------|
| `0` | Projection rendered successfully |
| `1` | Generic projection failure surfaced by the MCP handler |
| `2` | Unknown run anchor — no events match the requested `RUN_ID` / selectors |
| `64` | Malformed input — missing selectors or conflicting `RUN_ID` / option combination |

### `status health`

Check local system health. The command validates configuration, checks the configured database path, verifies the effective runtime CLI is reachable after applying `OUROBOROS_AGENT_RUNTIME` / `OUROBOROS_RUNTIME` and runtime-specific `OUROBOROS_*_CLI_PATH` overrides, and confirms that credentials for the active LLM provider are present without printing key material. CLI-authenticated backends such as Copilot are reported as local CLI authentication rather than requiring an API key.

```bash
ouroboros status health
```

`status health` exits with status `0` when no check is `error`; it exits with status `1` if any check is `error`. Warnings, such as a missing database file that will be created on first run or an empty template credential value, are rendered in the table but do not fail the command.

**Representative Output:**

```
                   System Health
+--------------------------------------------+---------+
| Name                                       | Status  |
+--------------------------------------------+---------+
| Configuration — ~/.ouroboros/config.yaml   |   ok    |
| Database — data/ouroboros.db (...)         |   ok    |
| Runtime backend — claude: /usr/bin/claude  |   ok    |
| Credentials — anthropic key present        |   ok    |
+--------------------------------------------+---------+
```

### `status executions`

List recent executions with status information.

```bash
ouroboros status executions [OPTIONS]
```

**Options:**

| Option | Description |
|--------|-------------|
| `-n, --limit INTEGER` | Number of executions to show (default: 10) |
| `-a, --all` | Show all executions |

**Examples:**

```bash
# Show last 10 executions
ouroboros status executions

# Show last 5 executions
ouroboros status executions -n 5

# Show all executions
ouroboros status executions --all
```

### `status execution`

Show details for a specific execution.

```bash
ouroboros status execution [OPTIONS] EXECUTION_ID
```

**Arguments:**

| Argument | Required | Description |
|----------|----------|-------------|
| `EXECUTION_ID` | Yes | Execution ID to inspect |

**Options:**

| Option | Description |
|--------|-------------|
| `-e, --events` | Show execution events |

**Examples:**

```bash
# Show execution details
ouroboros status execution exec_abc123

# Show execution with events
ouroboros status execution --events exec_abc123
```

---

## `ouroboros tui`

Interactive TUI monitor for real-time workflow monitoring.

> **Equivalent invocations:** `ouroboros tui` (no subcommand), `ouroboros tui monitor`, and `ouroboros monitor` are all equivalent — they all launch the TUI monitor.

### `tui monitor`

Launch the interactive TUI monitor to observe workflow execution in real-time.

```bash
ouroboros tui [monitor] [OPTIONS]
```

**Options:**

| Option | Description |
|--------|-------------|
| `--db-path PATH` | Path to the Ouroboros database file (default: `~/.ouroboros/ouroboros.db`) |
| `--backend TEXT` | TUI backend to use: `python` (Textual, default) or `slt` (native Rust binary) |

**Examples:**

```bash
# Launch TUI monitor (default Textual backend)
ouroboros tui monitor

# Monitor with a specific database file
ouroboros tui monitor --db-path ~/.ouroboros/ouroboros.db

# Use the native SLT backend (requires ouroboros-tui binary)
ouroboros tui monitor --backend slt
```

> **Note:** The `slt` backend requires the `ouroboros-tui` binary in your PATH. Install it with:
> ```bash
> cd crates/ouroboros-tui && cargo install --path .
> ```

**TUI Screens:**

| Key | Screen | Description |
|-----|--------|-------------|
| `1` | Dashboard | Overview with phase progress, drift meter, cost tracker |
| `2` | Execution | Execution details, timeline, phase outputs |
| `3` | Logs | Filterable log viewer with level filtering |
| `4` | Debug | State inspector, raw events, configuration |
| `s` | Session Selector | Browse and switch between monitored sessions |
| `e` | Lineage | View evolutionary lineage across generations (evolve/ralph) |

**Keyboard Shortcuts:**

| Key | Action |
|-----|--------|
| `1-4` | Switch to numbered screen |
| `s` | Session Selector |
| `e` | Lineage view |
| `q` | Quit |
| `p` | Pause execution |
| `r` | Resume execution |
| Up/Down | Scroll |

---

## `ouroboros mcp`

MCP (Model Context Protocol) server commands for Claude Desktop and other MCP-compatible clients.

### `mcp serve`

Start the MCP server to expose Ouroboros tools to Claude Desktop or other MCP clients.

```bash
ouroboros mcp serve [OPTIONS]
```

**Options:**

| Option | Description |
|--------|-------------|
| `-h, --host TEXT` | Host to bind to (default: localhost) |
| `-p, --port INTEGER` | Port to bind to (default: 8080) |
| `-t, --transport TEXT` | Transport type: `stdio`, `sse`, or `streamable-http` (default: stdio). Note: `http` is only a client config alias for outbound MCP connections and is NOT a valid serve transport. |
| `--db TEXT` | Path to the EventStore database file |
| `--runtime TEXT` | Agent runtime backend for orchestrator-driven tools (`claude`, `codex`, `opencode`, `hermes`, `gemini`, `copilot`, `goose`, `kiro`, `pi`, `gjc`, `antigravity`, `grok`). Affects which tool variants are instantiated |
| `--llm-backend TEXT` | LLM backend for interview/seed/evaluation tools (`claude_code`, `litellm`, `codex`, `copilot`, `opencode`, `gemini`, `goose`, `kiro`, `pi`, `gjc`). Affects which tool variants are instantiated |

**Examples:**

```bash
# Start with stdio transport (for Claude Desktop)
ouroboros mcp serve

# Start with SSE transport on custom port
ouroboros mcp serve --transport sse --port 9000

# Start with streamable HTTP transport on custom port
ouroboros mcp serve --transport streamable-http --port 9000

# Start with Codex-backed orchestrator tools
ouroboros mcp serve --runtime codex --llm-backend codex

# Start on specific host
ouroboros mcp serve --host 0.0.0.0 --port 8080 --transport sse
```

For serving with streamable HTTP, use `streamable-http`, not `http`. `http` is accepted only in MCP client configuration as a compatibility alias for dialing another server's streamable HTTP endpoint; `mcp serve` uses the precise protocol name so users do not confuse it with a generic HTTP API. Streamable HTTP clients should connect to `http://<host>:<port>/mcp`.

FastMCP caveats: Network serving uses the MCP SDK's FastMCP server. The streamable HTTP path is FastMCP's default `/mcp`. Authentication and rate limiting configured on `MCPServerAdapter` are rejected for FastMCP transports because FastMCP does not pass credentials or stable client identity to handlers; protect `0.0.0.0` binds with normal network controls.

**Startup behavior:**

On startup, `mcp serve` automatically cancels any sessions left in `RUNNING` or `PAUSED` state for more than 1 hour. These are treated as orphaned from a previous crash. Cancelled sessions are reported on stderr for `stdio` and on the console for network transports (`sse`, `streamable-http`). This cleanup is best-effort and does not prevent the server from starting if it fails.

**Claude Desktop / Claude Code CLI Integration:**

`ouroboros setup --runtime claude` writes this automatically to `~/.claude/mcp.json`.
To register manually, add to `~/.claude/mcp.json`:

```json
{
  "mcpServers": {
    "ouroboros": {
      "command": "uvx",
      "args": ["--from", "ouroboros-ai[mcp,claude]", "ouroboros", "mcp", "serve"],
      "timeout": 600
    }
  }
}
```

If Ouroboros is installed directly (not via `uvx`), use:

```json
{
  "mcpServers": {
    "ouroboros": {
      "command": "ouroboros",
      "args": ["mcp", "serve"],
      "timeout": 600
    }
  }
}
```

**Runtime selection** is configured in `~/.ouroboros/config.yaml` (written by `ouroboros setup`):

```yaml
orchestrator:
  runtime_backend: claude   # or "codex", "opencode", "hermes", "gemini", "copilot", "goose", "kiro", "pi", or "gjc"
```

Override per-session with the `OUROBOROS_AGENT_RUNTIME` environment variable if needed.

### `mcp info`

Show MCP server information and available tools.

```bash
ouroboros mcp info [OPTIONS]
```

**Options:**

| Option | Description |
|--------|-------------|
| `--runtime TEXT` | Agent runtime backend for orchestrator-driven tools (`claude`, `codex`, `opencode`, `hermes`, `gemini`, `copilot`, `goose`, `kiro`, `pi`, `gjc`, `antigravity`, `grok`). Affects which tool variants are instantiated |
| `--llm-backend TEXT` | LLM backend for interview/seed/evaluation tools (`claude_code`, `litellm`, `codex`, `copilot`, `opencode`, `gemini`, `goose`, `kiro`, `pi`, `gjc`). Affects which tool variants are instantiated |

**Available Tools:**

| Tool | Description |
|------|-------------|
| `ouroboros_execute_seed` | Execute a seed specification |
| `ouroboros_session_status` | Get the status of a session |
| `ouroboros_query_events` | Query event history |

---

## Typical Workflows

> For first-time setup and the complete onboarding flow, see **[Getting Started](getting-started.md)**.
> For runtime-specific configuration, see the [Claude Code](runtime-guides/claude-code.md), [Codex CLI](runtime-guides/codex.md), [OpenCode](runtime-guides/opencode.md), [Hermes](runtime-guides/hermes.md), [Gemini](runtime-guides/gemini.md), [Kiro CLI](runtime-guides/kiro.md), [GitHub Copilot CLI](runtime-guides/copilot.md), [Pi CLI](runtime-guides/pi.md), and [GJC](runtime-guides/gjc.md) references.

### Cancelling Stuck Executions

```bash
# Interactive: list and pick
ouroboros cancel execution

# Cancel all at once
ouroboros cancel execution --all
```

---

## Environment Variables

The table below covers the most commonly used variables. For the full list — including all per-model overrides (e.g., `OUROBOROS_QA_MODEL`, `OUROBOROS_SEMANTIC_MODEL`, `OUROBOROS_CONSENSUS_MODELS`, etc.) — see [config-reference.md](config-reference.md#environment-variables).

| Variable | Overrides config key | Description |
|----------|----------------------|-------------|
| `ANTHROPIC_API_KEY` | — | Anthropic API key for Claude models |
| `OPENAI_API_KEY` | — | OpenAI API key for LiteLLM / Codex CLI |
| `OPENROUTER_API_KEY` | — | OpenRouter API key for consensus and LiteLLM |
| `OUROBOROS_AGENT_RUNTIME` | `orchestrator.runtime_backend` | Override the runtime backend (`claude`, `codex`, `opencode`, `hermes`, `gemini`, `goose`, `kiro`, `copilot`, `pi`, `gjc`, `antigravity`, `grok`) |
| `OUROBOROS_RUNTIME` | `orchestrator.runtime_backend` (fallback) | Shortcut env var honored by both `orchestrator.runtime_backend` and `llm.backend` resolution when their dedicated env vars are unset |
| `OUROBOROS_KIRO_CLI_PATH` | `orchestrator.kiro_cli_path` | Explicit path to `kiro-cli` binary when it is not on `PATH` |
| `OUROBOROS_AGENT_PERMISSION_MODE` | `orchestrator.permission_mode` | Permission mode for Claude Code / Codex runtimes (no-op for OpenCode) |
| `OUROBOROS_MAX_PARALLEL_WORKERS` | `orchestrator.max_parallel_workers` | Maximum concurrent Acceptance Criteria workers for parallel execution |
| `OUROBOROS_LLM_BACKEND` | `llm.backend` | Override the LLM-only flow backend |
| `OUROBOROS_CLI_PATH` | `orchestrator.cli_path` | Path to the Claude CLI binary |
| `OUROBOROS_CODEX_CLI_PATH` | `orchestrator.codex_cli_path` | Path to the Codex CLI binary |
| `OUROBOROS_OPENCODE_CLI_PATH` | `orchestrator.opencode_cli_path` | Path to the OpenCode CLI binary |
| `OUROBOROS_GJC_CLI_PATH` | `orchestrator.gjc_cli_path` | Explicit path to `gjc` binary when it is not on `PATH` |
| `OUROBOROS_SESSION_WALL_CLOCK_SECONDS` | `runtime_controls.session_wall_clock_seconds` | Override the Auto session wall-clock watchdog budget; `0` disables the watchdog |
| `OUROBOROS_MCP_TOOL_TIMEOUT_SECONDS` | `runtime_controls.mcp_tool_timeout_seconds` | Optional adapter-level MCP timeout; `0` disables the fixed wall-clock cap |
| `OUROBOROS_GENERATION_IDLE_TIMEOUT_SECONDS` | `runtime_controls.generation_idle_timeout_seconds` | Stop an evolve generation after no lineage/execution activity is observed |
| `OUROBOROS_GENERATION_NO_PROGRESS_TIMEOUT_SECONDS` | `runtime_controls.generation_no_progress_timeout_seconds` | Stop an evolve generation after activity continues without material progress |
| `OUROBOROS_GENERATION_SAFETY_TIMEOUT_SECONDS` | `runtime_controls.generation_safety_timeout_seconds` | Optional final hard cap for one generation; `0` disables it |
| `OUROBOROS_WATCHDOG_POLL_SECONDS` | `runtime_controls.watchdog_poll_seconds` | EventStore polling interval for generation watchdog decisions |

---

## Configuration Files

Ouroboros stores configuration in `~/.ouroboros/`:

| File | Description |
|------|-------------|
| `config.yaml` | Main configuration — see [config-reference.md](config-reference.md) for all options |
| `credentials.yaml` | API keys (chmod 600; created by `ouroboros config init`) |
| `ouroboros.db` | SQLite database for event sourcing (actual path: `~/.ouroboros/ouroboros.db`; the `persistence.database_path` config key is currently not honored — see [config-reference.md](config-reference.md#persistence)) |
| `logs/ouroboros.log` | Log output (path configurable via `logging.log_path`) |

---

## Exit Codes

| Code | Description |
|------|-------------|
| `0` | Success |
| `1` | General error |
