Reference
Command Reference
The five core verbs that cover ~80% of agent workflows, plus the most-used commands grouped by intent. Every command is local, credential-free, and emits a structured envelope an agent can read. Run roam --help for the full 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.
How to read this reference
The command surface is organised around the nine engineering senses agents miss (see homepage), plus five tiers of approachability. Most users start with Tier 1.
| Tier | What it covers | When to reach for it |
|---|---|---|
| Tier 1 — Core workflow | understand · retrieve · context · preflight · critique (plus one-time init) | First-day, every-day. Five core verbs cover ~80% of agent workflows; init is run once per repo. |
| Tier 2 — High-value practical | impact · affected-tests · test-gaps · safe-delete · clones · pr-risk · verify-imports · math / algo | When you're acting on real changes, not just exploring. |
| Tier 3 — Agent / MCP | mcp · mcp-setup · agent-export · skill-generate · minimap · agent-context | Wiring Roam into Claude Code, Cursor, Codex, your own agent. |
| Tier 4 — CI / enterprise | pr-analyze · pr-comment-render · attest · audit-trail-export · audit-trail-verify · --sarif | Production CI gates, audit evidence, signed attestations. |
| Tier 5 — Advanced / experimental | Specialised commands for specific workflows (catalogued below). | You know what you're looking for; the surface is exhaustive. |
Tier 1 — 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 <name> | Show symbol definition, callers, and callees |
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 |
roam stale-refs [--gate] [--fix preview|apply] [--attest path] | Find dangling file references — markdown links / HTML href-src / backtick paths / anchors whose target is missing. Index-free. Supports SARIF, in-toto attestations, LSP code actions, repo-config (--init), and --root for monorepos. |
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 every MCP tool exposed by the active preset (default: 57 core tools plus the roam_expand_toolset meta-tool; 227 in full) |
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 conflict-aware partitions |
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 SARIF-capable analysis commands including health, complexity, dead, smells, clones, vulns, taint, secrets, n1, dark-matter, supply-chain, critique, stale-refs. Run roam --help for the live list. |
--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
- Every command: run
roam --helpin a terminal. The surface is large; pick by question, not by reading top-to-bottom — see How Roam thinks for the nine-moment decision tree. - Per-command flags:
roam <cmd> --help. - Recipes:
roam ask --listshows every dispatchable recipe;roam ask "<intent>"runs the closest match. - Source: each command lives in
src/roam/commands/cmd_*.py. Apache 2.0. - Something broken? See Troubleshooting for index errors, missing flags, MCP setup issues, and rebuild guidance.
See it run: The 5-minute canonical demo — install → health → preflight → critique → signed ChangeEvidence packet, end to end.
Complete Reference
Auto-generated from roam --help. Every canonical command + alias.
Getting Started
| Command | Description |
|---|---|
roam ask | Run the recipe that matches a free-form query. |
roam workflow | Inspect a workflow recipe DAG, review lenses, and next co... |
roam index | Build or rebuild the codebase index. |
roam index-export | Export the roam index as a portable, integrity-checked ta... |
roam index-import | Import a portable roam index bundle into the current repo. |
roam watch | Watch for file changes and auto-re-index incrementally. |
roam init | Initialize Roam for this project: index + config. |
roam hooks | Manage git hook integration for automatic re-indexing. |
roam reset | Delete the index DB and rebuild from scratch. |
roam clean | Remove orphaned entries from the index (files no longer o... |
roam config | Manage per-project roam configuration (.roam/config.json). |
roam doctor | Diagnose environment setup: Python, dependencies, and ind... |
roam understand | Single-call codebase comprehension — everything in one shot. |
roam dashboard | Unified codebase status: health, hotspots, debt, bus fact... |
roam tour | Generate a codebase onboarding tour. |
roam describe | Auto-generate a project description for AI coding agents. |
roam minimap | Generate a compact codebase minimap for CLAUDE.md injection. |
roam agent-export | Generate an AI agent context file from the roam index. |
roam ws | Manage multi-repo workspaces with cross-repo dependency t... |
roam schema | Show the roam JSON envelope schema and validate output fi... |
roam mcp | Start the roam MCP server. |
roam mcp-setup | Generate MCP server config for AI coding platforms. |
roam mcp-status | Report MCP server status: preset, tools, backpressure, ca... |
roam ci-setup | Generate CI/CD pipeline config for roam-code integration. |
roam adrs | Discover Architecture Decision Records and link them to c... |
roam audit | One-shot codebase architecture audit. |
roam changelog | List commits since the last tag, optionally as a markdown... |
roam exit-codes | List every roam exit code with its meaning. |
roam help-search | Fuzzy search across every command's help text. |
roam plugins | List discovered roam plugins (commands, detectors, langua... |
roam pre-commit | Install or preview a roam-critique pre-commit git hook. |
roam recipes | List every ``roam ask`` recipe with intent + example quer... |
roam version | Print the installed roam-code version (and check PyPI wit... |
roam index-stats | Report .roam index size, row counts, and fragmentation. |
roam stats | Aggregate metrics: language, role, kind counts + recent a... |
roam telemetry | Show local telemetry: slowest commands + recent runs. |
roam surface | Print the canonical capability surface (commands, aliases... |
roam explain-command | Show what a command does, what it depends on, and how sta... |
roam db-check | Integrity sweep over the local index. Reports orphans, br... |
Daily Workflow
| Command | Description |
|---|---|
roam preflight | Run a pre-change safety checklist for a symbol, file, or ... |
roam permit | Structural-permission verdict facade for AI agents. |
roam postmortem | Replay current detectors against past commits. |
roam pr-replay | Generate a PR Replay report. |
roam guard | Check breaking-change risk for a symbol before editing. |
roam agent-plan | Decompose partitions into dependency-ordered multi-agent ... |
roam agent-context | Generate per-worker context: write scope, read-only deps,... |
roam pr-risk | Compute risk score for pending changes. |
roam pr-prep | One-shot pre-PR fitness check: diff + critique + pr-risk. |
roam pr-analyze | Analyse a PR diff for structural risk and AI-likelihood. |
roam pr-bundle | Build a proof-carrying PR bundle (intent + context + affected symbols + risks + tests + non-goals). --auto-collect folds in envelopes from prior roam runs. CI-gateable via validate. |
roam pr-comment-render | Render a markdown PR comment from a pr-analyze envelope. |
roam rules-validate | Lint a `.roam/rules.yml` file before shipping it to your ... |
roam metrics-push | Push metrics-only summary to Roam Cloud Lite. |
roam audit-trail-verify | Verify SHA-256 chain integrity of a roam audit trail. |
roam audit-trail-export | Export the audit trail for procurement / compliance review. |
roam audit-trail-conformance-check | Score the audit trail against an EU AI Act Article 12 che... |
roam article-12-check | EU AI Act Article 12 readiness assessment for the indexed... |
roam capabilities | Emit the capability registry — every command's machine-re... |
roam skill-generate | Generate an agent-runtime skill manifest from the capabil... |
roam compare | Structural diff between two roam indices. |
roam migration-plan | Generate an ordered migration plan with risk + blast-radi... |
roam dogfood | Run the v2 stack on the current repo and emit one combine... |
roam dogfood-aggregate | Aggregate the dogfood eval corpus into a backlog/triage v... |
roam suppress | Suppress a math / over-fetch / missing-index / auth-gaps ... |
roam pr-diff | Show structural impact of pending changes. |
roam evidence-diff | Diff two ChangeEvidence packets. |
roam evidence-doctor | Diagnose a ChangeEvidence packet's health. |
roam evidence-oscal | Emit an OSCAL v1.2 document (Control Mapping or Assessment Results). |
roam api-changes | Detect breaking and non-breaking API changes vs a git ref. |
roam semantic-diff | Show structural change summary vs a git ref. |
roam test-gaps | Map changed symbols to missing test coverage. |
roam affected | Identify affected files/modules from a git diff via depen... |
roam attest | Generate a proof-carrying PR attestation. |
roam adversarial | Adversarial architecture review -- challenge your changes. |
roam verify | Verify changed files follow codebase conventions. |
roam verify-imports | Validate import/require statements against the indexed sy... |
roam diff | Show blast radius: what code is affected by your changes. |
roam context | Get the minimal context needed to safely modify a symbol. |
roam hover | Show a one-line architectural summary for SYMBOL. |
roam retrieve | Return ranked code spans for a free-form task. |
roam critique | Verify a patch against the indexed graph. |
roam fleet | Graph-aware planner for multi-agent code work. |
roam affected-tests | Trace from a changed symbol or file to test files that ex... |
roam test-impact | List tests transitively reachable from symbols changed in... |
roam diagnose | Root cause analysis for a failing symbol. |
roam why-fail | Find recently-changed symbols transitively reached by a f... |
roam recommend | Recommend related symbols using call-graph, co-change, an... |
roam api | List the public API surface (exported public symbols). |
roam disambiguate | List every symbol matching <name> with disambiguators. |
roam annotate | Annotate a symbol or file with a persistent note. |
roam annotations | List annotations for a symbol, file, or the whole project. |
roam plan | Generate a structured execution plan for modifying code. |
roam syntax-check | Check files for syntax errors using tree-sitter AST parsing. |
roam triage | Manage security finding suppressions. |
roam oracle | Container for the boolean oracle commands (symbol-exists, route-exists, is-test-only, is-reachable-from-entry, is-clone-of). |
roam memory | Repo-local agent memory. |
roam runs | Per-agent-run event ledger. |
roam laws | Self-installing constitution. |
roam constitution | Repo-local agent constitution -- capstone for agent-OS su... |
roam agents-md | Generate an ``AGENTS.md`` describing this codebase to AI ... |
roam next | Suggest the next roam command based on current repo state. |
roam brief | One-page agent briefing covering mode / next / highlights... |
roam replay | Re-narrate a past run and (optionally) rerun its commands. |
roam agent-score | Aggregate runs and score each agent on a 0..100 composite. |
roam mode | Show, switch, or query the active agent mode. |
roam intent-check | Verify INTENDED_COMMAND would be allowed by the active mode. |
roam lease | Multi-agent lease system. |
Codebase Health
| Command | Description |
|---|---|
roam health | Show code health: cycles, god components, bottlenecks. |
roam smells | Detect code smells: brain methods, god classes, deep nest... |
roam vibe-check | Detect AI code anti-patterns and compute AI rot score. |
roam llm-smells | Detect LLM-API integration anti-patterns. |
roam test-hermeticity | Scan Python test files for non-hermetic patterns (AI-test flakiness risk). |
roam boundary | Surface public-by-accident exports + changed-range layer violations. |
roam ai-readiness | Estimate how effectively AI agents can work on this codeb... |
roam check-rules | Run structural governance rules against the indexed codeb... |
roam ai-ratio | Estimate the percentage of AI-generated code from git pat... |
roam trends | Health trend timeline, anomaly detection, per-metric trac... |
roam weather | Rank files by churn x complexity score (highest-leverage ... |
roam timeline | Show commits that touched the file owning <symbol>. |
roam debt | Hotspot-weighted technical debt prioritization. |
roam complexity | Show cognitive complexity metrics for functions and methods. |
roam py-types | Show Python type-annotation health for the indexed project. |
roam py-modern | Modern-Python adoption: walrus, match, PEP 604/585/695, f... |
roam pytest-fixtures | Show the pytest fixture chain for SYMBOL, or a project su... |
roam algo | Detect suboptimal algorithms and suggest better approaches. |
roam n1 | Detect implicit N+1 I/O patterns in ORM models. |
roam over-fetch | Detect models that serialize more fields than necessary i... |
roam missing-index | Detect queries that filter or sort on columns without ind... |
roam alerts | Detect health degradation trends and generate actionable ... |
roam fitness | Run architectural fitness functions from .roam/fitness.yaml. |
roam forecast | Predict when metrics will exceed thresholds using trend a... |
roam bisect | Find which snapshots caused architectural degradation. |
roam ingest-trace | Ingest runtime trace data and match spans to symbols. |
roam hotspots | Show runtime hotspots comparing static analysis vs runtim... |
roam why-slow | Find runtime hotspots — symbols slow under real productio... |
roam eval-retrieve | Run the retrieval eval harness over a labeled task set. |
Architecture
| Command | Description |
|---|---|
roam map | Show project skeleton with entry points and key symbols. |
roam graph-export | Export the indexed graph for external tooling. |
roam graph-stats | Report density, connected components, and degree statistics. |
roam graph-diff | Structural diff between two graph snapshots. |
roam architecture-drift | Architectural-trend report over a sliding window of snaps... |
roam layers | Show dependency layers and violations. |
roam clusters | Show code clusters and directory mismatches. |
roam spectral | Spectral bisection: Fiedler vector partition tree. |
roam coupling | Show temporal coupling: file pairs that change together. |
roam dark-matter | Detect dark matter: file pairs that co-change but have no... |
roam effects | Show what functions DO — side-effect classification. |
roam side-effects | Classify symbols by their side effects (none / io_read / ... |
roam idempotency | Classify symbols by idempotency (idempotent / non_idempot... |
roam causal-graph | Build per-symbol causal graphs (input → sink data depende... |
roam tx-boundaries | Classify functions by transactional safety. |
roam cut | Minimum cut analysis — find fragile domain boundaries. |
roam simulate | Counterfactual architecture simulator. |
roam orchestrate | Partition the codebase for parallel multi-agent work. |
roam partition | Generate a multi-agent partition manifest with conflict a... |
roam entry-points | Entry point catalog with protocol classification. |
roam patterns | Detect common architectural patterns in the codebase. |
roam safe-zones | Identify safe refactoring boundaries for a symbol or file. |
roam visualize | Generate a Mermaid or DOT architecture diagram. |
roam x-lang | Show cross-language symbol bridges detected in the project. |
roam fingerprint | Topology fingerprint for cross-repo comparison. |
roam clones | Detect near-duplicate code via AST structural hashing. |
Exploration
| Command | Description |
|---|---|
roam search | Find symbols matching a name substring (case-insensitive). |
roam search-semantic | Find symbols by natural language query (hybrid BM25 + vec... |
roam batch-search | Search up to 10 symbol-name patterns in a single command. |
roam complete | Return left-anchored prefix completions for the given par... |
roam grep | Context-enriched grep with reachability, clone, and bridg... |
roam refs-text | Audit literal strings across the project: per-surface ref... |
roam history-grep | Through-history search using git pickaxe (-S / -G). |
roam file | Show file skeleton: all definitions with signatures. |
roam symbol | Show symbol definition, callers, and callees. |
roam module | Show directory contents: exports, signatures, deps. |
roam trace | Show shortest path between two symbols. |
roam deps | Show file import/imported-by relationships. |
roam uses | Show all consumers of a symbol: callers, importers, inher... |
roam fan | Show fan-in/fan-out: most connected symbols or files. |
roam impact | Show blast radius: what breaks if a symbol changes. |
roam relate | Show how a set of symbols relate to each other. |
roam endpoints | List all detected REST/GraphQL/gRPC endpoints with handlers. |
roam metrics | Show unified metrics for a file or symbol. |
roam findings | Query the central findings registry (cross-detector view). |
Reports & CI
| Command | Description |
|---|---|
roam report | Run a compound report preset — multiple commands in one s... |
roam budget | Check pending changes against architectural budgets. |
roam breaking | Detect potential breaking changes vs a git ref. |
roam coverage-gaps | Find entry points with no path to a required gate symbol. |
roam auth-gaps | Find endpoints missing authentication or authorization ch... |
roam orphan-routes | Find backend API routes that have no frontend consumers (... |
roam bus-factor | Detect knowledge loss risk per module (bus factor analysis). |
roam simulate-departure | Simulate what happens when a developer leaves the team. |
roam suggest-reviewers | Suggest optimal code reviewers for changed files. |
roam dev-profile | Analyze developer commit patterns and behavioral metrics. |
roam owner | Show code ownership: who owns a file or directory. |
roam codeowners | Analyze CODEOWNERS coverage and ownership distribution. |
roam drift | Detect ownership drift: where declared owners differ from... |
roam secrets | Scan for hardcoded secrets, API keys, tokens, and passwords. |
roam supply-chain | Dependency risk dashboard: pin coverage, risk scoring, su... |
roam risk | Show domain-weighted risk ranking of symbols. |
roam migration-safety | Check migration files for non-idempotent (unsafe if run t... |
roam api-drift | Detect mismatches between backend API responses and front... |
roam path-coverage | Find critical untested paths from entry points to sensiti... |
roam capsule | Export the structural graph as a portable JSON capsule. |
roam rules | Evaluate custom governance rules defined in .roam/rules/. |
roam vuln-map | Ingest vulnerability scanner reports and match to codebas... |
roam vuln-reach | Query reachability of ingested vulnerabilities through th... |
roam vulns | Scan and manage vulnerability inventory. |
roam sbom | Generate a Software Bill of Materials (SBOM) enriched wit... |
roam taint | Reach-analysis from rule sources to sinks over the indexe... |
roam cga | Code Graph Attestation: sign-ready in-toto evidence over ... |
roam congestion | Detect developer congestion: files with too many concurre... |
roam compatibility | Detect outbound surface regressions vs a baseline snapshot. |
Refactoring
| Command | Description |
|---|---|
roam dead | Show unreferenced exported symbols (dead code). |
roam orphan-imports | List imports that don't resolve to any indexed module / i... |
roam flag-dead | Detect potentially stale feature flag code (conditionally... |
roam duplicates | Detect semantically duplicate functions via structural si... |
roam safe-delete | Check if a symbol can be safely deleted. |
roam delete-check | Gate the working diff on surviving references to deleted ... |
roam split | Analyze a file's internal structure and suggest how to sp... |
roam fn-coupling | Show function-level temporal coupling (hidden dependencies). |
roam doc-staleness | Detect stale docstrings where the code body changed long ... |
roam docs-coverage | Analyze exported-symbol doc coverage and stale docs in on... |
roam stale-refs | Find dangling file references — markdown links, HTML href... |
roam lsp | Run the roam-stale-refs language server on stdin/stdout (... |
roam suggest-refactoring | Rank symbols that are likely to yield high-value refactor... |
roam plan-refactor | Build an ordered refactoring plan with risk, test, and im... |
roam conventions | Auto-detect codebase naming, file, import, and export con... |
roam sketch | Show compact structural skeleton of a directory. |
roam test-map | Map a symbol or file to its test coverage. |
roam test-pyramid | Count tests by kind (unit/integration/e2e/smoke), flag in... |
roam pr-risk | Compute risk score for pending changes. |
roam why | Explain why a symbol matters — role, reach, criticality, ... |
roam invariants | Discover implicit contracts for symbols. |
roam intent | Link documentation to code -- find what docs describe wha... |
roam closure | Compute the minimal set of changes needed when modifying ... |
roam mutate | Syntax-less agentic editing. |
roam test-scaffold | Generate test file skeletons from indexed symbols. |
Other
| Command | Description |
|---|---|
roam churn | Rank files by churn x complexity score (highest-leverage ... |
roam digest | Health trend timeline, anomaly detection, per-metric trac... |
roam math | Detect suboptimal algorithms and suggest better approaches. |
roam onboard | Single-call codebase comprehension — everything in one shot. |
roam refs | Show all consumers of a symbol: callers, importers, inher... |
roam snapshot | Health trend timeline, anomaly detection, per-metric trac... |
roam trend | Health trend timeline, anomaly detection, per-metric trac... |