Skip to content

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>` | Symbol search by name substring; BM25/FTS5 reranking when `--explain` is set
`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` | Onboarding tour: top symbols, reading order, entry points, language breakdown, stats
`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` | Query reachability of ingested vulnerabilities; `--cve` scopes to one CVE, `--from` to one entry point
`roam adversarial` | Adversarial architecture review — challenges your changes by composing diff + cycles + clusters + layers + detectors
`roam cga emit` | Sign an in-toto v1 Code Graph Attestation
`roam cga verify` | Verify a CGA attestation (cosign-aware)
`roam attest` | Proof-carrying PR attestation — bundles diff, risk, breaking changes, and fitness for a commit range

## 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: 16 core tools plus the `roam_expand_toolset` meta-tool; 243 in `full`)
`roam mcp-setup <client>` | Generate config for Claude Code, Cursor, Windsurf, VS Code, Gemini CLI, Codex CLI
`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).

## Mutate — probabilistic intent, deterministic compiler

`roam mutate` turns a natural-language refactor request into a deterministic AST transform with a graph-validated diff. The agent emits intent; Roam compiles it to a typed spec, applies it via tree-sitter, then re-resolves the graph and asserts zero dangling references before any disk write.

                PROBABILISTIC INTENT                       DETERMINISTIC COMPILER
                (what the agent wants)                     (what roam guarantees)

                "move handleSave into                      Stage 1 -- Typed transform spec
                 src/forms/save.ts and                     +----------------------------+
                 rewrite its callers"                      | op       : move            |
                        |                                  | symbol   : handleSave      |
                        v                                  | dst_file : src/forms/...   |
                LLM emits a structured                     | dry_run  : true            |
                transform request                          +----------------------------+
                        |                                              |
                        +--------->  validate  --------> reject  ----->+
                                      fail               (no edit)
                                        |
                                        v
                                    Stage 2 -- AST rewriter (tree-sitter)
                                    +------------------------------------+
                                    |  parse src   ->  remove def        |
                                    |  parse dst   ->  insert def        |
                                    |  refs/edges  ->  rewrite imports   |
                                    +------------------------------------+
                                                |
                                                v
                                    Stage 3 -- Graph-validated diff
                                    +------------------------------------+
                                    |  re-resolve symbols + edges        |
                                    |  diff against indexed graph        |
                                    |  assert: zero dangling refs        |
                                    +------------------------------------+
                                                |
                                                v
                                      apply patch  |  reject + reason

## Simulate — gradient descent on an architecture canvas

`roam simulate` evaluates counterfactual refactors against the indexed graph without writing to disk. For each candidate move / extract / merge / delete, it clones the graph, re-derives the metric vector, and ranks by metric delta — so the agent picks the structurally best move before any edit lands.

                        GRADIENT DESCENT ON AN ARCHITECTURE CANVAS

                indexed graph G0  (cycles=12, complexity=84, coupling=0.31)
                        |
                        v
                +-------+---------------------------------------------+
                |       |       |       |              |              |
                v       v       v       v              v              v
            candidate candidate candidate candidate    ...        candidate
            move      move      extract   merge                   delete
            A->m1     B->m2     C->m3     D+E                     F
                |       |       |       |              |              |
                v       v       v       v              v              v
            clone     clone     clone     clone        clone        clone
            graph     graph     graph     graph        graph        graph
                |       |       |       |              |              |
                v       v       v       v              v              v
            re-derive re-derive re-derive re-derive ...    re-derive
            metrics   metrics   metrics   metrics              metrics
                |       |       |       |              |              |
                v       v       v       v              v              v
            delta:    delta:    delta:    delta:                  delta:
            -2 cyc    +1 cyc    -4 cyc    -1 cyc                  +3 cyc
            -8 cmp    -3 cmp    -5 cmp    +2 cmp                  -1 cmp
            -.04 cpl  +.01 cpl  -.07 cpl  -.02 cpl                +.05 cpl

                                    |
                                    v
                            rank by metric delta
                                    |
                                    v
                            best move:  extract C -> m3
                            (-4 cycles, -5 complexity, -0.07 coupling)
                                    |
                                    v
                            no disk write -- counterfactual only
                            agent may keep, refine, or discard

## Where to find more

- Every command: run `roam --help` in 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 --list` shows 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` | Inspect roam plugins discovered via entry points / ROAM_P...
`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 commands` | List the repo's runnable commands, classified + evidence-...
`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 + W198...
`roam postmortem` | Replay current detectors against past commits.
`roam pr-replay` | Generate a PR Replay report.
`roam guard` | Check breaking-change risk for SYMBOL before editing.
`roam guard-pr` | Run the full Roam Guard pipeline in one call.
`roam guard-doctor` | Preflight + health check before running roam guard-pr.
`roam guard-init` | Bootstrap `.roam/` + optional rule-pack stub for Roam Guard.
`roam guard-clean` | Prune `.roam/verdict-log.jsonl` to its last N entries.
`roam guard-diff` | Show the verdict delta between two bundle snapshots.
`roam guard-history` | Show recent pr-bundles + their last-known verdict.
`roam guard-rules` | Inspect / validate / test Roam Guard verification rule pa...
`roam proof-bundle` | Compose and emit the AgentChangeProofBundle v1 from a pr-...
`roam verdict` | Compute the closed-enum verdict for a proof bundle.
`roam verification-contract` | Emit the G3 verification contract for changed files + mod...
`roam bench-compile` | Run a controlled A/B between vanilla / static / compile p...
`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` | Proof-carrying PR bundle (R26 -- Roam Review MVP differen...
`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 Assessmen...
`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 SYMBOL 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 compile` | Compile TASK (freeform string) into an agent-consumable e...
`roam compile-stats` | Show distribution stats over the compile telemetry log.
`roam compile-cache` | Manage the persistent envelope cache.
`roam envelope-diff` | Compare two compile envelopes A and B. Reports probe-fami...
`roam dispatch-trace` | Emit the classifier + dispatch decision tree for PROMPT.
`roam syntax-check` | Check files for syntax errors using tree-sitter AST parsing.
`roam triage` | Manage security finding suppressions.
`roam oracle` | Container for the five v12.1 boolean oracles.
`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 magic-numbers` | Scan source for hardcoded numeric constants that should b...
`roam compiler-health` | One envelope per compiler health snapshot.
`roam compiler-corpus` | Compile every prompt in a corpus file and aggregate the p...
`roam vibe-check` | Detect AI code anti-patterns and compute AI rot score.
`roam llm-smells` | Detect LLM-API integration anti-patterns.
`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 dict-consistency` | Audit string-keyed dicts in a Python file for cross-dict ...
`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 test-hermeticity` | Scan Python test files for non-hermetic patterns (AI-test...
`roam algo` | Detect suboptimal algorithms and suggest better approaches.
`roam agent-opt` | Optimize roam's agent-contract surface: find weak envelop...
`roam observability-opt` | Optimize a repo's diagnosability: find debug prints / wea...
`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.
`roam boundary` | Surface public-by-accident exports + changed-range layer ...

### 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 cycles` | List strongly-connected components (import/call cycles) o...
`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 at` | Show the code at FILE:LINE plus the enclosing symbol (and...
`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 definition, callers, and callees for SYMBOL.
`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 SYMBOL: callers, importers, inherit...
`roam fan` | Show fan-in/fan-out: most connected symbols or files.
`roam impact` | Show blast radius: what breaks if 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 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 docs-index` | Find orphaned planning memos and broken local Markdown li...
`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 identifier or file path to its test coverage.
`roam test-pyramid` | Count tests by kind (unit/integration/e2e/smoke), flag in...
`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 SYMBOL: callers, importers, inherit...
`roam snapshot` | Health trend timeline, anomaly detection, per-metric trac...
`roam trend` | Health trend timeline, anomaly detection, per-metric trac...