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.

Managed assemblies (.NET)

For a .NET PE/CLI assembly, inspect its identity and deployment form before inspecting members. These commands read metadata and Common Intermediate Language (CIL) without loading or executing the assembly and require no native analysis engine:

rea inspect-managed-artifact /absolute/path/Assembly.dll --json
rea inspect-managed-members /absolute/path/Assembly.dll --json
rea inspect-managed-members /absolute/path/Assembly.dll --type Example.Parser --json

Replace Example.Parser with an exact full_name from the member inspection, or a declaring type name you already know. Omit --type to inspect all members, or repeat it to select several types. Selection limits decoding to the selected types; member references remain an assembly-wide inventory, so the output can still be large.

Choose the workflow from the artifact's contents rather than its .exe or .dll extension. The managed parser requires PE/CLI metadata; it does not unpack .NET single-file hosts or decode IL2CPP metadata. NativeAOT method bodies require native analysis. See the managed-code guide for supported deployment forms, selection semantics, and coverage limits.

SQLite snapshots

For a local database snapshot, use rea inspect-sqlite-database PATH --json. Add --table NAME --row-limit 20 to read a bounded sample from an ordinary table. This command does not require a native analysis provider. See SQLite database snapshots for database/WAL identity, source-file handling and row-value semantics.

Native analysis

Inspect embedded Go build metadata without installing Go or configuring a disassembler:

rea inspect-go-binary /absolute/path/to/program --json

The shared CLI/MCP workflow reports compiler version, modules, replacements, build settings, original bytes and SHA-256. See Go binaries for supported containers and absent or malformed metadata.

Inspect an embedded cargo-auditable Rust dependency list without installing Rust or configuring a disassembler:

rea inspect-rust-binary /absolute/path/to/program --json

The same workflow reports package names, versions, sources, the root package, dependency edges, and the section's file range. A missing .dep-v0 section is null metadata, not proof that the binary has no dependencies. See Rust binaries.

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, follow message, remediation.action, and the original reasons in details.rejections. For Hopper, Ghidra, IDA, and JADX, run rea doctor --provider ID --json to diagnose the selected engine. Other adapters, such as pwntools-elf, report their configuration requirements directly and are not accepted by doctor --provider. 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.

Dispatching a metadata write invalidates the active session's snapshot cache, even if its reply fails: the provider may already have applied the write. Close and reopen the target before importing or saving another snapshot.

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 normally read before starting a provider process. On Windows, Ghidra first admits the selected source through its native snapshot owner, so replay can start that provider. 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
rea import-reference-source /absolute/path/to/source --detail summary --outline-depth 2 --json

The default (--detail full) returns the complete HistoricalSourceGraph. Choose --detail summary for a HistoricalSourceSummary of that same committed inventory: its HistoricalSourceManifest contains the full graph and root digests, with provenance, VCS facts, languages, manifest paths, entry and relationship counts, parse-failure counts, file/directory states, exclusions and limitations. The summary is a presentation view, not a graph accepted by source-to-bundle comparison; keep the full output for that workflow.

--outline-depth requires --detail summary and accepts a nonnegative safe integer. Depth 1 shows root children, depth 2 (the default) also shows their children, and depth 0 omits all outline entries. Paths retain canonical Unicode code-point order. outline.omitted_entry_count counts only inventoried entries hidden by the chosen depth; it does not count unexamined children of excluded or unreadable directories, or change inventory_state. Exclusions and source limitations remain separate from this presentation omission.

file_sizes.known_bytes is the exact sum of known inventoried file sizes as decimal text, so large sums cannot lose integer precision. Unknown sizes count in file_sizes.unknown_file_count; excluded or unexamined paths are not included in that total. A zero known-byte sum therefore does not establish an empty source tree. Full output retains individual file hashes, relationships and parse-failure diagnostics. Summary mode performs the same import and cleanup, then projects the committed result without rereading source files. It reduces the selected output, not the amount of source examined. A shallow tree or many exclusions can still produce a large summary; depth 0 removes the outline but preserves the other facts. No fixed output-size or runtime improvement is promised.

The import records hashes and metadata for the supplied files, separately from observations of the current app. For a directory inside a Git checkout, it records the HEAD of the nearest enclosing repository; whether the working tree matches that commit remains unknown. 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. Links into excluded paths retain their internal target metadata; the exclusion explains why the target has no inventory entry, and the inventory remains partial. Exclusions record entry_kind when the importer observed it; older saved exclusions without that field have unknown kind. An excluded ancestor proves an internal descendant only when its kind is directory. 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.
• Electron fuses: read packaged fuse bytes before expecting --inspect to reach an Electron main process.
• 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

rea mcp doctor --json checks production MCP startup and reports child logs in diagnostics. It drains stderr while retaining at most its first 64 KiB of raw bytes as text, omitting a final UTF-8 code point if it crosses that byte limit. stderr_bytes counts all observed bytes, including omitted output; stderr_truncated indicates that output exceeded the retention limit. The same diagnostics appear inside the report when --full-output is selected. Log truncation alone does not change the diagnostic health or 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.

For cutter-command, --json-output requests command-specific JSON from Cutter when available. This is separate from --format json, which selects the CLI result representation; the global --json flag selects that same CLI representation.

Cutter still accepts deprecated --json=true and --json=false compatibility values. When both forms are present, --json-output takes precedence in either argument order. Bare --json retains its global meaning of selecting JSON CLI output formatting.

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-derived status. An unhandled signal may have ended the process, with the shell or runtime preserving the conventional status; a command may instead have handled the signal, waited for its operation and cleanup to settle, and assigned the same status (130 for SIGINT, 143 for SIGTERM). In the handled case, it may also have printed a structured cancelled result.

A cancelled result does not by itself determine the exit status; it depends on the command's signal handling. Commands routed through the shared withCommandCancellation handler in the CLI set status 130 for SIGINT or 143 for SIGTERM after their operation settles. Current source registrations use that handler for process capture and comparison (capture-process, compare-process-captures), JavaScript application analysis (analyze when it selects the JavaScript lane, and analyze-javascript-application), selected browser, web and Electron commands (including analyze-web-bundle, observe-web-execution, capture-browser-scenario and capture-electron-scenario), and the platform and provider command families for Android/ADB, Apktool/JEB/Flutter, firmware, PCAP and signal analysis, WASM/EVM, Go/Rust and binary diagnostics, Frida instrumentation, the Cutter command, objdump, Rizin and GDB. In these paths, a returned structured cancelled result can be printed before the wrapper assigns the signal-derived status. This describes the current source routing; it is not a claim that every command or provider runtime has been independently exercised.

inspect-artifact also returns a structured cancelled result, but its direct analysis cancellation path does not set a signal-derived exit status, so it exits 1. Setup has its own contract: cancellation exits 0. Treat the structured result and process status as separate signals when scripting cancellation.

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