Martin Klein
7b15762d09
* fix(reference): report sloppy scripts, PHP, C# and enclosing Git facts Importing the source/ subtree of a legacy PHP and C# checkout produced four wrong or missing facts: - Babel's unambiguous mode parses a module first and keeps its strict-mode recovery errors after falling back to a script, so a valid sloppy-mode `delete messages;` was reported as a parse failure and the semantic IR marked the file as parser-recovered. Parsing now goes through one owner that re-parses such a script as a script. - .php and .cs files had no language; they are now detected as PHP and C# (detection only, no parsing). - A root without its own .git was reported as having no version control even inside a checkout. The adapter now resolves the nearest enclosing repository, as Git does, and reports `none` only when no ancestor has one. - The CLI recorded importer_version as null although the package version is known. * fix(reference): keep module strictness and classify C# and PHP as source Review follow-up. `.mjs` and `.mts` files are modules by extension, but the script fallback re-parsed them in sloppy mode and erased real strict-mode errors. The parser boundary now owns the extension rule, parses explicit modules as modules and applies the fallback only when the mode is ambiguous; the require-binding analysis uses the same rule. `.cs` and `.php` received a language but stayed classified as unknown, so source-to-bundle comparison dropped them. Both are now source extensions, like the other detected languages. * fix(reference): honor package module scope and keep unknown-mode strict errors Review follow-up. A `.js` file under a package.json with `"type": "module"` is an ES module, but it went through the script fallback that erases strict-mode errors. The import now reads each in-inventory package.json and parses `.js` files in a module scope as modules. Other `.js` and `.ts` sources keep an unknown mode, because bundlers treat them as modules without that field: they are no longer forced to script, and errors that only the module parse reports are kept as an entry limitation. * fix(reference): bound package scopes and keep application parsing unchanged Review follow-up. - `.cjs` files parse as scripts, so module-only strict errors no longer become limitations on CommonJS trees. `.cts` keeps an unknown mode because TypeScript compiles ES import syntax there. - An unreadable or linked package.json now bounds the module scope with an unknown type instead of letting an outer `"type": "module"` apply. - The application pipeline parses as on main again. Its module-only strict errors keep a source partial; package-mode handling stays in the reference importer. * refactor(reference): keep unmarked module modes unknown instead of resolving package scope Review follow-up. Resolving Node package scope for `.js` kept pulling in more of Node's lookup semantics (require bindings, excluded or directory-named manifests). Only extensions now select a mode: `.mjs` and `.mts` parse as modules and `.cjs` as scripts. Every other source keeps an unknown mode, so module-only strict errors stay visible as an entry limitation instead of being dropped or asserted. This matches the require-binding analysis, which also treats unmarked paths as unknown.
280 lines
13 KiB
Markdown
280 lines
13 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.
|
|
|
|
## 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:
|
|
|
|
```bash
|
|
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](managed-code-analysis.md)
|
|
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](sqlite-databases.md) 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:
|
|
|
|
```bash
|
|
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](go-binaries.md)
|
|
for supported containers and absent or malformed metadata.
|
|
|
|
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](mcp-contracts.md#generated-catalog) 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),
|
|
[raw binary guide](raw-binary.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.
|
|
|
|
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.
|
|
|
|
```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. 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. 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
|
|
```
|