CLI reference

rigg init

Create a .rigg/ directory with example workflow files.

rigg init

Generated examples include:

• plan.yaml
• implement.yaml
• review-uncommitted.yaml
• review-branch.yaml
• review-commit.yaml

rigg list

List workflows discovered from the nearest .rigg/ directory.

rigg list

When local run history is available, rigg list also shows the last recorded run status for each workflow.

rigg serve

Start the local HTTP API server.

rigg serve [--host <host>] [--port <n>] [--json]

Flag	Description
--host <host>	Bind address for the HTTP server. Default: 127.0.0.1.
--port <n>	Listen port for the HTTP server. Default: 3000.
--json	Print machine-readable startup info as a single JSON object on stdout.

Examples:

rigg serve
rigg serve --port 3847
rigg serve --host 0.0.0.0 --json

rigg upgrade

Upgrade an installed Rigg release binary to the latest or a specific version.

rigg upgrade [target]

Examples:

rigg upgrade
rigg upgrade v0.1.0

rigg upgrade is only available from an installed release binary, not from bun run.

rigg validate

Validate all .rigg/*.yaml workflow files. Reports syntax errors, unknown fields, invalid references, and schema violations.

rigg validate

rigg history

Show recorded runs for the current workspace.

rigg history [workflow_id] [--status <status>] [--limit <n>] [--offset <n>] [--json]

Flag	Description
--status <status>	Filter by running, succeeded, failed, or aborted.
--limit <n>	Limit the number of rows returned. Default: 10.
--offset <n>	Skip the first n matching rows. Default: 0.
--json	Emit machine-readable JSON instead of the default text table.

Examples:

rigg history
rigg history plan --status failed
rigg history --limit 20 --offset 20
rigg history --json

rigg show

Show a single recorded run by run ID or unique short ID prefix.

rigg show <run_id> [--json]

Examples:

rigg show d3f8a1c
rigg show d3f8a1c --json

rigg logs

Show recorded output for a run or a single step.

rigg logs [run_id] [step] [--run <id>] [--step <name>] [--json]

If you omit run_id, rigg logs defaults to the latest recorded run. Step selectors can use a step ID or a node path such as /0.

Flag	Description
--run <id>	Select the run explicitly, using a full run ID or short ID.
--step <name>	Select a step explicitly by step ID or node path.
--json	Emit machine-readable JSON instead of the default text view.

Examples:

rigg logs
rigg logs d3f8a1c
rigg logs d3f8a1c code-review
rigg logs --run d3f8a1c --step /0
rigg logs --json

rigg run

Execute a workflow by ID.

rigg run <workflow_id> [--input key=value] [--auto-continue] [--headless] [--output-format <text|json|stream-json>] [--verbose]

Flag	Description
--input key=value	Set input parameter (repeatable). Values are JSON-parsed when possible.
--auto-continue	Skip step barriers automatically in the interactive TTY UI, while still pausing for approvals and questions.
--headless	Run without the TTY UI. Step barriers auto-continue and output is written to stdout/stderr.
--output-format <text|json|stream-json>	Choose headless output format. Requires --headless. Default: text.
--verbose	In headless text mode, stream step output and lifecycle markers as the run executes. Requires --headless.

By default, rigg run requires an interactive terminal. It opens a stateful terminal UI with:

• a run header
• a live running view for the active step output and codex activity
• a waiting view for barriers and interactions
• a final view that shows the last completed step result

With --auto-continue, step barriers advance automatically and the UI emits a muted auto-continue: Next: ... line for each released barrier. Approvals and user input still pause normally.

If stdin or stderr is not attached to a TTY, the default interactive mode fails fast with a message telling you to re-run in an interactive terminal or switch to --headless.

Headless mode

Use --headless for scripts, CI, or other non-interactive environments.

• --headless removes the TTY requirement.
• Step barriers auto-continue automatically.
• Required workflow inputs must be supplied via --input or workflow defaults before the run starts.
• Headless runs cannot pause for interactive approvals or free-form questions. If a workflow requests an approval, rigg selects a non-approve decision when one exists; otherwise the run fails.

Headless output formats:

• text: print the final workflow result to stdout and final errors to stderr.
• text --verbose: also stream step stdout/stderr and lifecycle markers while the run is executing.
• json: emit one final summary object with run metadata, final result or error, and per-step status.
• stream-json: emit one JSON event per line as the run executes, followed by a final summary record.

Use Ctrl-C to interrupt the active step.

Workflows are discovered from the nearest .rigg/ directory.

Successful runs are recorded in local run history when the history database is available. Use rigg history, rigg show, and rigg logs to inspect past runs.

Provider prerequisites:

• Codex steps require a local Codex CLI session.
• Claude steps require a local Claude Code CLI session. Run claude login before use.
• OpenCode steps require a local OpenCode CLI installation. Verify with opencode --version.
• Cursor steps require a local Cursor installation with ACP available.

Examples:

rigg run hello --input name=Rigg
rigg run hello --auto-continue
rigg run hello --headless
rigg run hello --headless --verbose
rigg run hello --headless --output-format json
rigg run hello --headless --output-format stream-json