rea/docs/cli.md

CLI and Evidence

Use the CLI for a direct inspection or a script. It uses the same application workflows and evidence contracts as REA's MCP server. Each CLI invocation is a separate process; save results when you want to use them in a later command.

Run a command

After installing REA, use rea. You can also run a command without a global installation:

npx -y rea-agents@latest analyze-javascript-application /absolute/path/to/app --json

Use an extracted application directory or an ASAR as the target. Static JavaScript analysis returns the application graph and Evidence directly. Generic rea analyze PATH selects this workflow for directories and .asar files when neither --provider nor --snapshot is supplied. See JavaScript artifact reconstruction for results, integrity checks and coverage.

The complete application Evidence can be hundreds of megabytes for a real application. When an agent or a person reads the result, save it to a file and project a summary, a module page or one module from the saved Evidence:

rea analyze-javascript-application /absolute/path/to/app --json > app-evidence.json
jq -c '{source: {kind: "inline", evidence: .}, view: {kind: "summary"}}' app-evidence.json > app-view.json
rea inspect-analysis-view app-view.json

For example, a 334 MB Obsidian application Evidence file yields a summary view of about 10 KB. Replace the view with {"kind": "page", "collection": "modules", "offset": 0, "limit": 32} for a module page. See JavaScript application workflows for views, feature traces and comparisons that take the same saved Evidence.

Native analysis

Configure Hopper or Ghidra, or the IDA adapter, before analyzing a native target. Substitute your target, search text and function name or address in these examples:

rea analyze /absolute/path/to/program --provider ghidra --json
rea search /absolute/path/to/program "search" --provider ghidra --json
rea function /absolute/path/to/program main --provider ghidra --json
rea decompile /absolute/path/to/program 0x1000 --provider ghidra --json
rea xrefs /absolute/path/to/program 0x1000 --provider ghidra --json
rea trace /absolute/path/to/program "search" --provider ghidra --json

analyze and inspect share the native overview workflow. function returns a function dossier; decompile returns pseudocode. For assembly instructions alone, use rea instructions. A macOS .app bundle can be supplied directly.

Run rea --help or a command's --help for arguments and output options. The generated catalog lists all CLI commands and MCP tools. Provider-specific target support is described in the native guide, DOS guide, raw binary guide, and Windows Ghidra guide.

Choose a provider

List the available providers and their supported operations:

rea providers --json
rea capabilities --json

These commands describe binary-session providers and auxiliary capabilities. For the complete MCP surface, use the connected server's tool list and the session's advertised availability; individual guides describe prerequisites.

With automatic selection, REA uses the single available provider that supports the target. When several providers support it, select one explicitly:

rea analyze /absolute/path/to/program --provider hopper

Set REA_ANALYSIS_PROVIDER for a standing preference. An explicit --provider overrides it. In MCP, pass provider_id to open_binary:

{
  "path": "/absolute/path/to/program",
  "provider_id": "hopper"
}

The selected provider remains bound to the session until an explicit switch or close. Provider failures are returned with their original reason. For an ambiguous selection error, choose from details.candidate_ids; for provider_unavailable, run rea doctor --provider ID --json to diagnose the selected engine. See task readiness and provider selection.

The session reports work still in progress through analysis_activity. A client timeout can end its wait while the provider continues analyzing. cleanup_incomplete identifies resources whose shutdown or removal could not be verified. See MCP contracts for session lifecycle and Ghidra first-query deadlines for import, client timeouts and recovery.

Save and reuse analysis snapshots

A snapshot retains successful analysis results for later queries. REA reuses an exact result when the target bytes, operation, parameters, provider and settings match. Mutations and cursor-dependent calls are excluded from the cache. Snapshot files are local and use owner-only permissions.

Snapshots retain eligible target-scoped question histories in full, including mutation Evidence recorded while another target was active. Observations and related questions must still belong to the saved target. If those dependencies cannot be retained, the entire history is excluded instead of reverting the question to an earlier revision or disposition.

rea analyze /absolute/path/to/program --provider ghidra --snapshot /absolute/path/to/analysis/program.json
# Repeat the same query to reuse its saved result.
rea analyze /absolute/path/to/program --provider ghidra --snapshot /absolute/path/to/analysis/program.json

An exact CLI cache hit is read before starting a provider process. In MCP, open_binary accepts snapshot_path to import a snapshot atomically for its matching target; an MCP provider may still start before returning a cached result. close_binary accepts snapshot_path and optional overwrite: true to save before releasing provider resources. A failed save leaves the session open so the caller can resolve the output failure.

The MCP save receipt reports primitive_entries, workflow_entries, and evidence_records separately. Zero primitive bindings can still accompany retained workflow results and Evidence. These are cached observations, not a saved provider database: only eligible exact queries can reuse a result, and new or live queries can still require provider startup. The CLI uses the same snapshot format and preserves these records when loading and updating it.

Import, export and compare Evidence

Evidence records retain artifact identity, source locations, observations, inferences and unresolved findings. Validate an existing bundle, export its canonical form, or compare two supplied bundles:

rea evidence-import /absolute/path/to/evidence/bundle.json
rea evidence-export /absolute/path/to/evidence/bundle.json /absolute/path/to/evidence/canonical.json
rea compare /absolute/path/to/evidence/left.json /absolute/path/to/evidence/right.json

Exports preserve an existing destination unless --overwrite is explicit. For application traces and version comparisons, see JavaScript application workflows. MCP retained Evidence references belong to one connection. Separate CLI calls consume full saved records.

Import historical source

Import an older source tree to compare with the current artifact:

rea import-reference-source /absolute/path/to/source

The import records hashes and metadata for the supplied files, separately from observations of the current app. It honors the source tree's .gitignore and applies default exclusions for common generated and dependency paths such as node_modules/, dist/, and *.log. Pattern-based exclusions record the matched pattern and whether it came from project, default, caller, or sensitive path policy. Set REA_REFERENCE_SECRET_PATTERNS_JSON to a JSON array of ignore patterns when you want to mark selected paths as sensitive; those patterns are reported separately as configured-secret exclusions.

Re-import saved graphs whose pattern-based exclusions lack pattern before using them in source-to-bundle comparisons.

JavaScript and TypeScript import parsing requires valid UTF-8. Malformed source bytes retain their original hashes and sizes with a decoding diagnostic; REA does not infer module targets from replacement characters.

Historical-source import requires safe no-follow file opens on Linux or macOS. Native Windows returns unsupported_host; use Linux REA inside WSL or another supported host. See source-to-bundle comparison for mapping identities, inferences and unknowns.

Capture runtime behavior

Choose the guide for the target and intended interaction:

• Browser observation: inspect a selected page through CDP.
• Browser scenarios: run declared interactions and capture their results.
• Electron observation: inspect an Electron renderer or capture an application scenario.
• Node/Electron Inspector: record script locations and execution contexts.
• Process capture: run an executable and compare terminal, exit and filesystem observations.

Runtime requests name the target and actions. Launched targets run with your user permissions; consult the chosen guide for host requirements and effects.

Output and exit status

The default terminal format is TOON. Use --json when saving results for a JSON consumer. --json is indented on a terminal and compact when piped or redirected, which keeps large results smaller for agents and scripts; pipe through jq . for indented files. Output selection and formatting do not change operation status.

Status	Meaning
0	The operation completed. Its result may include partial evidence, warnings or unresolved questions.
1	The operation could not complete. Structured output identifies invalid input, permissions, cancellation, timeouts or another failure when available.
128 + N	Signal N ended the process, where the shell or runtime preserves the conventional signal-derived status.

setup --dry-run returns planned and exits 0; a cancelled setup also exits 0. Setup returns 1 for needs_confirmation or needs_human. doctor returns 1 when required checks in its selected readiness scope fail; unavailable optional providers remain informational for unrelated tasks.

Enable pipefail in a supporting shell so a downstream formatter preserves REA's failure status:

set -o pipefail
rea inspect-artifact ./app.asar --json | jq . > inspection.json