Reference
Command Reference
The five core verbs that cover ~80% of agent workflows, plus the most-used commands grouped by intent. Run roam --help for the full 202-command surface; roam <cmd> --help for any command's flags.
Every command supports --json for machine output and (where applicable) --sarif for CI Code Scanning. Verdicts use VERDICT: first-line convention.
The 5 Core Verbs
These are the "start here" commands. Most agents need only these.
| Verb | What it does | Example |
|---|
understand |
Landing-pad summary of the codebase: layers, sizes, hotspots, entry points. |
roam understand |
retrieve |
Free-form natural-language task → budget-bounded ranked spans (graph-aware FTS5 + rerank). |
roam retrieve "where is auth?" |
context |
Files + line ranges to read before changing a symbol, prioritised by callers and tests. |
roam context AuthService |
preflight |
Blast radius, affected tests, complexity, fitness rules — all in one verdict. |
roam preflight AuthService |
critique |
Patch verifier. Pipe a diff in; get clones-not-edited + blast-radius severity. Exits 5 on high-severity findings. |
git diff | roam critique |
Exploration
| Command | What it does |
|---|
roam search <pattern> | FTS5 symbol search (BM25-ranked, qname-aware) |
roam symbol <path> | File skeleton — top-level symbols + line ranges |
roam file <path> | Detailed file info: complexity, ownership, recent changes |
roam impact <name> | Caller list — what breaks if you change this symbol |
roam trace <a> <b> | k-shortest paths between two symbols in the call graph |
roam tour | Walk through the most architecturally-central symbols |
roam diagnose <name> | Root-cause ranking for a failing symbol |
roam ask "<question>" | Natural-language intent dispatch over the recipe registry |
Health & Quality
| Command | What it does |
|---|
roam health | Composite health score (0-100) with risk breakdown |
roam health --gate | Same, but exits non-zero on threshold breach |
roam complexity | SonarSource-compatible cognitive complexity per symbol |
roam debt | Tech-debt aggregate; --roi ranks refactor candidates |
roam check-rules | Run all built-in + community rule packs |
roam test-gaps | Symbols that no test covers; --changed for diff scope |
roam why-slow | Runtime hotspots from ingested traces |
Refactoring
| Command | What it does |
|---|
roam suggest-refactoring | Top-N refactor candidates by ROI |
roam plan-refactor <name> | Step-by-step plan to refactor without breaking callers |
roam mutate move <sym> <file> | Apply a structural transform with import rewriting |
roam simulate move <sym> <file> | What-if architecture — clone the graph and apply a move |
roam clones --persist | Detect AST-level clones; persist to clone_pairs for critique |
roam migration-plan | Current architecture → target architecture roadmap |
Security & Governance
| Command | What it does |
|---|
roam taint | Graph-reach BFS for vulnerability reachability (OpenVEX-correct) |
roam vuln-reach | Map a CVE to reachable code paths |
roam adversarial | Attack-surface review per symbol |
roam cga emit | Sign an in-toto v1 Code Graph Attestation |
roam cga verify | Verify a CGA attestation (cosign-aware) |
roam attest | SLSA-style provenance for the index itself |
Multi-Agent & MCP
| Command | What it does |
|---|
roam mcp | Start the MCP server (stdio transport) |
roam mcp --list-tools | Print all 136 MCP tools the server exposes |
roam mcp-setup <client> | Generate config for Claude Code, Cursor, Gemini, Codex |
roam fleet plan | Partition work across N agents (Louvain + co-change + PageRank) |
roam orchestrate | Multi-agent coordination plan with zero-conflict guarantees |
roam skill-generate | Emit a SKILL.md file from the Capability Registry |
Output Modes
Every command supports these flags at the top level (before the subcommand):
| Flag | Effect |
|---|
--json | Stable JSON envelope with schema versioning. For agent + script consumption. |
--sarif | SARIF 2.1.0 — for GitHub Code Scanning. Supported on health, debt, complexity, rules, secrets. |
--agent | Compact JSON + 500-token default budget. Optimised for sub-agent CLI calls. |
--budget <n> | Cap output to N tokens (0 = unlimited). |
Where to find more
- All 202 commands: run
roam --help in a terminal.
- Per-command flags:
roam <cmd> --help.
- Cookbook recipes: github.com/Cranot/roam-code/docs/cookbook.
- Source: each command lives in
src/roam/commands/cmd_*.py. Apache 2.0.