mirror of
https://github.com/morluto/rea.git
synced 2026-10-12 02:19:24 +00:00
morluto
6585293c56
Record the exact matching pattern and distinguish project, default, caller, and configured-sensitive exclusions without changing ignore ordering. Include that provenance in graph commitments and validate the contract through compiled CLI and MCP consumers. BREAKING CHANGE: Pattern-based reference graph exclusions require pattern and distinguish project-ignored and default-ignored reasons. Re-import saved graphs that omit matching patterns.
229 lines
11 KiB
Markdown
229 lines
11 KiB
Markdown
# 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](installation.md), use `rea`. You can also run a command
|
|
without a global installation:
|
|
|
|
```bash
|
|
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](javascript-artifact-reconstruction.md)
|
|
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:
|
|
|
|
```bash
|
|
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](javascript-application-workflows.md) for
|
|
views, feature traces and comparisons that take the same saved Evidence.
|
|
|
|
## Native analysis
|
|
|
|
Configure [Hopper or Ghidra](installation.md#hopper), or the
|
|
[IDA adapter](ida-provider.md), before analyzing a native target. Substitute
|
|
your target, search text and function name or address in these examples:
|
|
|
|
```bash
|
|
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](product-catalog.json) lists all CLI commands and MCP
|
|
tools. Provider-specific target support is described in the
|
|
[native guide](native-investigation.md), [DOS guide](ghidra-dos.md), and
|
|
[Windows Ghidra guide](windows-ghidra-p0.md).
|
|
|
|
## Choose a provider
|
|
|
|
List the available providers and their supported operations:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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`:
|
|
|
|
```json
|
|
{
|
|
"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](installation.md#check-readiness-for-your-task)
|
|
and [provider selection](mcp-contracts.md#identity-and-discovery).
|
|
|
|
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](mcp-contracts.md) for session lifecycle and
|
|
[Ghidra first-query deadlines](mcp-contracts.md#ghidra-first-query-deadlines-and-recovery)
|
|
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.
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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](javascript-application-workflows.md).
|
|
MCP [retained Evidence references](mcp-contracts.md#retained-application-evidence-inputs)
|
|
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:
|
|
|
|
```bash
|
|
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](javascript-application-workflows.md#historical-source-to-bundle-comparison)
|
|
for mapping identities, inferences and unknowns.
|
|
|
|
## Capture runtime behavior
|
|
|
|
Choose the guide for the target and intended interaction:
|
|
|
|
- [Browser observation](browser-observation.md): inspect a selected page through CDP.
|
|
- [Browser scenarios](browser-scenario-contract.md): run declared interactions and capture their results.
|
|
- [Electron observation](electron-observation.md): inspect an Electron renderer or capture an application scenario.
|
|
- [Node/Electron Inspector](javascript-runtime-observation.md): record script locations and execution contexts.
|
|
- [Process capture](process-capture.md): 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:
|
|
|
|
```bash
|
|
set -o pipefail
|
|
rea inspect-artifact ./app.asar --json | jq . > inspection.json
|
|
```
|