Reference

CLI Reference

The rig CLI is the primary interface for both humans and coding agents. 36 top-level commands, human-readable by default, with --json on most commands for structured agent consumption. Every mutating command ends with a handoff: what happened, current state, the next action.

Design Principles

Post-Command Handoff

Every mutating command ends with: what happened + current state + the next action.

Error Messages Are First-Class

Every error: what happened + why it is a problem + what to do next.

# Example handoff output:
Rig "auth-feats" restored (ID: abc123)
5/5 nodes ready: 3 resumed, 2 fresh (resume tokens expired)
Dashboard: http://localhost:7433/rigs/abc123
Orchestrator: tmux attach -t orch-lead@auth-feats

# Example error output:
Error: pod "dev1" member "impl" has runtime "bogus"
  Expected: claude-code, codex, or terminal
  Fix: update your rig spec at pods[0].members[0].runtime

Core Loop

The operator workflow: whoami (where am I?) → ps (what is running?) → transcript/ask (what happened?) → act (send, expand, down).

rig whoami

Show the current managed identity in an OpenRig topology. Resolves identity through a 7-level cascade: --node-id flag, --session flag, OPENRIG_NODE_ID / RIGGED_NODE_ID env, OPENRIG_SESSION_NAME / RIGGED_SESSION_NAME env, tmux pane @rigged_node_id, tmux pane @rigged_session_name, raw tmux session name.

rig whoami [--node-id <id>] [--session <name>] [--json]

--node-idExplicit node ID override.

--sessionExplicit session name override.

--jsonPartial result if daemon is unreachable but identity can still resolve.

# From inside a managed tmux session:
rig whoami
# Node: impl@auth-pod (rig: auth-feats)
# Runtime: claude-code
# Transcript: ~/.openrig/transcripts/auth-feats/impl@auth-pod.log

# Explicit override:
rig whoami --node-id abc123 --json

rig ps

Process status. Lists running rigs, or expands into a cross-rig node inventory with session names, runtimes, startup status, restore outcomes, attach commands, and errors.

rig ps [--nodes] [--json]

--nodesExpand into per-node detail across all rigs.

--jsonStructured JSON output.

# List all rigs:
rig ps

# Show every node across all rigs:
rig ps --nodes

rig transcript

Read agent transcript output. Reads transcript files, not pane scrollback.

rig transcript <session> [--tail <lines>] [--grep <pattern>] [--json]

<session>Session name to read transcripts for.

--tailNumber of lines from the end (default: 50).

--grepRegex pattern filter.

rig ask

Query rig evidence from transcript and chat history. This is a daemon-backed evidence query, not a second LLM invocation. Returns rig summary, evidence excerpts, optional chat excerpts, an insufficient flag, and optional guidance.

rig ask <rig> <question> [--json]

<rig>Rig name to query.

<question>Natural language question.

# Check what an agent has been doing:
rig ask auth-feats "has the reviewer approved the auth changes?"

# Structured output for automation:
rig ask auth-feats "what errors occurred in the last hour?" --json

Lifecycle

rig up

Boot a new rig from a spec, restore from a snapshot, or install from a bundle. Source resolution: YAML path boots from spec, .rigbundle path installs/bootstraps, bare name checks spec library first then treats as existing rig restore — if both match, exits with an ambiguity error.

rig up <source> [--plan] [--yes] [--target <root>] [--json]

<source>A .yaml spec path, .rigbundle path, or bare name.

--planShow the execution plan without running.

--yesSkip confirmation prompts.

--targetRoot directory for agent resolution.

--jsonStructured JSON output.

# Boot from a spec file:
rig up auth-rig.yaml --target .

# Restore an existing rig by name:
rig up auth-feats

# Install from a bundle:
rig up my-topology.rigbundle

# Preview before booting:
rig up auth-rig.yaml --plan

rig down

Tear down a running rig. When --snapshot succeeds, output includes the restore command. If the rig name is uniquely reusable, the handoff prefers rig up <rigName>.

rig down <rigId> [--delete] [--force] [--snapshot] [--json]

--deleteDelete the rig record after teardown.

--forceKill sessions immediately.

--snapshotTake a snapshot before teardown.

--jsonStructured JSON output.

# Graceful teardown with snapshot:
rig down abc123 --snapshot
# Rig stopped. Snapshot saved: snap-20260330.
# To restore: rig up auth-feats

# Force teardown and delete record:
rig down abc123 --force --delete

rig snapshot

Capture a point-in-time snapshot of a running rig, or list existing snapshots.

rig snapshot <rigId>
rig snapshot list <rigId>

<rigId>The rig to snapshot or list snapshots for.

rig restore

Restore a rig from a specific snapshot. Reports per-node outcome: resumed, fresh, or failed. Non-zero exit if any node fails.

rig restore <snapshotId> --rig <rigId>

<snapshotId>The snapshot to restore from.

--rigRequired. The target rig ID.

rig release

Release an adopted-session rig. Stops OpenRig management but leaves tmux sessions alive. Refuses if the rig contains OpenRig-launched nodes.

rig release <rigId> [--delete] [--json]

--deleteDelete the rig record after release.

--jsonStructured JSON output.

Discovery & Adoption

rig discover

Scan for unmanaged tmux sessions. Groups by naming convention and shared CWD.

rig discover [--draft] [--json]

--draftGenerate a candidate rig spec YAML from discovered sessions.

--jsonStructured JSON output.

# See what's running outside OpenRig:
rig discover

# Generate a spec from discovered sessions:
rig discover --draft > adopted-rig.yaml

rig bind

Bind a discovered session to a rig node. Binding mode is exclusive: use --node for an existing node, or --pod + --member to create a new node.

rig bind <discoveredId> --rig <rigId> (--node <logicalId> | --pod <namespace> --member <name>)

<discoveredId>The discovered session ID from rig discover.

--rigRequired. Target rig ID.

--nodeBind to an existing node by logical ID.

--podCreate a new node in this pod namespace (requires --member).

--memberMember name for the new node (requires --pod).

rig adopt

Materialize topology and bind discovered live sessions in one step. The input must be a pod-aware RigSpec.

rig adopt <path> --bind <logicalId=sessionId> [--bind ...] [--target-rig <rigId>] [--rig-root <root>] [--json]

<path>Path to a pod-aware RigSpec YAML.

--bindRequired. Repeatable. Maps logicalId=tmuxSessionOrDiscoveryId.

--target-rigAdopt into an existing rig instead of creating a new one.

--rig-rootRoot directory for agent resolution.

# Adopt discovered sessions into a new rig:
rig adopt topology.yaml \
  --bind impl=session-abc \
  --bind reviewer=session-def

# Adopt into an existing rig:
rig adopt topology.yaml \
  --bind impl=session-abc \
  --target-rig existing-rig-id

rig unclaim

Release an adopted session without killing its tmux session.

rig unclaim <sessionRef> [--json]

Topology Mutation

rig expand

Add a pod to a running rig from a pod fragment file.

rig expand <rigId> <pod-fragment-path> [--rig-root <path>] [--json]

<rigId>Target rig.

<pod-fragment-path>YAML pod fragment to add.

--rig-rootRoot directory for agent resolution.

rig shrink

Remove an entire pod from a running rig.

rig shrink <rigId> <podRef> [--json]

<podRef>Pod namespace or pod ID.

rig launch

Launch or relaunch a node in a running rig.

rig launch <rigId> <nodeRef> [--json]

<nodeRef>Logical ID or node ID.

rig remove

Remove a single node from a running rig.

rig remove <rigId> <nodeRef> [--json]

<nodeRef>Logical ID or node ID.

Communication

rig send

Send a message to an agent's terminal. Uses the two-step send pattern: paste text, wait, submit Enter.

rig send <session> <text> [--verify] [--force] [--json]

<session>Target session name.

<text>Message text to send.

--verifyRequest delivery verification.

--forceOverride mid-task safety checks.

# Send a task to an agent:
rig send impl@auth-pod "implement the login endpoint"

# Force send even if agent is mid-task:
rig send impl@auth-pod "stop and switch to logout" --force

rig capture

Capture terminal output from agent sessions. Can target a single session, all sessions in a rig, or a specific pod.

rig capture <session> [--lines <n>] [--json]
rig capture --rig <name> [--lines <n>] [--json]
rig capture --pod <name> --rig <name> [--lines <n>] [--json]

--linesNumber of lines to capture (default: 20).

--rigCapture from all sessions in a rig.

--podCapture from all sessions in a pod (requires --rig).

rig broadcast

Send a message to multiple agent sessions. Without --rig or --pod, broadcasts to all running sessions across all rigs.

rig broadcast <text> [--rig <name>] [--pod <name>] [--force] [--json]

--rigScope broadcast to a specific rig.

--podScope broadcast to a specific pod.

--forceOverride mid-task safety checks.

rig chatroom

Structured chat room for rig communication. All subcommands take the rig name as a positional argument.

rig chatroom send <rig> <message> [--sender <name>]
rig chatroom history <rig> [--topic <name>] [--limit <n>] [--json]
rig chatroom watch <rig> [--tmux]
rig chatroom topic <rig> <topic-name> [--body <text>] [--sender <name>]

sendPost a message to the chatroom.

historyRead chat history, optionally filtered by topic.

watchLive-watch chatroom messages. --tmux starts a dedicated watcher session.

topicPost a topic-scoped message.

# Send a message as the orchestrator:
rig chatroom send auth-feats "auth PR is ready for review" --sender orch

# Watch chatroom live in a tmux pane:
rig chatroom watch auth-feats --tmux

# Read recent history:
rig chatroom history auth-feats --limit 20

Specs & Validation

rig agent validate

Validate an AgentSpec directory. Checks agent.yaml structure, resource references, and profile definitions.

rig agent validate <path> [--json]

rig spec validate

Validate a RigSpec file. Checks pod structure, member references, and edge validity.

rig spec validate <path> [--json]

rig spec preflight

Run preflight checks on a RigSpec. Resolves all agent_ref paths and validates resources exist on disk.

rig spec preflight <path> [--rig-root <root>] [--json]

rig specs

Browse, preview, and manage the spec library. The add subcommand validates the file as either RigSpec or AgentSpec before copying it into the user library.

rig specs ls [--kind <kind>] [--json]
rig specs show <name-or-id> [--json]
rig specs preview <name-or-id> [--json]
rig specs add <path> [--json]
rig specs sync [--json]
rig specs remove <name-or-id> [--json]
rig specs rename <name-or-id> <new-name> [--json]

lsList specs in the library. --kind filters by spec type.

showShow full spec details.

previewStructured review data from the daemon.

addAdd a spec file to the library (validates first).

syncSync the library with the filesystem.

removeRemove a spec from the library.

renameRename a spec in the library.

Bundles

rig bundle create

Create a .rigbundle archive from a rig spec. Vendors all referenced AgentSpecs with SHA-256 checksums.

rig bundle create <spec> -o <path> [--name <name>] [--bundle-version <ver>] [--include-packages <refs...>] [--rig-root <root>] [--json]

-o, --outputRequired. Output path for the bundle.

--nameBundle name override.

--bundle-versionBundle version string.

--include-packagesAdditional package refs to vendor.

--rig-rootRoot directory for agent resolution.

rig bundle inspect

Inspect a bundle without installing. Shows schema version, agents, and integrity status.

rig bundle inspect <bundle-path> [--json]

rig bundle install

Install a bundle. Extracts, validates integrity, and bootstraps.

rig bundle install <path> [--plan] [--yes] [--target <root>] [--json]

--planShow the execution plan without running.

--yesSkip confirmation prompts.

--targetTarget root directory.

Import & Export

rig import

Import a rig spec from YAML and optionally instantiate or materialize it. Supports additive materialization into an existing rig.

rig import <path> [--instantiate] [--materialize-only] [--preflight] [--target-rig <rigId>] [--rig-root <root>]

--instantiateInstantiate the rig after import.

--materialize-onlyMaterialize topology without launching.

--preflightRun preflight checks before import.

--target-rigAdditive materialization into an existing rig.

--rig-rootRoot for pod-aware agent resolution.

rig export

Export a live rig back to YAML. Default output path is rig.yaml.

rig export <rigId> [-o|--output <path>]

-o, --outputOutput file path (default: rig.yaml).

Infrastructure

rig daemon

Manage the OpenRig daemon process.

rig daemon start [--port <port>] [--host <host>] [--db <path>]
rig daemon stop
rig daemon status
rig daemon logs [--follow]

startLaunch the daemon with optional runtime overrides.

stopStop the daemon.

statusShow daemon status.

logsRead daemon logs. --follow for live tail.

rig status

Human-oriented summary. Prints daemon state, rig summary, and cmux availability. Does not support --json.

rig status

rig ui

Open the OpenRig UI in the browser.

rig ui open

rig mcp

Start the MCP server for agent tool access. Exposes 17 tools including rig_up, rig_down, rig_ps, rig_send, rig_chatroom_send, and more.

rig mcp serve [--port <port>]

rig config

Inspect and change OpenRig configuration. Precedence: CLI flag, environment variable, config file, default.

rig config [--json]
rig config get <key>
rig config set <key> <value>
rig config reset

getRead a config value.

setWrite a config value.

resetReset config to defaults.

rig preflight

Check system readiness for OpenRig. On failure, prints what failed, why it matters, and how to fix it.

rig preflight [--json]

rig doctor

Verify OpenRig install health. Checks daemon dist, UI dist, Node version, tmux availability, writable state paths, and daemon port availability.

rig doctor [--json]

Global Behavior

--jsonAvailable on most commands. Emits structured JSON for agent consumption. Same data as human-readable output.

Error formatEvery error follows: what happened + why it's a problem + what to do next.

Exit codes0 = success. 1 = daemon not running. 2 = daemon fetch failure. Non-zero on partial failures (e.g. some nodes failed to restore).

Daemon dependencyMost commands require a running daemon. Exceptions: daemon, config, preflight, and doctor also work locally.