Command reference

All commands run from the target repository’s root (the git toplevel of the current directory) with python3 ralph_orchestrator/orch.py <cmd> (or the .venv-ralph/bin/python created by install.sh). Configuration is always read from ralph_orchestrator/config.yaml; e-mail and gateway settings accept environment overrides (Configuration reference).

Subcommands

Command What it does Exit codes

wizard

interactive setup: banner, config sanity, agent CLI check, opencode provider reachability, ralph gateway reachability (hard stop), dependency install, plugin install

0 ok · 1 problem/aborted · 130 Ctrl-C

preflight [--ping]

non-interactive environment check: base branch exists, agent CLI on PATH, python modules importable, gateway key resolvable; --ping sends a 1-message call to every reviewer model + the planner

0 ok · 1 any problem

plan [--spec PATH] [--force]

SPEC.md → ralph_orchestrator/tickets.yaml via the planner model (3 repair rounds against graph.validate); refuses to overwrite an existing file without --force

0 ok · 1 invalid plan / file exists

check

validate tickets.yaml: DAG, waves, longest chain, max useful agents, scope-overlap notes between same-wave tickets

0 valid · 1 invalid (error list printed)

graph

print the ticket DAG as Mermaid (graph TD, one node per ticket with title + complexity)

0

run [--max-agents N] [--no-consensus] [--preflight]

execute the plan (resumable); consumes pending e-mail replies first; final report mail at the end

0 DONE · 2 BLOCKED · 1 STUCK/BUDGET/API_DOWN/INTERRUPTED

watch [--once]

correction agent: each cycle fetches + consumes replies and reworks pending tickets; yields to a live run; heartbeats .ralph/watch.json

0 stopped · 1 no tickets

status

one line per ticket (status, attempts, model, title) + agent runs, peak agents, reason; needs ralph_orchestrator/tickets.yaml

0

dashboard [--port 8471] [--host 127.0.0.1]

serve the live dashboard (Dashboard HTTP API)

0 (Ctrl-C stops)

report

send the run report mail now (manual)

0

mail-reply [--limit N] [--file PATH] [--subject S]

capture replies to the last status mail from IMAP into .ralph/inbox.json, or import one from a file (deduped by content)

0 · 1 (file empty)

mail-check

step-by-step e-mail setup check (DNS/TCP/TLS/login/send), hidden password prompt, test mail; standalone: python3 ralph_orchestrator/mail_check.py [--from-env]

0 test mail accepted · 1 any step failed

pdf

render the current state to out/run_report.pdf (Playwright Chromium; HTML always written)

0 PDF written · 1 browser missing

install

install the agent plugins (project npm plugins into .opencode/opencode.json + one-time global caveman installer)

0

reset [--branches]

remove all .ralph/wt/ worktrees, ralph/ branches (integration kept unless --branches) and .ralph/

0

install.sh (from this repository)

./install.sh /path/to/target-repo

Copies ralph_orchestrator/ into the target (refusing if a git repo is missing or a kit already exists), creates .venv-ralph, installs requirements.txt, excludes .ralph/ and .venv-ralph/ locally via git info/exclude, and prints the next steps. It never commits anything — commit the kit yourself (worktrees branch from a commit).

setup.sh (mockup)

The showcase equivalent for the dummy-agent demo: copies the kit into mockup/demo-repo, installs the showcase config and tickets, creates the git history. See 2-minute offline showcase.

Notes

  • orch.py is the only entry point that matters day to day; dashboard.py, bus.py and mail_check.py are also directly executable (the bus runs as bus on agents' PATH).

  • Every command that builds State touches .ralph/state.json (creating it if absent); check, graph, plan, preflight do not.

  • Timeouts: agent runs and acceptance commands use orchestrator.iter_timeout; git operations 300 s; the wizard’s gateway probes 15 s (60 s for the chat fallback).