CLI Reference

Complete command reference for the Ouroboros CLI.

Installation

For install instructions, onboarding, and first-run setup, see Getting Started.

Usage

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.

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
`run`	Execute Ouroboros workflows
`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.

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`, `kiro`, `copilot`. 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` 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.

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 and 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() 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 (currently: Claude Code, Codex CLI, OpenCode) and configures orchestrator.runtime_backend accordingly. Additional runtimes can be registered by implementing the protocol — see Architecture.

ouroboros setup [OPTIONS]

Options:

Option	Description
`-r, --runtime TEXT`	Runtime backend to configure. Shipped values: `claude`, `codex`, `opencode`, `hermes`, `gemini`, `kiro`. 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
`--non-interactive`	Skip interactive prompts (for scripted installs)
`--mcp-mode TEXT`	Codex MCP config mode: `auto` (default), `preserve`, or `stdio`

Examples:

# 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, and kiro-cli 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 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 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

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. 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:

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.

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`, `kiro`. 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`, `opencode`, `kiro`)
`-d, --debug`	Show verbose logs including debug messages

Examples:

# 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.

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.

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`, `kiro`). 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:

# 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>.

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:
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.

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:

# 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.

`config show`

Display current configuration summary, or a specific section.

ouroboros config show [SECTION]

Arguments:

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

Examples:

# 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.

ouroboros config backend [BACKEND]

Arguments:

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

Examples:

# Show current backend
ouroboros config backend

# Switch to Codex CLI
ouroboros config backend codex

# Switch to Claude Code
ouroboros config backend claude

`config init`

Initialize Ouroboros configuration.

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.

ouroboros config set KEY VALUE

Arguments:

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

Examples:

# 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.

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.

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 uninstall`

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

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:

# 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-*
 …  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 for the full guide.

`ouroboros status`

Check Ouroboros system status.

Current state: the status subcommands return lightweight placeholder summaries. They are useful for smoke testing the command surface, but should not be treated as authoritative orchestration state.

`status health`

Check system health. Verifies database connectivity, provider configuration, and system resources.

ouroboros status health

Representative Output:

+---------------+---------+
| Database      |   ok    |
| Configuration |   ok    |
| Providers     | warning |
+---------------+---------+

`status executions`

List recent executions with status information.

ouroboros status executions [OPTIONS]

Options:

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

Examples:

# 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.

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:

# 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.

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:

# 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:
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.

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`, `kiro`). Affects which tool variants are instantiated
`--llm-backend TEXT`	LLM backend for interview/seed/evaluation tools (`claude_code`, `litellm`, `codex`, `opencode`, `gemini`, `kiro`). Affects which tool variants are instantiated

Examples:

# 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:

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

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

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

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

orchestrator:
  runtime_backend: claude   # or "codex", "opencode", "hermes", "gemini", or "kiro"

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

`mcp info`

Show MCP server information and available tools.

ouroboros mcp info [OPTIONS]

Options:

Option	Description
`--runtime TEXT`	Agent runtime backend for orchestrator-driven tools (`claude`, `codex`, `opencode`, `hermes`, `gemini`, `kiro`). Affects which tool variants are instantiated
`--llm-backend TEXT`	LLM backend for interview/seed/evaluation tools (`claude_code`, `litellm`, `codex`, `opencode`, `gemini`, `kiro`). 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. For runtime-specific configuration, see the Claude Code, Codex CLI, and OpenCode runtime guides.

Cancelling Stuck Executions

# 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.

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`, `kiro`)
`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_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 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)
`logs/ouroboros.log`	Log output (path configurable via `logging.log_path`)

Exit Codes

Code	Description
`0`	Success
`1`	General error

FilesExpand file tree

cli-reference.md

Latest commit

History

cli-reference.md

File metadata and controls

CLI Reference

Installation

Usage

Global Options

Quick Start

Commands Overview

ouroboros auto

What --runtime controls in ooo auto

Underlying MCP-handler dispatch (outside ooo auto)

ouroboros setup

Brownfield Subcommands

ouroboros init

init start

init list

ouroboros run

run workflow

run resume

ouroboros cancel

cancel execution

ouroboros config

config show

config backend

config init

config set

config validate

ouroboros codex

codex refresh

ouroboros uninstall

ouroboros status

status health

status executions

status execution

ouroboros tui

tui monitor

ouroboros mcp

mcp serve

mcp info

Typical Workflows

Cancelling Stuck Executions

Environment Variables

Configuration Files

Exit Codes

`ouroboros auto`

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

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

`ouroboros setup`

`ouroboros init`

`init start`

`init list`

`ouroboros run`

`run workflow`

`run resume`

`ouroboros cancel`

`cancel execution`

`ouroboros config`

`config show`

`config backend`

`config init`

`config set`

`config validate`

`ouroboros codex`

`codex refresh`

`ouroboros uninstall`

`ouroboros status`

`status health`

`status executions`

`status execution`

`ouroboros tui`

`tui monitor`

`ouroboros mcp`

`mcp serve`

`mcp info`