CLI Surface

Command Reference with Examples

High-signal commands by workflow. The full CLI surface has 139 canonical commands (+3 alias pairs), but most teams rely on a smaller daily core.

Convention: all examples assume the current directory is a repository root that has already run roam init.

Core Daily Commands

Command	Example	When to use
`roam understand`	`roam understand`	Get a full codebase briefing before diving into files.
`roam context`	`roam context PaymentService`	Ranked file/line reading plan for a symbol.
`roam impact`	`roam impact PaymentService`	Blast radius and likely affected areas.
`roam preflight`	`roam preflight PaymentService`	Safety check before edits.
`roam diff`	`roam diff --staged`	Understand current change set risk.
`roam health`	`roam health --gate`	Track and enforce architecture health (gate thresholds via `.roam-gates.yml`).

Command	Example	Output focus
`roam search`	`roam search auth`	Name matches over indexed symbols.
`roam search-semantic`	`roam search-semantic "database connection pool" --backend auto`	Hybrid BM25 + TF-IDF + optional local ONNX semantic retrieval with pre-indexed framework packs for cold-start queries.
`roam symbol`	`roam symbol src/auth/service.py`	Symbol list in one file.
`roam uses`	`roam uses login`	Who calls a symbol (callers and consumers).
`roam fan`	`roam fan login`	Fan-in/fan-out for a symbol.
`roam trace`	`roam trace LoginController UserRepo`	Path through the call graph.
`roam deps`	`roam deps src/`	Module dependency graph summary.
`roam layers`	`roam layers`	Detected architecture layering.
`roam clusters`	`roam clusters --min-size 3`	Louvain module communities.
`roam hotspots`	`roam hotspots`	Complexity/churn hotspots.
`roam algo`	`roam algo`	Detect 23 algorithm anti-patterns with Big-O improvements and fix suggestions.
`roam visualize`	`roam visualize --format mermaid`	Diagram output for architecture views.

Command	Example	Purpose
`roam check-rules`	`roam check-rules --severity error`	Run built-in and custom governance rules.
`roam rules`	`roam rules --rules-dir rules/community`	Evaluate YAML rule packs (path/symbol/AST).
`roam rules --init`	`roam rules --init`	Generate starter custom rules.
`roam smells`	`roam smells --min-severity warning`	Code smell detector catalog.
`roam secrets`	`roam --sarif secrets`	Secret leakage detection with remediation hints.
`roam vulns`	`roam --json vulns`	Dependency vulnerability scan and reachability.
`roam test-gaps`	`roam test-gaps --changed`	Changed code lacking nearby tests.
`roam verify-imports`	`roam verify-imports --file src/auth/service.py`	Import hallucination and unresolved reference checks.

Command	Example	Purpose
`roam semantic-diff`	`roam semantic-diff --base HEAD~1`	Structural deltas: symbols, signatures, imports.
`roam api-changes`	`roam api-changes --base HEAD~1`	Breaking API risk detection.
`roam affected`	`roam affected --changed`	Files/tests likely impacted by current edits.
`roam safe-delete`	`roam safe-delete old_helper`	Evidence-based dead code removal check.
`roam docs-coverage`	`roam docs-coverage --threshold 70`	Doc coverage + stale-doc drift + PageRank-ranked missing docs.
`roam simulate`	`roam simulate move AuthService src/core/`	Counterfactual architecture changes without editing files.
`roam partition`	`roam partition --agents 3`	Split work for multi-agent execution.
`roam orchestrate`	`roam orchestrate --agents 3`	Generate an agent task graph and dependencies.

Command	Example	Purpose
`roam mcp`	`ROAM_MCP_PRESET=core roam mcp`	Run MCP server with constrained tool set (presets: core, review, refactor, debug, architecture, full).
`roam mcp --list-tools`	`roam mcp --list-tools`	Inspect tool catalog and metadata.
`roam mcp-setup`	`roam mcp-setup cursor`	Generate client configuration.
`roam hooks`	`roam hooks install`	Auto-index on post-merge/post-checkout flows.
`roam watch`	`roam watch --webhook-port 8787 --guardian --guardian-report .roam/guardian.jsonl`	Daemon mode with polling/webhook refresh plus optional continuous architecture-guardian snapshots.
`roam dashboard`	`roam --json dashboard`	Single endpoint for key quality/project metrics.

roam --json context PaymentService
roam --sarif health --gate
roam --budget 600 impact PaymentService