Command Reference

How to read this reference

Start with your task, not the size of the command list. The groups below offer entry points for code investigation, implementation choices and change checks. See the homepage examples for the questions behind these tools.

Five commands to start with

Useful starting points, not a complete workflow or the MCP core preset. Connect Roam and build the index first; refresh it as the code changes.

Exploration

Health & Quality

Refactoring

Security & Governance

Multi-Agent & MCP

Output Modes

Place global output flags before the command. Format support varies; for example, --sarif applies only to the supported analysis commands below.

Interpret evidence before acting

Read the verdict together with scope, resolution, metric definitions, partial_success, truncation, and skipped-check reasons. Exit zero does not mean every check ran or every finding is resolved.

• safe-delete emits SAFE / REVIEW / UNSAFE. Missing indexed references do not prove absence of dynamic, member, or external use; imported-but-unresolved cases require review.
• algo reports candidate patterns. Inspect the exact source, loop inputs, receiver identity, and ordering requirements; test and measure before applying an optimization.
• observability-opt reports raw-print review candidates, not proven debug leftovers. Python checks actual call syntax and skips docstring/comment examples. Keep intentional CLI output; unreadable or unparseable sources make the result incomplete. Other languages still use text-pattern heuristics.
• doctor checks SQLite integrity independently of index completion or matching search-row counts. Specific failures appear in integrity_errors; a repair does not establish why the corruption happened.
• test-map, ai-readiness, and path-coverage use static relationships, not runtime coverage. Depth-pruned paths and empty input cannot establish a clean result.
• ai-ratio is an uncalibrated pattern score, not an AI-written percentage. Legacy JSON score keys do not establish authorship.
• taint distinguishes dataflow evidence from co-occurrence. Inspect the sink argument, sanitizers, and execution context; even a high-confidence graph finding is not exploitability proof.
• partition chooses two through eight agents by default; the MCP roam_partition default is explicitly four. Review shared files and merge order; the manifest does not enforce ownership.

Global flags go before the command: roam --detail algo or roam --json ai-readiness. Compare Git structure with roam semantic-diff --base HEAD~1. Use roam plan-refactor SymbolName for a symbol and roam split path/to/file.ts for a file.

magic-numbers defaults to the current directory, respects discovery exclusions, and includes monorepo workspaces. Relative JavaScript imports can resolve to TypeScript source through extension substitution; this is not a complete compiler or bundler resolver.

Investigate algorithm choices

roam algo looks for source patterns that may have a better approach and pairs findings with catalogued alternatives. Your agent gets a place to inspect and an option to evaluate, not just a warning that a function is complex.

roam index
roam --json algo

For each candidate, inspect the matched source and the stated assumptions. Check inputs, ordering and side effects, then test correctness and measure performance before adopting a replacement. Refresh the index after code changes. An empty or partial scan is not proof that every algorithm is appropriate.

function countAllowed(values, allowed) {
  let count = 0;
  for (const value of values) {
    if (allowed.indexOf(value) !== -1) count++;
  }
  return count;
}

function countAllowedWithSet(values, allowed) {
  const lookup = new Set(allowed);
  let count = 0;
  for (const value of values) {
    if (lookup.has(value)) count++;
  }
  return count;
}

function findPositions(values, allowed) {
  const positions = [];
  for (const value of values) {
    positions.push(allowed.indexOf(value));
  }
  return positions;
}

git init --quiet
git add -- lookup.js
roam --json index
roam --json algo --task loop-lookup --path lookup.js

{
  "location": "lookup.js:1",
  "symbol_name": "countAllowed",
  "task_id": "loop-lookup",
  "suggested_way": "set-prebuilt",
  "confidence": "medium"
}

The CLI command is algo; math remains a legacy alias. For MCP, select the review preset and restart the server; roam_algo is not in the default core preset. Check the connected tool list.

Preview a specific code edit

roam mutate supports move, rename, add-call and extract operations. The agent supplies the operation and its arguments. Roam previews the planned edits by default; --apply writes them to source files.

Example: preview moving an indexed handle_login function. Replace the name and destination with ones from your repository.

roam --json mutate move handle_login src/auth/login.py

Inspect the proposed edits and warnings before applying. Move uses indexed references for supported import updates; that is not complete language or dependency resolution. Review the diff, refresh the index and run the project's tests and build after an applied change.

Try a change on the graph first

roam simulate applies one requested move, extract, merge or delete operation to a copy of the indexed graph and compares structural metrics. It does not edit source files or choose an architecture for you.

Example: compare the graph before and after a proposed move. Replace this example symbol and path with your own.

roam --json simulate move handle_login src/auth/login.py

Use the result to investigate a proposal, not to approve an edit. A move changes file placement in the model while keeping its edges, so topology-based metrics can stay unchanged. These metrics do not establish runtime performance or behavior after an actual refactor.

Where to find more

• Every command: run roam --help-all 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 a complete workflow: the worked verification example shows how to bind a run, collect checks, review a change and verify its evidence bundle.