mirror of
https://github.com/morluto/rea.git
synced 2026-11-16 19:53:50 +00:00
* fix(native): report a target-selected plist against the target, not the unsent path input inspect_plist resolved a plist that the open target itself selects with the same origin as a caller's path input, so an unreadable target plist was reported as an input issue on path even when the caller never sent path. The selection now records a target origin, and unreadablePlist reports it as a BinaryTargetError for the target. The inspect-plist CLI command is projected from its contract, so its --relative-path issues are named by the CLI key. * refactor(cli)!: route analyze to the contract its target selects (#10808) * refactor(cli): route analyze to the contract its target selects analyze hand-declared both lanes: native open options for binary_overview and the JavaScript integrity policy and source selection for analyze_javascript_application, with its own routing and refusals. registerTargetRoutedCommand now projects each route from its contract, takes the union of their options, runs the first route that owns every given option and takes the target, and refuses options the chosen route does not own by their CLI key. Omitted union fields, including a root discriminator, no longer need an argv projection. * fix(cli): give a routed command's chosen route its CLI-only option defaults Routing strips option defaults so an omitted option routes no target. Contract fields regain theirs on admission, but CLI-only options have no later parse, so a defaulted one reached the handler as undefined. The chosen route's omitted CLI-only options now receive their defaults before the handler runs. * refactor(cli): deliver decompile and inspect-macho Evidence by the contract's detail (#10813) * refactor(cli): deliver decompile and inspect-macho Evidence by the contract's detail decompile and inspect-macho omitted the contract's detail field and always printed complete Evidence. Both now declare evidenceDelivery, adding --detail and --evidence_output from the contract. Publishing a result never used the provider id it required, so publication takes no provider and runOnSessionTarget no longer needs one to deliver. * refactor(cli): project managed artifact and native-boundary inspectors from their contracts (#10816) inspect-managed-artifact and inspect-managed-native-boundaries re-declared the managed budget fields by hand. Both now register from their contracts on a session target, and inspect-managed-artifact gains --detail and --evidence_output from its detail field. * fix(cli): name every contract command's input issues by their CLI key Commands applied their CLI field binding only where a session-target or direct handler returned an undelivered result. With evidenceDelivery, decompile publishes through the shared delivery, which returned a provider failure unprojected, so an issue about the procedure would be reported at ["procedure"] instead of the advertised positional "address". Handlers that run a service or publish themselves never applied it: inspect-il2cpp-metadata reported ["generic_instances"], inspect-go-binary ["max_string_literals"] and inspect-apple-ips ["join_path"] rather than the CLI keys other commands report. The contract command now projects whatever its handler returns through the binding it owns, for plain and target-routed commands alike, and the handler context no longer carries the binding. * fix(analysis-view): summarize pseudocode that selected an independent fresh decompile The pseudocode view parsed its parent's parameters with a selection schema that admitted only procedure and document. A procedure_pseudo_code observation made with analysis independent_fresh records that field, so its summary view refused the parent. Through the CLI's new summary delivery, `decompile --analysis independent_fresh --detail summary --evidence_output <file>` would fail after a successful decompile and never save the bundle; an inline inspect_analysis_view of such Evidence failed the same way. The selection schema now admits the analysis the contract offers, and the contract reads that enum from the same owner. * test(cli): restore the worker's exit status after synthetic contract command runs logCliCommand sets process.exitCode on a refused or failed command. The synthetic routed and input-field harnesses ran in the cli-boundary project's shared workers (isolate: false) and left that status for later tests. Each invocation now restores the previous status. * refactor(cli)!: deliver inspect-managed-members Evidence through the shared --evidence_output (#10845) inspect-managed-members was the last command with its own Evidence delivery: a hand-written registration passed --detail and --evidence-bundle to runProviderAnalysis, whose members-only delivery variant re-checked heap headroom and published through deliverAnalysisEvidence. Every other producer writes its bundle with --evidence_output through publishCliAnalysisEvidence, and elsewhere on the CLI --evidence-bundle names an input bundle to read. The command now registers from the inspect_managed_members contract on a session target with evidenceDelivery, like inspect-managed-artifact; --type is the contract's type_names. runProviderAnalysis loses its delivery parameter and its two refusals, and deliverAnalysisEvidence, now unused, is deleted. Its lifecycle tests drive publishEvidenceDelivery directly or the CLI delivery; the managed-only headroom pre-check tests are removed, since the shared delivery deliberately does not re-authenticate immutable Evidence and keeps the writer's check for mutable sources. BREAKING CHANGE: `rea inspect-managed-members --evidence-bundle <path>` is now `--evidence_output <path>`; the old flag is refused as an unknown flag. With `--detail summary`, stdout is now `{"summary": <summary Evidence>, "evidence_bundle": {"path", "bytes"}}` instead of the summary Evidence alone, and a publication failure is the shared delivery's error projection without the `error` label or `input_path`. A summary without a destination names `evidence_output` in its issue path. Migrate by renaming the flag and reading `.summary`. Compatibility is not kept: one spelling cannot mean "read this bundle" on view and workflow commands and "write this bundle" on one producer. * refactor(cli): project analyze-javascript-application and analyze's JavaScript route from one contract projection analyze-javascript-application declared its options by hand, mapped about twelve option names to contract fields itself, parsed its delivery separately and resolved its own caller path. analyze's JavaScript route, projected from the same contract, omitted every field but the path, source selection and integrity policy, so the two commands for one contract offered different options. Both now use javaScriptApplicationCliProjection and runJavaScriptApplicationCommand: the path positional, --artifact-format, --source-path, and the two options that accept a JSON file (--source-paths-json, --semantic-precision), with contract delivery. analyze therefore takes the JavaScript budgets, --artifact-format, --semantic-precision and --detail/--evidence_output/--view for JavaScript targets, and refuses them by CLI key for native targets. javascriptApplicationOptions is deleted. The command's missing-target refusal now names its CLI key, "path", as every contract command does. * refactor(cli): project the apktool commands from their contracts (#10878) * refactor(cli): project the apktool commands from their contracts * refactor(cli): project the Flutter commands from their contracts (#10882) * refactor(cli): project the Flutter commands from their contracts * refactor(cli): project the JEB commands from their contracts (#10888) * refactor(cli): project the JEB commands from their contracts * refactor(cli): project the Android package, class, method and reference commands from their contracts (#10893) * refactor(cli): compose compare-managed-members from its contract over two inspected targets (#10914) * refactor(cli): compose compare-managed-members from its contract over two inspected targets The contract command builder takes Evidence targets: required contract fields that each take the Evidence a source contract produces for one positional target, with the source's options admitted for every target. compare-managed-members now inspects each path through the typed managed runner, as inspect-managed-members does, and compares the records as MCP compare_managed_members does. A failing candidate names its argument and retains the baseline's Evidence; a cancellation as the comparison settles retains the comparison. The path-only comparison service is removed. * fix(cli): drain queued interrupts before a composed command settles Select snapshot faults by file identity, guard real permission denial to hosts that enforce it, and release retained owners when a test fails. * refactor(cli): project the ADB commands from their contracts (#10934) Each ADB command is registered from its ADB_TOOL_CONTRACTS entry through registerContractCommand, keeping its positionals, flags and kebab-case path keys. start-adb-activity keeps its repeatable --extra type:key:value option, which supplies the contract's extras. * refactor(cli): project Frida discovery from its contracts and share Frida request mapping with MCP (#10951) list-frida-devices and list-frida-processes are registered from their contracts, with each remote member as its own option, and admit the request MCP would send. instrument-with-frida keeps its argv but builds and admits the instrument_with_frida contract input. One application owner maps Frida contract inputs to service requests for both adapters. * refactor(cli): finalize the Evidence-target composition through runOwned runOnEvidenceTargets turned a completed comparison into a cancellation by reading the abort signal by hand, which main's architecture guard now refuses outside runOwned. The composition now finalizes through runOwned: its close drains queued interrupts (it owns no resource), and a cancellation observed as it settles keeps the completed Evidence as the partial observation, as before. * fix(errors)!: keep every completed argument's observation beside a composite failure's own partial (#10961) * fix(errors): keep every completed argument's observation beside a composite failure's own partial * test(errors): cover argument observations through cleanup composition and the partial-free fallback * test(errors): settle the cleanup through its owner's release in the argument-observation case * refactor(cli): project instrument-with-frida through the contract builder (#10962) * refactor(cli): project instrument-with-frida through the contract builder with CLI-only positionals and handler-filled fields * fix(cli): keep omitted flattened members omitted so partial capture limits keep their Evidence * refactor(cli): project the CDP page-target browser commands from their contracts (#10976) * refactor(cli): project the CDP page-target browser commands from their contracts * refactor(cli): project inspect-web-page from its contract with a branch-selecting flag * test(cli): enroll the browser commands in the parity registration check and refuse unenrolled argv fixtures * refactor(cli): project the V8 Inspector and Electron commands from their contracts (#10977) * refactor(cli): project the V8 Inspector runtime commands from their contracts * test(cli): enroll the V8 Inspector runtime commands in the parity registration check * refactor(cli): project the Electron page observation commands from their contracts (#10987) * refactor(cli): project the Electron page observation commands from their contracts * test(cli): enroll the Electron page observation commands in the parity registration check * refactor(cli): project inspect-electron-fuses from its contract with the shared caller-path rule The command now registers through registerContractCommand with `path` as a caller path, so the builder's absoluteCallerPath owns relative-path anchoring and the command's own absoluteElectronFusePath copy is removed. inspectWithService records the caller's spelling as caller_input_path. The named file is unchanged: every `..` is kept for the filesystem, and Win32 resolves as before. The recorded selected_path drops `.` segments and repeated separators (`App.app/./` -> `App.app/`), and an empty path is now refused at argv parsing (VALIDATION_ERROR) like every other caller-path command. * test(cli): derive contract-built commands from the builder registries instead of a hand list Every command named after a public tool contract must register through a contract builder unless it is in a shrinking list of hand registrations, and the renamed contract commands are listed exactly, so an earlier migration that reverts fails instead of dropping out of the parity cases. The JSON-document command hand list is covered by the same check and removed. * test(cli): drop the empty inspect-electron-fuses path mismatch the CLI now refuses * refactor(cli): project compare-web-screenshots and analyze-web-bundle from their contracts with builder JSON inputs (#11012) * refactor(cli): project compare-web-screenshots from its contract with builder JSON inputs read from inline text or a file The contract command builder gains jsonInputs: structured fields taken as inline JSON or a JSON file path (- reads stdin), read when the command runs and admitted with the contract input before any target is opened. Inline text that is not JSON is refused under its CLI key; a file that cannot be read keeps its own failure. compare-web-screenshots takes both artifacts this way, replacing its hand-written JSON argument parsing. * refactor(cli): project analyze-web-bundle from its contract analyze-web-bundle now registers through registerContractCommand with Evidence and view delivery, semantic_precision as a builder JSON input, and source_map_limits flattened onto the existing --source-map-* flags. Page-inspection extras stay omitted, and script sources stay on as the contract default. The superseded javascriptRouteDelivery options, passive browser scope options, observation duration helper and fetched source-map option set are removed. * refactor(cli): take semantic_precision of JavaScript application analysis as a builder JSON input analyze-javascript-application and the analyze route read --semantic-precision through the contract builder's jsonInputs instead of a CLI-only option decoded in the handler, so the decoded budgets are admitted with the contract input before analysis. * refactor(cli): route compare-web-captures to the contract input shape its documents select (#11027) * refactor(cli): route compare-web-captures to the contract input shape its documents select * fix(cli): keep routed defaults advertised and reuse the admitted capture parse * fix(cli): keep explicit routed options distinct from advertised defaults * refactor(cli): project inspect-ntfs-journal from its contract (#11043) * refactor(cli): project inspect-ntfs-journal from its contract * refactor(cli): project the pcap commands from their contracts (#11045) * refactor(cli): project the pcap commands from their contracts * refactor(cli): project inspect-playwright-trace, the Cutter commands and execute-rizin-command from their contracts (#11046) * refactor(cli): project inspect-playwright-trace from its contract * refactor(cli): project the Cutter commands from their contracts (#11047) * refactor(cli): project the Cutter commands from their contracts * refactor(cli): project execute-rizin-command from its contract (#11048) * fix(cli): refuse a selected page without summary delivery before opening the target * refactor(cli): project export-web-scripts and trace-web-module-imports from their contracts (#11053) * refactor(cli): project export-web-scripts and trace-web-module-imports from their contracts * fix(cli): describe export-web-scripts paths as resolved against the working directory * refactor(cli): project the web runtime and JavaScript recovery commands from their contracts (#11084) * refactor(cli): project the web runtime commands from their contracts * refactor(cli): project recover-javascript-sources from its contract * refactor(cli): select a contract input branch by its literal field and project guided-workflows (#11085) * refactor(cli): select a contract input branch by its literal field and project guided-workflows * fix(cli): refuse delivery options before reading JSON inputs * fix(cli): keep branch-only defaults to their branch and name admission issues by CLI key A branch-only field no longer carries its default into the shared options, so another branch never receives it; the selected branch applies the default on parse. Contract admission failures are projected to CLI keys like handler failures. CLI defaults are typed only on top-level fields, the one place that applies them. * refactor(cli): project compare-process-captures from its contract, checking each capture before reading the next (#11114) * refactor(cli): project compare-process-captures from its contract, checking each capture before reading the next The contract builder gains jsonInputChecks: each check runs on a decoded JSON input as soon as it is read, in argv order, so a refused input stops the command before the next is read; the handler receives what each check admitted. compare-process-captures authenticates the left capture before reading the right and the right before the trace specification, then compares the authenticated facts. It now also takes inline JSON, stdin and --max-capture-age-ms like MCP. Empty JSON input text is refused at argv. A JSON input whose final file close fails is reported as cleanup_incomplete naming the file instead of an unclassified failure. compareProcessEvidenceFiles and its trace-spec parser are removed. * fix(cli): retry a refused JSON input close and keep the read's refusal beside incomplete cleanup parseCliJsonInput gives the file's owner a resource scope, so a transient close refusal is retried before the command fails. A close that still fails reports cleanup_incomplete composed with the read's own refusal. Routed commands refuse routes that check a shared JSON input differently, since it is checked before the route is chosen. * refactor(cli): project inspect-web-network-capture from its contract with nested protobuf options The contract builder flattens a nested optional object member in turn (protobuf.schema), resolves a flattened caller-path member and reports it as spelled under its dotted path in callerInputs, keeps a flattened member's contract default out of argv so an omitted member stays omitted, and takes an array of numbers as repeated decimal tokens within its bounds. inspect-web-network-capture registers from its contract with the same option names; Evidence keeps the capture and descriptor paths as the caller spelled them. CLI input issues name the capturePath argument. * fix(cli): name a selector field by its own option in admission issues A selector parameter's positional may share another key (decompile's procedure positional is address), so mapping the field to its positional key renamed selection issues that already name the option, such as a missing or conflicting --procedure. Map a selector field to its option. * fix(cli): retain a JSON input file whose close fails and keep why its read stopped parseCliJsonInput dropped its per-read scope after the owner's close retry failed, so the handle lost its owner, and a read or cancellation failure recorded before the close was replaced by the cleanup failure. The read's scope now stays with the CLI process until final CLI cleanup retries it, and the recorded outcome is translated once into the primary failure with the cleanup attached. The module moves into src/cli so it can register with the CLI process owner without a layer cycle. * refactor(cli): project inspect-with-objdump and inspect-api-contract from their contracts (#11142) * refactor(cli): project inspect-with-objdump, list-objdump-architectures and inspect-api-contract from their contracts The contract builder selects input branches by a field that is a literal in one branch and an enum in another, takes the default of the one branch that admits omission, and lets a command take a subset of a union's branches by their discriminating values, fixing the field when one value is selected. * refactor(cli): project trace-web-source-location from its contract with flattened positional objects (#11167) * refactor(cli): project trace-web-source-location from its contract with flattened positional objects The contract builder flattens required objects as well as optional ones; a flattened field listed in positionals takes its members as positionals in member order. The hand-written source-map limit options and the separate CLI delivery schema are removed. * fix(cli): refuse to flatten a required object without a required member * fix(cli): refuse a malformed Evidence-input document before reading the selected bundle runEvidenceInputCommand admits the document with its transport frame before it reads --evidence-bundle, so every Evidence-input command refuses a malformed document first, as compare-static-and-observed-endpoints already did by hand. * test(cli): expect a selector field to be named by its option in input issues * fix(cli): report a refused view before the delivery rule it would trip Refusing delivery options before JSON inputs are read checked --evidence_output before the view's own schema, so a summary view naming an unknown field reported only the missing bundle. Admit the view with the contract's view field first, as full admission does. * refactor(cli): project inspect-android-jni-bindings from its contract with a grouped --query option (#11196) * refactor(cli): project inspect-android-jni-bindings from its contract with a grouped --query option A projection's fieldGroups take several optional top-level contract fields as the members of one JSON object option. The text is decoded when the command runs, refused with the group's message when it is not a JSON object, a member that is not one of the group's fields is refused by its path, and the contract admits each member as its field. inspect-android-jni-bindings keeps its --query selection through a group and now registers through the contract builder, so the hand-registered contract command list is empty; the superseded parseCliAnalysisEvidenceDelivery and androidJniDeliverySchema are removed. * fix(cli): refuse an object rule that names a grouped field A grouped field is a JSON member, not an option, so a contract rule such as dependentRequired naming it would be advertised over an option that does not exist. Registration now refuses that combination. * fix(cli): describe the --view and --maxCaptureAgeMs options of projected commands A projected view field kept no help because the contract's own description was skipped and none replaced it, and compare-process-captures exposed max_capture_age_ms without help. The canonical CLI catalog test refused both. The view option now takes the same help in both builders. * refactor(cli): derive the CLI command inventory from the contract registry (#11248) A contract now declares `cli: true` when the CLI exposes it as the command named by its kebab-case name. The primary CLI inventory (CLI_COMMAND_NAMES, now owned by catalogIdentity.ts) is derived from those declarations plus the commands no contract names, and a contract projection omits `command`: the builder names the command from the contract and refuses a contract that does not declare one. CLI_COMMANDS keeps only the 32 commands no contract names; the 164 contract-named entries and the copied MCP-only list in cliToolCoverage.test.ts are removed. * fix(managed): keep decoded members when only their loaded literals exceed capacity A capacity failure while decoding #US literals discarded the member facts already decoded, because the shared representation budget threw through the whole inspection. Literals carry their own coverage, so the inspection is retried without them and reports user_strings as partial with the capacity issue. compare-managed-members, which now runs full inspections, keeps comparing members it used to read with literals disabled. * test(cli): expect builder-admitted issues by CLI key and option help with its default Builder admission of compare-web-captures, compare-web-screenshots and analyze-web-bundle names input issues by the CLI key (beforeJson, afterJson, normalizationJson, endpoint), and --integrity-policy help states its default. Four test files still expected the contract field names and the old help, so they failed on the stack. * test(cli): read each refused browser input's CLI path directly now that every case names one Every invalid browser input now carries its CLI key, so the fallback branch narrowed to never and failed the TypeScript compiler's typecheck. * chore(verify): carry the moved cliJsonInput baseline entry into its per-guard file Rebased on main after #11316 split the guard baselines and #11181 threaded the launch environment into the web bundle command; the contract-built analyze-web-bundle command now passes that environment to the browser provider. * refactor(cli): hand whole-input contract handlers the admitted parse instead of parsing again (#11301) * refactor(cli): hand whole-input contract handlers the admitted parse instead of parsing again * refactor(cli): parse an argv whole input only when the handler reads it Admission parsed every argv whole-input command eagerly, so handlers that hand the raw input to a service (inspectWithService) parsed it twice. parseWholeInput now parses on the first admittedContractInput call and reuses the result; run-time JSON and view delivery still parse at admission. The test counts whole-schema evaluations. * refactor(cli): hand JSON-document handlers the admitted parse of their document (#11332) observe-native-calls, capture-electron-scenario and match-native-functions parsed their resolved document against the contract schema in the handler. registerContractDocumentCommand now gives each document handler parseWholeInput, a memoized parse of the resolved document as the whole contract input whose refusal names the caller's spelling, so admittedContractInput serves argv and document commands alike. A handler whose document is not the whole input never calls it, so it adds no parse. * fix(cli): admit checked JSON inputs through their checks only compare-process-captures walked and copied both capture records again in the whole-input parse after their checks had admitted them. Admission now parses the remaining fields with the contract and hands the handler the checked documents uncopied. The managed summary example names --evidence_output.
1616 lines
87 KiB
Markdown
1616 lines
87 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.
|
||
For a pinned, noninteractive workflow with retained reports, see
|
||
[static analysis in GitHub Actions](../ci-analysis.md).
|
||
|
||
## 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](../guides/javascript/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
|
||
```
|
||
|
||
The request can also name the saved file instead of embedding it:
|
||
`{"source": {"kind": "evidence-file", "path": "app-evidence.json"}, "view": {"kind": "summary"}}`.
|
||
The CLI resolves a relative path against the working directory; MCP clients
|
||
pass an absolute path. REA reads and authenticates the file, then projects it
|
||
like retained Evidence, so a large file is bounded by the file reader rather
|
||
than charged as inline input.
|
||
|
||
An argument that accepts inline JSON or a JSON file path also accepts `-`, which
|
||
reads the request from standard input, so a generated request needs no
|
||
temporary file:
|
||
|
||
```bash
|
||
jq -nc '{source: {kind: "evidence-file", path: "app-evidence.json"}, view: {kind: "summary"}}' | rea inspect-analysis-view -
|
||
```
|
||
|
||
Standard input is read once as a single UTF-8 JSON document without a
|
||
byte-order mark, and it is limited to 8 MiB. Put a larger request in a file.
|
||
|
||
Local file inspection commands reject empty paths and NUL bytes before resolving
|
||
relative inputs, auxiliary files or output destinations. An empty string never
|
||
selects the working directory; use an explicit `.` when selecting that directory
|
||
is supported by the command.
|
||
|
||
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](../guides/javascript/javascript-application-workflows.md) for
|
||
views, feature traces and comparisons that take the same saved Evidence.
|
||
|
||
Add `--timings` to a command to write one JSON timing record to stderr. For
|
||
example, `rea inspect-elf-notes program --json --timings > result.json` keeps
|
||
stdout as a parseable result and writes
|
||
`{"rea_timings":{"version":1,"command_ms":42}}` to stderr. `command_ms`
|
||
measures CLI command dispatch and result delivery; it is not provider-only or
|
||
analysis-only time. The flag is off by default, and the record omits stages
|
||
that REA did not measure. Root version reporting does not dispatch a command
|
||
and has no command timing record.
|
||
|
||
## JSON Lines record output
|
||
|
||
Use `--format jsonl` to consume row-oriented results one record per line:
|
||
|
||
```bash
|
||
cat > observations-view.json <<'JSON'
|
||
{"source":{"kind":"evidence-file","path":"app-evidence.json"},"view":{"kind":"javascript-facts","property_keys":[],"offset":0,"limit":32}}
|
||
JSON
|
||
rea inspect-analysis-view observations-view.json --format jsonl > observations.jsonl
|
||
```
|
||
|
||
This request selects up to 32 observation identities and their provenance,
|
||
without observation property values.
|
||
|
||
This changes JSONL object-collection framing. Scripts that need one complete
|
||
report or a scalar field should use `--format json`. For a full application
|
||
graph, first project a supported analysis view rather than selecting an
|
||
arbitrary nested graph array.
|
||
|
||
A top-level array emits its elements in source order. An object must have one
|
||
clear `rows`, `items`, `records`, or `occurrences` array, directly or under
|
||
`page`. Evidence uses the same boundaries inside `normalized_result`.
|
||
Any other selection is refused before a record is written, including an
|
||
arbitrary report, a scalar, a nested array elsewhere, and a columnar object such
|
||
as the `inspect-sqlite-database --table` `normalized_result.rows`
|
||
(`{columns, values}`). The refusal is the caller error `invalid_request`
|
||
(`invalid_input`) and names the selection and its observed shape; the analysis
|
||
itself succeeded, so use `--format json` for the complete document. If several
|
||
collections exist, select one with `--filter-output`, for example
|
||
`normalized_result.rows` for an analysis view.
|
||
|
||
Object collections finish with a control record:
|
||
|
||
```json
|
||
{
|
||
"$rea": "jsonl/v1",
|
||
"type": "metadata",
|
||
"records": {
|
||
"path": ["normalized_result", "rows"],
|
||
"emitted": 2,
|
||
"source": 10,
|
||
"filter": "normalized_result.rows[0,2]"
|
||
},
|
||
"context": {
|
||
"evidence_id": "ev_…",
|
||
"normalized_result": {
|
||
"coverage": {
|
||
"status": "page",
|
||
"examined": 10,
|
||
"total": 100,
|
||
"next_offset": 10,
|
||
"exhausted": false
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
This abbreviated example illustrates framing. The actual `context` preserves
|
||
all non-row fields, including Evidence subject, provider, authority, confidence,
|
||
locations, links, limitations, parent/view digests, pagination and coverage.
|
||
With `--full-output`, it also retains the command envelope and its metadata.
|
||
A data filter selects row fields/slices while this context remains available;
|
||
excluded peer record collections and unselected Evidence `raw_result` are not
|
||
restored. An explicitly selected `raw_result` remains selected. Retain the
|
||
original Evidence for complete observations.
|
||
|
||
`records.emitted` and `records.source` count the selected output and its source
|
||
array; they do not assert analysis completeness. Source coverage and unknowns
|
||
retain their original meaning. Existing row identities and indices remain
|
||
unchanged unless your field selection excludes them. Empty object collections
|
||
still emit metadata; an empty top-level array emits no lines. Bare top-level
|
||
arrays have no synthetic coverage record.
|
||
|
||
Command and output-validation failures emit `{"$rea":"jsonl/v1","type":"error","ok":false,"result":…}`
|
||
and retain the original diagnostic payload. SDK validation/sentinel errors use
|
||
the SDK's exit status rather than guessing from data fields. `$rea` is reserved
|
||
at the top level of a data record, so control records are unambiguous; collisions
|
||
are refused before rows are written. Nested `$rea` values are ordinary data.
|
||
A missing final metadata record or nonzero exit can indicate an interrupted
|
||
export; do not treat already emitted rows as a complete result.
|
||
|
||
`--token-count` estimates this exact representation, including metadata, one
|
||
line at a time. Errors remain error records even with token counting enabled.
|
||
Token windows cannot preserve JSON Lines and are rejected. JSON encoding and
|
||
stdout writes are incremental, including large escaped strings; this is output
|
||
streaming over a completed result, not incremental analysis. The analysis still
|
||
needs its normal resources. A single record must fit the runtime string limit
|
||
for token estimation; remove `--token-count` to stream a larger record.
|
||
|
||
Standalone version and MCP doctor diagnostics remain single JSON documents
|
||
in JSON Lines mode. Incur's streaming generator events and successful sentinel
|
||
responses retain their SDK protocol. MCP application results and Evidence
|
||
contracts are unchanged.
|
||
|
||
## Shell completion
|
||
|
||
The CLI includes optional shell completion. Run `rea completions --help` to
|
||
see the available shells and their setup commands. For Bash, load the hook
|
||
into the current shell:
|
||
|
||
```bash
|
||
eval "$(rea completions bash)"
|
||
```
|
||
|
||
For zsh, initialize completion before loading the hook. If your shell already
|
||
runs `compinit`, place the hook after that existing initialization:
|
||
|
||
```zsh
|
||
autoload -Uz compinit
|
||
compinit
|
||
eval "$(rea completions zsh)"
|
||
```
|
||
|
||
The Bash hook supports macOS system Bash 3.2. It uses optional completion
|
||
features when the shell provides them and falls back to portable registration.
|
||
Completion includes standard global options and the active command's options;
|
||
`rea mcp ` offers only `add` and `doctor`. Output-option values remain data when
|
||
resolving the command scope.
|
||
|
||
For future interactive non-login Bash sessions, add the command to
|
||
`~/.bashrc`. Interactive login Bash sessions read the first available file in
|
||
`~/.bash_profile`, `~/.bash_login`, and `~/.profile`; add the command to the
|
||
file your shell reads, or have that file source `~/.bashrc`. Remove the command
|
||
from the startup file to stop loading completion, and run `complete -r rea` to
|
||
remove the registration from the current shell. These are manual, opt-in
|
||
steps.
|
||
Completion is a discovery aid; use `rea COMMAND --help` to confirm the
|
||
available options and subcommands.
|
||
|
||
## 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.
|
||
|
||
Select `--detail summary --evidence_output /absolute/path/members.json` to
|
||
receive identity, selection, coverage, limitations and collection counts while
|
||
saving the complete original Evidence in a new bundle. Summary requires that
|
||
explicit destination; existing files are preserved. Later
|
||
`inspect-analysis-view` calls can page the exact parent from the saved bundle
|
||
without reopening the assembly. See
|
||
[CLI summary and saved member rows](../guides/managed/managed-code-analysis.md#cli-summary-and-saved-member-rows)
|
||
for the complete command sequence. Omitted or `--detail complete` retains the
|
||
full inline response.
|
||
|
||
`compare-managed-members` is a composite command. It runs
|
||
`inspect-managed-members` on its baseline path and then on its candidate path,
|
||
with the same `--type`, `--max-snapshot-bytes` and
|
||
`--max-metadata-representation-bytes` options, and compares the two records as
|
||
MCP `compare_managed_members` does:
|
||
|
||
```bash
|
||
rea compare-managed-members /absolute/path/v1/Assembly.dll /absolute/path/v2/Assembly.dll --type Example.Parser --json
|
||
```
|
||
|
||
The comparison Evidence records both selected paths and those options. Two
|
||
identical spellings of one path select the same Evidence and are refused. When
|
||
the candidate fails, the error names its argument. Every failure keeps each
|
||
completed side's member Evidence in `details.argument_observations` as
|
||
`{argument: "left" | "right", observation}`, beside any
|
||
`details.partial_observation` the failing step retained itself, such as the
|
||
completed comparison when cancellation arrives as it settles.
|
||
|
||
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. For the image, type and method
|
||
names in a Unity `global-metadata.dat`, use
|
||
[IL2CPP metadata](../il2cpp-metadata.md). NativeAOT method bodies require native
|
||
analysis. See the [managed-code guide](../guides/managed/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](../guides/data/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](../guides/native/go-binaries.md)
|
||
for supported containers and absent or malformed metadata.
|
||
|
||
Inspect a Godot PCK without running the game:
|
||
|
||
```sh
|
||
rea inspect-artifact game.pck --detail summary --evidence_output evidence.json --json
|
||
rea extract-artifact game.pck --json
|
||
```
|
||
|
||
Formats 2, 3 and 4 retain header, directory and integrity facts. Compact delivery
|
||
keeps complete Evidence in the requested bundle. See [Godot PCK](../godot-pck.md)
|
||
for embedded packs, batch queries and unknown encrypted coverage.
|
||
|
||
Inspect a UnityFS AssetBundle without running Unity:
|
||
|
||
```sh
|
||
rea inspect-artifact content.bundle --detail summary --evidence_output evidence.json --json
|
||
rea extract-artifact content.bundle --json
|
||
```
|
||
|
||
Format versions 6 through 8 retain header, block and directory facts with
|
||
none/LZ4/LZ4HC block decompression. See [UnityFS](../unityfs.md) for encryption
|
||
and LZMA coverage boundaries.
|
||
|
||
Inspect a WeChat mini-program package without WeChat or an unpacker:
|
||
|
||
```sh
|
||
rea inspect-artifact app.wxapkg --detail summary --evidence_output evidence.json --json
|
||
rea extract-artifact app.wxapkg --json
|
||
```
|
||
|
||
Plaintext packages retain header, table and member facts with verbatim member
|
||
bytes. `V1MMWX` packages are detected as encrypted coverage and refused on
|
||
extraction. See [wxapkg](../wxapkg.md) for layout and coverage boundaries.
|
||
|
||
Inspect an ESP32-family app or bootloader image without esptool:
|
||
|
||
```sh
|
||
rea inspect-artifact firmware.bin --json
|
||
rea extract-artifact firmware.bin --json
|
||
```
|
||
|
||
The inventory lists each segment with its ESP-IDF load classification, the
|
||
checksum and SHA-256 results, the descriptor and any Secure Boot v2 signature
|
||
blocks. See [ESP images](../esp-image.md) for recognition, coverage and refusals.
|
||
|
||
Inspect an ESP flash dump, or one read from a flash address other than 0:
|
||
|
||
```sh
|
||
rea inspect-artifact flash.bin --json
|
||
rea inspect-artifact dump.bin --target-format esp-flash-image --flash-offset 0x1000 --json
|
||
rea extract-artifact flash.bin --json
|
||
```
|
||
|
||
The inventory lists the bootloader, the partition table and each partition,
|
||
with ESP image facts for app partitions and the OTA records. See
|
||
[ESP flash images](../esp-flash-image.md) for table location, inputs and limits.
|
||
|
||
Inspect a Node.js SEA carrier without running it:
|
||
|
||
```sh
|
||
rea inspect-artifact ./application --json
|
||
rea extract-artifact ./application --json
|
||
```
|
||
|
||
See [Node.js SEA](../node-sea.md) for supported layouts, script and asset paths,
|
||
fuse observations, and the real-fixture verification lane.
|
||
|
||
Inventory and extract Intel HEX or S-record regions:
|
||
|
||
```sh
|
||
rea inspect-artifact ./firmware.hex --json
|
||
rea extract-artifact ./firmware.hex --json
|
||
```
|
||
|
||
See [Intel HEX and S-record images](../hex-records.md) for recognition, region
|
||
names, metadata and limits.
|
||
|
||
Inspect and extract stored U-Boot legacy uImage payloads and components:
|
||
|
||
```sh
|
||
rea inspect-artifact ./firmware.bin --detail summary --evidence_output firmware.json --json
|
||
rea extract-artifact ./firmware.bin --json
|
||
```
|
||
|
||
See [U-Boot uImage](../uimage.md) for verified CRCs, physical component ranges,
|
||
unknown names, resource limits and retained views. Compressed bytes stay stored.
|
||
|
||
`inspect-artifact` and `extract-artifact` also read ZIP members compressed with
|
||
Zstandard (standard method 93). They retain the shared ZIP CRC, declared-size,
|
||
overlap and archive expansion checks. The native streaming decoder keeps the
|
||
existing 128 MiB Zstandard window cap; frames requiring a larger window are
|
||
reported as a resource limit (`reason: limit`, `boundary: memory`), rather than
|
||
as archive corruption. The cap cannot be raised at runtime: recompress with a
|
||
window of at most 128 MiB, or decompress externally before retrying.
|
||
Deprecated method 20 and other unregistered ZIP codecs remain unsupported.
|
||
|
||
Inventory and extract UF2 or DfuSe regions:
|
||
|
||
```sh
|
||
rea inspect-artifact ./firmware.uf2 --json
|
||
rea extract-artifact ./firmware.dfu --json
|
||
```
|
||
|
||
See [UF2 and DfuSe images](../uf2-dfuse.md) for recognition, families, numbering,
|
||
the DfuSe suffix CRC and limits.
|
||
|
||
Inventory and extract U-Boot FIT images:
|
||
|
||
```sh
|
||
rea inspect-artifact ./boot.itb --json
|
||
rea extract-artifact ./boot.itb --json
|
||
```
|
||
|
||
See [U-Boot FIT images](../fit-images.md) for recognition, data sources, hashes
|
||
and limits.
|
||
|
||
Inspect local model declarations without loading weights:
|
||
|
||
```bash
|
||
rea inspect-model-artifact /absolute/path/model.gguf --json
|
||
rea inspect-model-artifact /absolute/path/model.safetensors --hash full --json
|
||
```
|
||
|
||
Default hashing reads only headers and leaves full-file identity unknown.
|
||
`--hash full` streams the complete file for SHA-256. Both return typed metadata,
|
||
original tensor declarations and derived totals. MCP summaries retain complete
|
||
Evidence for filtered metadata, tensor and type-total pages; CLI compact delivery
|
||
uses `--detail summary --evidence_output FILE`. See [model files](../model-artifacts.md).
|
||
|
||
Inspect Unity IL2CPP metadata names without Unity or a disassembler:
|
||
|
||
```bash
|
||
rea inspect-il2cpp-metadata /absolute/path/global-metadata.dat --json
|
||
```
|
||
|
||
The command decodes a version 24, 27, 29, 31 or 39 `global-metadata.dat` and reports assembly
|
||
images, type, method and member names, string literals, index ranges, header
|
||
sections and SHA-256. With `--binary PATH` it also reads the matching
|
||
`GameAssembly.dylib`, `GameAssembly.dll` or `libil2cpp.so` (never runs it) and
|
||
links each method to its code address; `--generic-instances` adds generic
|
||
method instances and `--ghidra-seeds PATH` then writes Ghidra function seeds. It does not decrypt metadata. MCP defaults to compact counts
|
||
with retained Evidence; query indexed rows with filters, batch indices and
|
||
selected fields. The CLI defaults to complete Evidence;
|
||
`--detail summary --evidence_output FILE` exports the full result to a new file
|
||
and returns a compact overview. See [IL2CPP metadata](../il2cpp-metadata.md).
|
||
|
||
Inspect an embedded cargo-auditable Rust dependency list without installing
|
||
Rust or configuring a disassembler:
|
||
|
||
```bash
|
||
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](../rust-binaries.md).
|
||
|
||
Inspect a PE Authenticode certificate table without executing the image or
|
||
verifying signatures:
|
||
|
||
```bash
|
||
rea inspect-pe-certificates /absolute/path/to/application.exe --json
|
||
```
|
||
|
||
The workflow reports `WIN_CERTIFICATE` entries and, for PKCS#7 signedData,
|
||
embedded X.509 serial, issuer, subject, and validity fields. A missing security
|
||
directory is observed absence of that table. See
|
||
[PE Authenticode certificate tables](../pe-certificates.md).
|
||
|
||
Inspect PE import and delay-load tables without executing the image:
|
||
|
||
```bash
|
||
rea inspect-pe-imports /absolute/path/to/application.exe --json
|
||
```
|
||
|
||
The workflow reports DLL names, named and ordinal functions, delay-load
|
||
descriptors, and a pefile-compatible import hash of the standard import table.
|
||
A missing import directory is observed absence of that table. See
|
||
[PE import and delay-load tables](../pe-imports.md).
|
||
|
||
Inspect a Windows Shell Link (`.lnk`) without resolving or executing the
|
||
target:
|
||
|
||
```bash
|
||
rea inspect-windows-shortcut /absolute/path/to/shortcut.lnk --json
|
||
```
|
||
|
||
The workflow reports header flags and FILETIMEs, IDList items, LinkInfo volume
|
||
and network names, StringData arguments and icon location, ExtraData blocks
|
||
including Tracker droid facts labelled derived, and derived observations such
|
||
as argument length and a minimized ShowCommand. See
|
||
[Windows Shell Link shortcuts](../guides/native/windows-shortcut.md).
|
||
|
||
Inspect ELF PT_NOTE and SHT_NOTE tables without executing the image:
|
||
|
||
```bash
|
||
rea inspect-elf-notes /absolute/path/to/program --json
|
||
```
|
||
|
||
The workflow reports note owners, types, descriptor hashes, and GNU build-id
|
||
or ABI-tag fields when those descriptors match. A missing note table is
|
||
observed absence of those declarations. See [ELF note tables](../elf-notes.md).
|
||
|
||
List ELF and Mach-O initializer and finalizer functions without executing the
|
||
image:
|
||
|
||
```bash
|
||
rea inspect-native-initializers /absolute/path/to/program --json
|
||
```
|
||
|
||
The workflow reports `DT_INIT`, init/fini arrays, legacy `.ctors`/`.dtors`, and
|
||
Mach-O `__mod_init_func`, `__init_offsets` and `__mod_term_func` entries with
|
||
their resolved targets. Universal Mach-O files need `--architecture`. See
|
||
[ELF and Mach-O initializer functions](../guides/native/native-initializers.md).
|
||
|
||
Inspect ELF unwind function ranges without executing the image:
|
||
|
||
```bash
|
||
rea inspect-elf-unwind-ranges /absolute/path/to/program --json
|
||
```
|
||
|
||
The workflow reports FDE start, end, and size, the containing section, an exact
|
||
symbol name when one exists, CIE identity, LSDA, and personality. Coverage
|
||
counts ranges that match a symbol, ranges without a symbol, and whether the
|
||
`.eh_frame_hdr` search table agrees with the decoded FDEs. `.debug_frame` is
|
||
reported present, absent, or incomplete and is not decoded. A missing unwind table is
|
||
observed absence of those declarations. See
|
||
[ELF unwind function ranges](../guides/native/elf-unwind-ranges.md).
|
||
|
||
Inspect an Apple `.ips` crash report without executing a target:
|
||
|
||
```bash
|
||
rea inspect-apple-ips /absolute/path/to/report.ips --json
|
||
```
|
||
|
||
The workflow reports first-line metadata, process/exception/termination facts,
|
||
threads, usedImages, lossless integer registers, and documented crash classes
|
||
when `bug_type` is `"309"`. Other DiagnosticReports types return no crash
|
||
result. See [Apple IPS crash reports](../apple-ips.md).
|
||
Inspect Linux kernel module metadata without executing the module or requiring
|
||
`modinfo`:
|
||
|
||
```bash
|
||
rea inspect-kernel-module /absolute/path/to/module.ko --json
|
||
```
|
||
|
||
The workflow reports ordered `.modinfo` keys (duplicate `alias` and `parm`
|
||
entries preserved), `__versions` symbol CRCs, presence of
|
||
`.gnu.linkonce.this_module` and `__ksymtab` sections, observed `.init.text`
|
||
and `.exit.text` sizes, and an appended signature trailer. `struct module` is
|
||
not decoded and the signature is not validated. Other ELF types are not
|
||
applicable. gzip, xz, and zstd containers are unsupported and name
|
||
`external_decompression` as the next probe: decompress with an external
|
||
utility, then inspect the decompressed file. See
|
||
[Linux kernel modules](../kernel-modules.md).
|
||
|
||
Read a Linux kernel image's version banner and embedded `CONFIG_IKCONFIG`
|
||
build config without executing it:
|
||
|
||
```bash
|
||
rea inspect-kernel-build-config /absolute/path/to/vmlinux --json
|
||
rea inspect-kernel-build-config /absolute/path/to/bzImage --name CONFIG_MODULE_SIG --json
|
||
```
|
||
|
||
The workflow reports the banner version, builder, and compiler, the config
|
||
option count, and paged `CONFIG_*` entries (`y`, `m`, strings, numbers, and
|
||
`not_set`). An `IKCFG_ST` string counts as a config only when a valid gzip
|
||
member follows it and `IKCFG_ED` follows that member. A gzip bzImage payload
|
||
is inflated and searched; other payload codecs are unsupported and name
|
||
`external_decompression` as the next probe. See
|
||
[Linux kernel build config](../guides/native/kernel-build-config.md).
|
||
|
||
Inspect a CPython 3.7–3.15 `.pyc` header and nested marshal code objects
|
||
without executing bytecode or installing Python:
|
||
|
||
```bash
|
||
rea inspect-python-pyc /absolute/path/to/module.pyc --json
|
||
```
|
||
|
||
The workflow reports the pinned CPython version for the magic, PEP 552 hash or
|
||
mtime/size fields, nested function names, and bytecode SHA-256. Bytecode is
|
||
not decompiled. See [CPython pyc inspection](../python-pyc.md).
|
||
|
||
Inspect an Erlang BEAM file without executing bytecode:
|
||
|
||
```bash
|
||
rea inspect-erlang-beam /absolute/path/to/app.beam --json
|
||
```
|
||
|
||
The workflow reports IFF chunk names, atom tables, exports, imports, lambdas,
|
||
and the Code chunk header. Missing optional tables stay null. See
|
||
[Erlang BEAM files](../erlang-beam.md).
|
||
|
||
Complete `rea decompile --json` Evidence can be saved and inspected through
|
||
`inspect-analysis-view` with an inline source and
|
||
`view: {kind: "native", facet: "pseudocode", offset: 0, limit: 20000}`.
|
||
The projection reads that saved observation without starting a provider;
|
||
offsets/limits count UTF-16 code units. A summary view preserves the original
|
||
selector and distinguishes null from empty text. The MCP tool additionally
|
||
supports `detail: "summary"` on its first call to retain the complete source
|
||
without returning the body inline; see [native investigation](../guides/native/native-investigation.md).
|
||
|
||
Configure [Hopper or Ghidra](installation.md#hopper), the
|
||
[IDA adapter](../providers/ida-provider.md), or [Kuna](../kuna-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.
|
||
|
||
A complete dossier can reach several megabytes of value-flow and references.
|
||
`rea function ... --detail summary --evidence_output /absolute/path/dossier.json` returns the
|
||
compact summary and saves the complete dossier as an Evidence bundle, never
|
||
overwriting an existing file. Page that bundle without reanalysis by naming it
|
||
as an `inspect-analysis-view` source, selecting the summary's
|
||
`normalized_result.parent_evidence_id` when the bundle holds several records:
|
||
`{"source": {"kind": "evidence-file", "path": "/absolute/path/dossier.json", "evidence_id": "ev_…"}, "view": {"kind": "native", "facet": "pseudocode", "offset": 0, "limit": 4096}}`.
|
||
MCP `analyze_function` defaults to the same summary and retains the complete
|
||
dossier in the session for `inspect_analysis_view`.
|
||
|
||
Run `rea --help` or a command's `--help` for arguments and output options.
|
||
The [generated catalog](../reference/mcp-contracts.md#generated-catalog) lists all CLI commands and MCP
|
||
tools. Provider-specific target support is described in the
|
||
[native guide](../guides/native/native-investigation.md), [DOS guide](../providers/ghidra-dos.md),
|
||
[raw binary guide](../providers/raw-binary.md), [GameCube DOL guide](../ghidra-dol.md), and
|
||
[Windows Ghidra guide](../providers/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`, follow `message`, `remediation.action`, and the original
|
||
reasons in `details.rejections`. Each rejection names its `origin`: `availability`
|
||
entries describe local readiness failures, including missing configuration or an
|
||
invalid existing registration; they do not establish target support. `target`
|
||
entries record a refused kind, format, architecture, or role. An availability-only
|
||
message describes the recorded rejections without claiming that every provider
|
||
is unconfigured or that target support is known.
|
||
For Hopper, Ghidra, IDA, JADX, and Kuna, 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](installation.md#check-readiness-for-your-task) and
|
||
[provider selection](../reference/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](../reference/mcp-contracts.md) for session lifecycle and
|
||
[Ghidra first-query deadlines](../reference/mcp-contracts.md#ghidra-first-query-deadlines-and-recovery)
|
||
for import, client timeouts and recovery.
|
||
|
||
One-shot binary analysis validates the selected operation's input before creating
|
||
a provider session, opening the target, or replaying a snapshot. Invalid selectors
|
||
and option combinations report their input errors before target or provider
|
||
availability errors. An already-cancelled request keeps its cancellation reason.
|
||
Caller-selected paths and request parameters remain separate from parsed execution
|
||
arguments in Evidence.
|
||
|
||
A one-shot command attempts provider-session and runtime cleanup before reporting
|
||
a failure. If cleanup remains incomplete, inspect the reported resources and
|
||
follow the error's remediation. [Same-session cleanup retry](../reference/mcp-contracts.md#retained-cleanup-retry),
|
||
reuse and `update_analysis_settings` apply to a live MCP connection.
|
||
For one-shot commands, `details.limit` reports `scope: "rea-invocation"` and
|
||
`applies_at: "next_invocation"`; set the named `environment` (or the per-call
|
||
`parameter`) for a new invocation and rerun. For example, a Ghidra decompile
|
||
deadline names `REA_GHIDRA_DECOMPILE_TIMEOUT_SECONDS`.
|
||
|
||
`rea debug-with-gdb` and `rea debug-with-rizin` hold their debugger only for the
|
||
command's own process. If cleanup cannot confirm the debugger stopped, they print
|
||
`cleanup_incomplete` and exit nonzero without stopping it. `remediation.action`
|
||
names the process, as does `retained_debugger_pids` in `details.diagnostics`, or
|
||
in `details.diagnostics.cleanup_error.details.diagnostics` when the command also
|
||
failed or was interrupted. Exiting closes the debugger's command and output pipes.
|
||
REA does not establish what the debugger or its target does next, so check that
|
||
process. An MCP server that shuts down likewise exits with status 1 instead of
|
||
waiting on a debugger it could not stop. It names the process on stderr and as
|
||
`retained_debugger_pids` in its error log.
|
||
|
||
If one-shot analysis fails and closing its session also fails, the original
|
||
error details remain inline and `details.cleanup_error` describes the later
|
||
close failure. Each diagnostic retains its own reported resources; the later
|
||
failure does not establish whether an earlier resource was released. Captured
|
||
output and partial observations remain in the original details.
|
||
|
||
## 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.
|
||
|
||
Malformed snapshot headers or entries remain integrity failures. The diagnostic
|
||
keeps the first schema issue's location and message, plus the number of further
|
||
issues, rather than replacing it with a constant validation reason. File-selection
|
||
and JSON-syntax failures remain distinct; internal exception objects and stacks
|
||
are not serialized into the public error.
|
||
|
||
A binary CLI replay reports the current invocation's selected path while leaving
|
||
the saved Evidence and snapshot query unchanged. See
|
||
[caller-selected paths](../reference/mcp-contracts.md#caller-selected-paths)
|
||
for primary and auxiliary path fields and their relation to Evidence identity.
|
||
|
||
Importing an Evidence bundle refreshes retained request and subject display metadata.
|
||
It preserves cached analysis results, including observations for other targets.
|
||
Snapshot bindings that use a replaced record retain its updated display path.
|
||
|
||
Dispatching a provider 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.
|
||
|
||
Saved snapshots include only cache entries whose subject identifies the selected
|
||
target. Unbound observations and observations of child artifacts remain available
|
||
in the open session and its Evidence bundle; they are excluded from the target's
|
||
saved replay entries without changing their subjects.
|
||
The snapshot also retains available Evidence linked by selected records, including
|
||
transitive sources with an unbound or different subject. Those sources are not
|
||
replay entries for the selected target. Unrelated records remain excluded.
|
||
|
||
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 normally read before starting a provider process.
|
||
`decompile --provider ghidra --snapshot ...` also retains its single selected
|
||
Program's pseudocode result, even without an explicit document selector. Old
|
||
snapshots that contain only the Evidence need one new query to add that replay
|
||
entry. This does not retain every body from `decompile-all` or make a persistent
|
||
session's implicit document replayable.
|
||
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.
|
||
|
||
When a validated snapshot does not match the selected binding, the error's
|
||
`details.binding_mismatch` reports confirmed target identities, provider
|
||
identities, or profile digests that differ. `snapshot` is the saved value and
|
||
`selected` is the requested value. Multiple differences can be reported. A
|
||
`profile_comparison: "not_compared"` means the profile was not available at
|
||
that boundary; it does not establish a match. A profileless snapshot can report
|
||
`workflow_scope: "incompatible"` even when its target and profile match.
|
||
Choose a matching target, provider, and profile, or analyze without the snapshot
|
||
and save a new one for the intended binding.
|
||
|
||
For a profile mismatch, the saved snapshot contains
|
||
`binding.analysis_profile.parameters`. If `binary_session` reports an active
|
||
profile whose digest matches `binding_mismatch.profile_digest.selected`, its
|
||
`analysis_provider_binding.analysis_profile.parameters` can be compared with
|
||
those saved parameters. A rejected switch leaves the previous session active,
|
||
so its profile may be different from the attempted selection; check the digest
|
||
before using it for this comparison. A configuration difference does not by
|
||
itself establish why analysis results differ.
|
||
|
||
If no target is open and you intend to inspect the selected binding, open that
|
||
target without the snapshot, then check its profile digest in `binary_session`
|
||
before comparing parameters. This may start the selected provider; the saved
|
||
snapshot remains a separate file.
|
||
|
||
If a selected snapshot's file descriptor cannot close, `open_binary` reports
|
||
`cleanup_incomplete`. `binary_session` reports `cleanup_pending` even when no
|
||
target opened. Retry `close_binary` to release the retained descriptor before
|
||
opening another target.
|
||
|
||
If a snapshot switch fails after the previous target was retired, restoration
|
||
keeps that target's analysis commitments with the replacement client. This
|
||
includes the native dispatch workflow profile on a profileless route, so its
|
||
existing snapshot and fresh observations retain the same provenance.
|
||
|
||
For native dispatch, the snapshot binding retains the reader profile; workflow
|
||
Evidence and `workflow_entries` retain the composed profile, which commits that
|
||
reader and the workflow's analysis caveats. Restoration preserves both profiles.
|
||
|
||
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.
|
||
When an MCP session replays a provider observation, its delivered Evidence identifies
|
||
the original observation through `evidence_links` and reports that the
|
||
provider was not rerun. The original and its available source records remain
|
||
in the investigation bundle.
|
||
|
||
## 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
|
||
rea compare left.json right.json --record_pairs '[{"left_evidence_id":"ev_<left-sha256>","right_evidence_id":"ev_<right-sha256>"}]' --json
|
||
```
|
||
|
||
Migration: replace `rea compare-bundles` with `rea compare`; the former command
|
||
has been removed. The MCP tool remains `compare_bundles`.
|
||
|
||
`rea evidence-import` performs process-local bundle authentication and
|
||
validation, reporting record and Unknown-revision counts. `unknowns_added`
|
||
counts revisions, not distinct Unknown IDs. It does not retain records in a
|
||
separate or background MCP server process. To retain records across calls in an
|
||
active MCP session, use the MCP tool `import_evidence_bundle` in that session.
|
||
|
||
`rea compare` compares records by Evidence identity and explicit pairs. It does
|
||
not read artifact contents: the inventories of two builds are unresolved
|
||
records, or one opaque change when you pair them. Use `compare-artifacts`,
|
||
described at the end of this section, to compare their contents.
|
||
|
||
`--record_pairs` accepts an inline JSON array or the path to a local JSON
|
||
file containing that array, matching MCP `compare_bundles.record_pairs`. For a
|
||
file, use `rea compare left.json right.json --record_pairs pairs.json --json`.
|
||
Pair IDs must exist on their named sides and be one-to-one. Without pairs,
|
||
one-sided membership remains unknown; REA does not infer correspondence from
|
||
position or display names.
|
||
|
||
Exports preserve an existing destination unless `--overwrite` is explicit.
|
||
|
||
Atomic Evidence output stages on the selected destination's filesystem. If the
|
||
OS pathname ceiling prevents its internal staging name, REA retries in a shorter
|
||
ancestor on that same filesystem and removes the unused stage. Existing output
|
||
protection still applies. A genuine pathname refusal uses `resource_constraint`
|
||
with `details.reason: path-limit` and `boundary: filesystem-path`.
|
||
|
||
For application traces and version comparisons, see
|
||
[JavaScript application workflows](../guides/javascript/javascript-application-workflows.md).
|
||
MCP [retained Evidence references](../reference/mcp-contracts.md#retained-application-evidence-inputs)
|
||
belong to one connection. Separate CLI calls can consume full saved records or
|
||
resolve exact retained IDs from an explicitly selected local bundle:
|
||
|
||
```bash
|
||
rea trace-application-feature request.json --evidence-bundle /absolute/path/evidence.json --json
|
||
```
|
||
|
||
Here `request.json` uses the same logical Evidence input as MCP, for example
|
||
`"application": {"kind":"retained-evidence","evidence_id":"ev_<64 lowercase hex characters>"}`.
|
||
Inline records and references may be mixed in the request's declared source
|
||
fields, including arrays and nested inputs. The bundle is read and authenticated
|
||
once for that command; no target is reopened, no producer is rerun, and no
|
||
record is selected by file order. Source identity, provenance, coverage and
|
||
partial or unknown facts agree with the complete inline form. When starting
|
||
from summary or inspection Evidence, select its
|
||
`normalized_result.parent_evidence_id` for a workflow requiring complete source
|
||
facts. Omit `--evidence-bundle` when all sources are inline.
|
||
|
||
The JSON workflow commands supporting this option are:
|
||
|
||
- `trace-application-feature`, `trace-javascript-semantics`,
|
||
`compare-application-versions`, `compare-javascript-export-shapes`,
|
||
`compare-source-to-bundle`, and `reconcile-javascript-runtime`.
|
||
- `import-managed-reconstruction`, `verify-managed-native-boundaries`, and
|
||
`project-managed-application-graph`.
|
||
- `project-android-application-graph`, `project-apple-application-graph`, and
|
||
`project-harmony-application-graph`.
|
||
- `compare-wasm-interfaces` and `inspect-analysis-view`.
|
||
|
||
For `inspect-analysis-view`, the request's source reference selects a parent
|
||
from the bundle for every supported view kind. Bundles exported from MCP work
|
||
for these commands. Its inline source form cannot also select a bundle.
|
||
A missing ID is refused with `details.reason: "missing"`;
|
||
supplying a bundle does not make incompatible Evidence valid for a workflow.
|
||
`compare-managed-members` keeps its two assembly paths and the
|
||
[member inspection options](#managed-assemblies-net) it applies to both sides,
|
||
and `compare-process-captures` keeps its two capture Evidence JSON paths. The bundle
|
||
option above selects an input. Producers write a new bundle with
|
||
`--evidence_output`; `inspect-managed-members` spelled that option
|
||
`--evidence-bundle` in earlier releases.
|
||
File selectors remain available only on contracts that explicitly support them.
|
||
|
||
Compare two artifact inventories with `compare-artifacts`. It takes the same
|
||
`left` and `right` input as MCP `compare_artifacts`: complete Evidence, or an
|
||
`evidence-file` source with an optional `evidence_id` that selects one record
|
||
from a bundle. Relative paths resolve from the working directory:
|
||
|
||
```bash
|
||
rea inspect-artifact old.zip --json > old.json
|
||
rea inspect-artifact new.zip --json > new.json
|
||
rea compare-artifacts '{"left":{"kind":"evidence-file","path":"old.json"},"right":{"kind":"evidence-file","path":"new.json"}}' --json
|
||
```
|
||
|
||
A one-shot `compare-artifacts` command keeps no session Evidence, so it refuses a
|
||
`retained-evidence` source with `details.reason: "missing"`. Select the record
|
||
from a saved bundle instead.
|
||
For an artifact summary selected from a bundle, include its complete parent
|
||
inventory in the same bundle. The command resolves that parent from the
|
||
authenticated file records; a summary-only file cannot supply missing facts.
|
||
|
||
## Import historical source
|
||
|
||
Historical source inventories preserve exact filenames, including literal backslashes
|
||
on POSIX hosts. Relative import lookup uses the recorded source file's owning
|
||
directory and decodes URL percent escapes once; encoded slash, NUL and malformed
|
||
escapes remain unresolved. A decoded backslash remains part of a filename rather
|
||
than a directory separator. This inventory lookup does not claim that Node can
|
||
load that filename or apply Node's runtime file-URL admission policy.
|
||
|
||
Import an older source tree to compare with the current artifact:
|
||
|
||
```bash
|
||
rea import-reference-source /absolute/path/to/source
|
||
rea import-reference-source /absolute/path/to/source --detail summary --outline-depth 2 --json
|
||
rea import-reference-source /absolute/path/to/source --exclude-paths '["vendor/","*.generated","!keep.generated"]'
|
||
```
|
||
|
||
The default (`--detail full`) returns the complete `HistoricalSourceGraph`.
|
||
Choose `--detail summary` for a `HistoricalSourceSummary` of that same committed
|
||
inventory: its `HistoricalSourceManifest` contains the semantic 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.
|
||
|
||
Known filesystem failures commit the operation, parsed errno, entry-relative
|
||
location and recovery guidance. Entry `local_diagnostics`, when present,
|
||
retains the exact host message, including local paths, outside the semantic
|
||
graph commitment. Equivalent permission failures therefore retain their manifest
|
||
identity after relocation while preserving original source diagnostics in full
|
||
output and visible summary outline entries. Other substantive limitations still
|
||
participate in the graph commitment.
|
||
|
||
An unreadable child directory remains a partial inventory entry. Directory-scoped
|
||
ignore policy is required before enumerating a directory that can be opened;
|
||
an unreadable or invalid policy still fails the import. Project negations cannot
|
||
override defaults or caller exclusions; caller patterns retain their own ordered
|
||
negations. Configured secret exclusions remain final.
|
||
|
||
`--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.
|
||
|
||
Import failures use the shared error contract (`code`, `category`, `message`,
|
||
`retryable`, and `remediation`). When reads completed before failure,
|
||
`details.diagnostics.partial` retains the reader facts, with file bytes as
|
||
arrays of byte values. Unresolved cleanup uses `cleanup_incomplete` and
|
||
retains the source failure and resource paths in `details`.
|
||
|
||
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. Root selection follows filesystem
|
||
symlink/parent semantics before canonical identity is derived. It honors
|
||
`.gitignore` files at the selected root and in traversed child directories,
|
||
with patterns relative to their containing directory and deeper negations
|
||
applied only when the parent was not excluded. Matching uses the nearest
|
||
repository's local `core.ignorecase` setting (false when unset), including the
|
||
shared configuration of linked worktrees. Policy and Git metadata reads retain
|
||
their descriptor cleanup under the import's resource owner; unreadable policy
|
||
is a typed failure, not an empty policy. Above-root `.gitignore` files, global
|
||
excludes, `.git/info/exclude`, config includes and worktree-specific config are
|
||
not loaded. The import also 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. Every exclusion records `entry_kind` (`unknown` when the
|
||
importer could not observe the kind); a saved graph whose exclusion lacks it is
|
||
malformed. 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.
|
||
|
||
Entries that change during an import retain an unavailable-entry diagnostic
|
||
alongside readable siblings. If enumeration of an already admitted root fails,
|
||
the graph keeps its observed children and records the root failure as a
|
||
top-level limitation. That partial inventory does not establish absence among
|
||
unexamined children. POSIX directory-entry bytes that are not valid UTF-8 cannot
|
||
be represented as graph paths; the containing directory (or root) is marked
|
||
unsupported, and REA does not access the entry through a replacement-character
|
||
name. Symlink targets are read as bytes too: a target that is not valid UTF-8
|
||
is retained as an unreadable symlink with its bytes reported in the limitation,
|
||
and is never resolved through a replacement-character path. Readable siblings
|
||
remain inventoried.
|
||
|
||
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. Exact dynamic-import
|
||
strings, expression-free templates and runtime-transparent TypeScript wrappers
|
||
retain their targets; computed imports remain unknown. TypeScript import-equals
|
||
dependencies remain `requires` relationships whether or not they are exported.
|
||
Historical dependencies also include TypeScript import types (`import("./dep").T`
|
||
and `typeof import("./dep")`) and declarations inside ambient module bodies;
|
||
these source relationships do not assert runtime loading. Language labels retain
|
||
the conventional case-sensitive `.C` (C++) and `.M` (Objective-C++) suffixes.
|
||
|
||
REA derives historical CommonJS paths only when the selected loader and its
|
||
base are proven: this includes the exact
|
||
`createRequire(new URL("./file.cjs", import.meta.url))` form and
|
||
`require.resolve` with `{ paths: [__dirname] }`. Exact optional-call forms such
|
||
as `require.resolve?.("./dep.cjs")` use the same loader and mutation facts. The
|
||
nearest inventoried package manifest supplies `.js`/`.ts` package facts to the
|
||
shared parser; explicit filename modes take precedence. A known ES module has no
|
||
implicit CommonJS wrapper, including when a factory is derived from an unbound
|
||
`require`. An unreadable, excluded or malformed manifest, or package scope outside
|
||
the selected inventory, leaves otherwise unproven loader resolution unknown with
|
||
the requested specifier and a reason. A nearest manifest without a `type` field
|
||
uses the shared parser's JavaScript module-syntax facts. Unresolved TypeScript,
|
||
JSX compilation and declaration contexts do not establish runtime wrapper bases.
|
||
Other custom bases and search options remain partial with unknown resolution and
|
||
the literal requested specifier. Overwritten resolver methods retain that uncertainty; they are not
|
||
attributed to Node. `require.main` is a module object, so calling it does not
|
||
establish a loader reference. These relationships do not establish execution;
|
||
Node's [`require.resolve`](https://nodejs.org/docs/v24.22.1/api/modules.html#requireresolverequest-options)
|
||
performs lookup without loading the target. An excluded `package.json`
|
||
also leaves package-directory selection unknown rather than treating the
|
||
manifest as absent and applying an `index` fallback.
|
||
|
||
Import requests use URL pathname semantics: query and fragment remain request
|
||
identity, percent escapes decode exactly once for inventory lookup, and encoded
|
||
separators or malformed escapes retain an unresolved relationship and diagnostic.
|
||
URL-bearing relationships retain the authored `source_specifier` separately from
|
||
the inventoried `to` path; distinct query/fragment requests remain distinct even
|
||
when they name the same file. CommonJS requests retain literal filename semantics
|
||
for percent signs, query marks and fragments.
|
||
|
||
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](../guides/javascript/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](../guides/web/browser-observation.md): inspect a selected page through CDP.
|
||
- [Browser scenarios](../guides/web/browser-scenario-contract.md): run declared interactions and capture their results.
|
||
- [Electron observation](../guides/javascript/electron-observation.md): inspect an Electron renderer or capture an application scenario.
|
||
- [Electron fuses](../electron-fuses.md): read packaged fuse bytes before expecting `--inspect` to reach an Electron main process.
|
||
- [Node/Electron Inspector](../guides/javascript/javascript-runtime-observation.md): record script locations and execution contexts.
|
||
- [Process capture](../guides/runtime/process-capture.md): run an executable and compare terminal, exit and filesystem observations.
|
||
- [Desktop application capture](../desktop-application-capture.md): launch a Linux desktop application and record its windows and home-directory state at checkpoints while it is used.
|
||
- [Desktop application state](../desktop-application-state.md): read a capture folder into the application's state files, typed views of each version and kinds of change.
|
||
- [Desktop application export](../desktop-application-export.md): write a capture folder as an agentenv computer app bundle with its class, skill and seed.
|
||
- [Desktop application tasks](../desktop-application-tasks.md): describe how a capture's files changed, then validate an agent-written task against the capture and export it with its verifier.
|
||
|
||
Runtime requests name the target and actions. Launched targets run with your
|
||
user permissions; consult the chosen guide for host requirements and effects.
|
||
|
||
## Serve MCP over streamable HTTP
|
||
|
||
`rea mcp` speaks stdio to the client that launched it. To serve the same MCP
|
||
catalog over streamable HTTP for one local client, such as an agent environment
|
||
runtime, start the dispatcher entry with `--http`:
|
||
|
||
```sh
|
||
rea mcp --http --port 8765
|
||
```
|
||
|
||
`--host` and `--port` default to `MCP_HOST` and `MCP_PORT` from the environment,
|
||
then to `127.0.0.1` and an ephemeral port. A bind outside loopback requires
|
||
`MCP_ALLOWED_HOSTS` or `--allowed-hosts`, a comma-separated list of client host
|
||
names or IP addresses without URLs or ports.
|
||
|
||
Repeat `--allowed-hosts` to append names, or put multiple names in one
|
||
comma-separated value. All occurrences are validated together and deduplicated
|
||
after hostname normalization; the explicit list replaces `MCP_ALLOWED_HOSTS`.
|
||
|
||
For example:
|
||
|
||
```sh
|
||
rea mcp --http --host 0.0.0.0 --allowed-hosts 127.0.0.1,rea.lan
|
||
```
|
||
|
||
Requests with a different `Host` or browser `Origin` receive `403`; a missing
|
||
`Origin` is accepted. The announced client URL uses the bound hostname when
|
||
admitted, otherwise the first declared hostname, with the actual bound port.
|
||
It is written to stderr as one JSON log line (`"msg":"MCP transport listening"`) whatever `REA_LOG_LEVEL`
|
||
is set to; nothing is written to stdout. `rea mcp --http --help` lists the accepted options. The listener serves
|
||
one client at a time: a session ends with the client's `DELETE`, and a client
|
||
that connects while another session is open takes it over, so a client that
|
||
exited without ending its session needs no restart. The listener runs until
|
||
SIGINT or SIGTERM and does not stop when stdin closes. See
|
||
[transports](../reference/mcp-contracts.md#transports) for the session, `Host` header and
|
||
shutdown contract. Client registrations written by setup and the MCP registry
|
||
entry keep stdio.
|
||
|
||
## Serve an environment manifest
|
||
|
||
`rea environment-serve <manifest.json> --evidence <capture.json>
|
||
[--replay-only] [--host H] [--port N]` serves an environment manifest
|
||
projected by `inspect-analysis-view` as an agent environment: an MCP server at
|
||
`/mcp`, the environment card at `/.well-known/agent-env.json`, and a
|
||
`/agentenv` data plane. The manifest's `parent_evidence_id` must equal the
|
||
evidence file's `evidence_id`; otherwise the command refuses with
|
||
`invalid_request` before binding. Before binding it derives the
|
||
`environment-state` view of the capture with the manifest's `template_rules`,
|
||
as `inspect-analysis-view` would, and serves from it: read tools whose views
|
||
are state-backed answer from a live state, write tools are served only where
|
||
the capture's later reads confirmed their effect, and
|
||
`/agentenv` serves `data/reset`, `data/add` and `data/get`. When the state
|
||
cannot be derived, or its catalog exceeds the discovery reservation, it logs a
|
||
warning with the error code and message and serves replay; `--replay-only` serves replay without deriving. In replay every
|
||
manifest tool replays the retained capture records it cites and `/agentenv`
|
||
answers every method with JSON-RPC `-32601`. The stopped document's `state`
|
||
member is `{"served": true, "evidence_id": …}`,
|
||
`{"served": false, "reason": "replay-only"}` or
|
||
`{"served": false, "reason": "unavailable", "code": …, "message": …}`; see
|
||
[serve from the state](../agent-environments.md#serve-from-the-state).
|
||
|
||
```sh
|
||
rea environment-serve manifest.json --evidence capture.json --port 8765
|
||
```
|
||
|
||
`--host` and `--port` resolve like `rea mcp --http`: flags, then `MCP_HOST` and
|
||
`MCP_PORT`, then `127.0.0.1` and an ephemeral port. A non-loopback bind requires
|
||
`MCP_ALLOWED_HOSTS` with the same hostname rules and Host/Origin gates as above.
|
||
`environment-serve` uses this environment setting; `--allowed-hosts` belongs to
|
||
`rea mcp --http`. For example:
|
||
|
||
```sh
|
||
MCP_ALLOWED_HOSTS=127.0.0.1,rea.lan rea environment-serve manifest.json --evidence capture.json --host 0.0.0.0
|
||
```
|
||
|
||
`ENVIRONMENT_NAME` renames
|
||
the served environment; set but blank, it is refused as `configuration_invalid`
|
||
like a blank `MCP_HOST`. The admitted client URL is written to stderr as one JSON log line
|
||
(`"msg":"MCP transport listening"`). See
|
||
[agent environments](../agent-environments.md) for what the state and replay
|
||
return and do not establish.
|
||
|
||
## Build an environment bundle
|
||
|
||
`rea environment-build <capture> [dir] [--name <name>] [--template-rule <rule> ...]
|
||
[--format-rules-only] [--package-tarball <path>] [--capture-timeout-ms <ms>] [--dry-run]` builds the bundle
|
||
`environment-export` writes from one recorded capture: a `.har` file, which it
|
||
inspects as `inspect-web-network-capture` does, or capture Evidence JSON from
|
||
`inspect-web-network-capture` (HAR) or `capture-browser-scenario`. It projects
|
||
the environment manifest from the in-memory Evidence with the opt-in rules
|
||
`after-uid-literal`, `opaque-token`, `sibling-variance` and `prefix-variance`
|
||
unless `--template-rule` or `--format-rules-only` selects others, prepares the
|
||
state, and writes the bundle; every file is byte-identical to the three-step
|
||
path's when that path lists the same rules in the views' order and exports
|
||
under the build's name. A loopback or IP-literal capture is named after its file unless `--name`
|
||
is given. It prints one JSON report: the capture and manifest identities, the
|
||
state, a `coverage` summary of which tools answer from the state, which replay
|
||
and why each write is withheld with a hint, the files, warnings and the next
|
||
command. `--dry-run` writes nothing and may omit the directory.
|
||
|
||
```sh
|
||
rea environment-build grafana.har ./grafana --json
|
||
```
|
||
|
||
See [agent environments](../agent-environments.md#build-a-bundle-in-one-step)
|
||
for the report, the hints and what the bundle ships.
|
||
|
||
## Export an environment bundle
|
||
|
||
`rea environment-export <manifest.json> --evidence <capture.json> <dir>
|
||
[--package-tarball <path>] [--name <override>]` writes the same manifest and
|
||
capture pair as a bundle folder the agentenv framework runs with
|
||
`agent-env run <dir>`. It reads each file once, authenticates and cross-checks
|
||
the pair with the same checks as `environment-serve`, checks the bundle name,
|
||
then prepares the state under that name as the bundle's server will at startup
|
||
to predict what the bundle serves (replay when the state is unavailable),
|
||
copies the bytes it authenticated, refuses to write into a directory that
|
||
exists and is not empty, and never overwrites a file.
|
||
|
||
```sh
|
||
rea environment-export manifest.json --evidence capture.json ./grafana-example --json
|
||
```
|
||
|
||
The folder holds a `README.md` with the bundle's provenance, an env folder
|
||
`envs/<name>/` with a `Dockerfile` that installs this exact `rea-agents`
|
||
version and serves the copied `manifest.json` and `evidence.json` (written
|
||
with mode `0600` on POSIX; Windows retains inherited ACLs) with
|
||
`environment-serve` (from the state by default), a Python verifier under
|
||
`artifacts/check_<name>/` that checks the served tool count and one served
|
||
answer, and the smoke task `tasks/smoke.json`. `--package-tarball` copies a packed `rea-agents`
|
||
tarball into the env folder and installs it instead of the registry package,
|
||
which is how the hosted lane proves a checkout rather than a release. `--name`
|
||
replaces the manifest's kebab-case name as the env folder and env id; a device
|
||
name Windows reserves (`con`, `nul`, `com1` and the like) is refused. The
|
||
command prints one JSON document listing the written files with their sizes,
|
||
the pinned package source, the served `tool_count`, and `state` in the shape
|
||
of the serve command's stopped document. See
|
||
[agent environments](../agent-environments.md#export-a-bundle) for the folder
|
||
layout and what the smoke task checks.
|
||
|
||
`rea environment-export` prints the written files and exits `0` on success.
|
||
Input-pair refusals, an occupied destination, a missing package tarball, and
|
||
invalid labels fail before writing output. Host permission failures identify
|
||
whether reading or writing was denied and retain the affected path.
|
||
|
||
A failure during writing can leave a partial folder. Inspect it before removing
|
||
it and retrying; the next attempt refuses a non-empty destination. When one
|
||
file caused the failure, the diagnostic names that file. A folder-sync failure
|
||
can report only its cause.
|
||
|
||
If `details.partial_observation.kind` is `environment-bundle-publication`, the
|
||
bundle was already published. Its `directory` and `files` record the committed
|
||
output, even when a later identity check or cleanup failed. Inspect that bundle
|
||
and resolve the reported failure before using or replacing it; the receipt is
|
||
not an instruction to delete published output. Cleanup resources remain a
|
||
separate obligation.
|
||
|
||
## Compare an environment with its application
|
||
|
||
`rea environment-compare <manifest.json> --evidence <capture.json> --probe <probe.json> [--probe <probe.json> ...]`
|
||
compares the environment the pair serves with probe captures of the application it came from. Each probe is capture
|
||
Evidence of one call sequence recorded against the application after a reset; the environment's state is reset before
|
||
each probe, every request to the application's origin is answered as the served environment answers it, and the
|
||
answer is compared with the application's after ids are mapped and clocks and generated values are normalised. The command reads files only and
|
||
makes no network call. It prints the report and exits `0`, or prints a structured `invalid_request` error and exits `1`
|
||
for the same pair refusals as `environment-serve`, a probe that is not capture Evidence, or a browser probe captured
|
||
without response bodies, or without the request bodies its writes need. See
|
||
[agent environments](../agent-environments.md#measure-fidelity-against-the-application) for the report.
|
||
|
||
```sh
|
||
rea environment-compare manifest.json --evidence capture.json --probe probe.json --json
|
||
```
|
||
|
||
## Report version and runtime
|
||
|
||
`rea --version` prints the package version. Add an output format to get the
|
||
version with the runtime and platform context that a support request needs:
|
||
|
||
Version reports do not initialize analysis providers. Invalid global settings
|
||
or output options still report their usual errors.
|
||
|
||
```bash
|
||
rea --version --json
|
||
```
|
||
|
||
```json
|
||
{
|
||
"name": "rea-agents",
|
||
"version": "6.7.0",
|
||
"runtime": { "id": "node", "version": "24.22.1" },
|
||
"platform": "linux",
|
||
"architecture": "x64",
|
||
"supported_runtime": {
|
||
"range": "^22.23.4 || ^24.22.1 || >=26.12.1",
|
||
"satisfied": true
|
||
}
|
||
}
|
||
```
|
||
|
||
| Field | Meaning |
|
||
| ------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
|
||
| `name`, `version` | Published package name and version; `version` matches plain `--version`. |
|
||
| `runtime.id` | `node` or `bun`. |
|
||
| `runtime.version` | Version of that runtime. |
|
||
| `runtime.node_compatibility_version` | Bun only: the Node.js version it reports compatibility with. |
|
||
| `platform`, `architecture` | Node.js `process.platform` and `process.arch`, such as `linux` and `x64`. |
|
||
| `supported_runtime.range` | Supported Node.js range. |
|
||
| `supported_runtime.satisfied` | Whether this runtime is supported, judged as `rea doctor` judges it; Bun by its Node.js compatibility version. |
|
||
|
||
The field names are stable. The report contains no paths, environment values,
|
||
user or host names, and it starts no provider and reads no target. `--format`
|
||
selects any CLI output format, such as `--format yaml`. JSON follows the usual
|
||
rule: indented on a terminal, compact when piped or redirected. `--help` still
|
||
takes precedence. With other output controls, `--version` keeps its existing
|
||
behavior: valid controls such as `--filter-output` or `--full-output` print the
|
||
plain version, and invalid combinations report the usual output-flag error,
|
||
such as `UNSUPPORTED_OUTPUT_COMBINATION` for `--json` with `--token-limit`. Use
|
||
`rea doctor` for provider and host readiness.
|
||
|
||
## Output and exit status
|
||
|
||
Commands reject surplus positional arguments before execution, including commands
|
||
that accept no positionals. Use `rea <command> --help` for the declared argument
|
||
shape; a final variadic argument continues to accept multiple values.
|
||
`rea mcp add` accepts options only and rejects unknown options before reading or
|
||
backing up client settings or starting registration. Its `--agent` and
|
||
`--command`/`-c` options accept spaced and equals forms. Values must be nonempty; a following flag does not satisfy a spaced option's
|
||
missing value.
|
||
|
||
Registration command text is a launcher format, not a shell program. ASCII spaces
|
||
separate words; single and double quotes delimit adjacent fragments of a word.
|
||
Backslashes, tabs, variables and shell punctuation are literal data. Quoted empty
|
||
arguments are preserved, including an empty argument after the executable. An
|
||
empty executable, unfinished quote or NUL character fails before registration. For example:
|
||
|
||
```sh
|
||
rea mcp add --agent cursor --command '"/path with spaces/server" "" --mcp' --json
|
||
```
|
||
|
||
The registered executable is `/path with spaces/server`, with arguments `""` and
|
||
`--mcp`. Windows backslashes use the same literal rules after the invoking shell
|
||
has passed the option value. With no `--command`, REA uses its exact current
|
||
runtime and entrypoint arguments without converting them to text and parsing them
|
||
again. No package acquisition or server execution occurs during registration.
|
||
`--no-global` refuses any selection requiring global storage before writing files.
|
||
|
||
`rea mcp add --schema --json` returns the named input and output JSON Schemas.
|
||
Successful and partial registration reports contain the exact `command`, `args`
|
||
and a `clients` outcome list. `ok` is true only when every selected client is
|
||
configured or unchanged. Failed clients retain actionable errors; cancellation
|
||
marks remaining clients `not_started`. A failed client does not erase a successful
|
||
sibling's receipt. Existing settings and environment overrides survive refresh;
|
||
backups identify the original bytes, and identical repeats create no new backup.
|
||
Client IDs are case-insensitive for the helper-compatible catalog; documented
|
||
aliases include `droid`/`factory`, `gemini`, `grok`, `kilo`/`kilocode`, `kimi`,
|
||
`kiro`, `mastra`, `pi-agent`, `hermes-agent`, `cline-vscode`, and
|
||
`codeium`/`cascade`. `github-copilot` selects VS Code; use
|
||
`github-copilot-cli` for Copilot CLI. Amp uses `--agent amp`.
|
||
|
||
Kilo project registration follows its native configuration layers and requires a
|
||
verified Git worktree. Selected `KILO_CONFIG`, `KILO_CONFIG_DIR` and
|
||
`KILO_CONFIG_CONTENT` overrides remain authoritative. A conflicting higher-priority
|
||
source must be updated before registration can succeed; readonly layers are never
|
||
copied into the selected file. An unknown project root fails before writing and
|
||
does not fall back to global settings.
|
||
|
||
`rea mcp add --command` accepts stdio launcher text. An HTTP(S) URL in the
|
||
executable position is refused before any settings change; configure remote MCP
|
||
transport in the client's own settings. Earlier delegated registration could
|
||
interpret a URL as remote transport for some clients while storing it as an
|
||
executable for Amp. That inconsistent URL interpretation and package acquisition
|
||
are removed. Launcher arguments that happen to contain URLs remain arguments.
|
||
|
||
`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. More than
|
||
32 MiB of combined child stdout and stderr stops the child and fails the check
|
||
in progress.
|
||
|
||
Doctor owns the server's process group on POSIX hosts, or its Job Object on
|
||
Windows. Before reporting, it stops that process family, including POSIX
|
||
descendants in other process groups that inherited its run token. If that
|
||
cleanup cannot be confirmed, the report keeps its earlier checks and adds a
|
||
failed `cleanup` check with the reason and retained run identifier.
|
||
|
||
The default terminal format is TOON. Use `--json` when saving results for a
|
||
JSON consumer. Valued output flags (`--format`, `--filter-output`,
|
||
`--token-limit`, `--token-offset`) accept `--flag value` or `--flag=value`; a
|
||
missing value fails with `MISSING_OUTPUT_VALUE` before the command runs.
|
||
Malformed format values and token windows fail with `INVALID_OUTPUT_VALUE` in the
|
||
selected structured format. Token limits and offsets must be nonnegative safe
|
||
integers; zero selects an empty window. These checks run before command execution. `--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. A formatting refusal exits nonzero even when
|
||
the underlying operation succeeded.
|
||
|
||
`--format md` escapes backslashes, pipes, and inline Markdown syntax in table
|
||
headers and cells so source text is displayed literally, and renders cell line
|
||
breaks as `<br>`. Underscores between letters or digits, as in `source_index`,
|
||
cannot form emphasis and stay unescaped. These are presentation changes; retained
|
||
Evidence and JSON output keep the original values. Nested objects and arrays
|
||
use JSON inside their owning Markdown cells, retaining the field names and
|
||
values instead of replacing them with an object label. Table widths are measured
|
||
iteratively, so an admitted row page is not limited by the JavaScript function
|
||
argument count.
|
||
|
||
Markdown refuses selected NUL characters and unpaired UTF-16 surrogates because
|
||
renderers or UTF-8 output would substitute them. TOON refuses selected unpaired
|
||
surrogates for the same UTF-8 reason. Use JSON or YAML to retain those values.
|
||
An authored replacement character and valid supplementary characters are not
|
||
treated as malformed.
|
||
|
||
`--format csv` and `--format tsv` export one selected row collection. Select an
|
||
exact array path with `--filter-output` and provide comma-separated direct
|
||
scalar columns with `--columns`; column order is the output column order:
|
||
|
||
For an artifact inventory request that selects the `occurrences` collection
|
||
and includes `logical_path` and `artifact_id` in its view fields:
|
||
|
||
```bash
|
||
rea inspect-analysis-view request.json --format csv \
|
||
--filter-output normalized_result.items --columns logical_path,artifact_id
|
||
```
|
||
|
||
The first line is a REA metadata record,
|
||
`# rea-delimited-v1 <JSON>`. It carries the selected path, view request, limitations and unknowns,
|
||
coverage, source coverage and completeness, command, and duration. A metadata
|
||
value of `null` means that the selected row collection did not provide that
|
||
fact; it does not mean complete coverage. The following line is the header.
|
||
CSV records use CRLF line endings; TSV records use LF. Cells containing the
|
||
delimiter, quotes, or line breaks are quoted and embedded quotes are doubled.
|
||
Values are emitted as UTF-8 without Unicode normalization. Missing and `null`
|
||
cells are empty; booleans and finite numbers use their ordinary text forms.
|
||
String cells and headers that begin with spreadsheet formula syntax are refused
|
||
with a structured error; unpaired surrogates in selected cells or headers are
|
||
also refused. JSON retains those values unchanged.
|
||
|
||
Delimited output does not flatten nested Evidence or nested field values.
|
||
It returns a structured error and a nonzero status if the filter does not
|
||
select exactly one row array, a row is not an object, or a selected cell is
|
||
nested or formula-leading. JSON remains the complete canonical output; use it
|
||
to retain fields outside the selected columns or preserve exact formula-leading
|
||
text. Token counting and token windows are not
|
||
available for CSV/TSV because slicing would corrupt records or metadata.
|
||
|
||
`--filter-output` selects fields from successful command data. Classified failures
|
||
retain their complete typed diagnostic projection even when the selector matches
|
||
a field such as `code` or `message`, or names a missing field. `--full-output`
|
||
controls whether the outer `{ok, error, meta}` envelope is included.
|
||
Selected own JSON members, including `__proto__`, remain ordinary output data.
|
||
|
||
Sibling array slices that select different fields are combined by original row
|
||
index and emitted in source order, regardless of selector order. Selecting a
|
||
whole parent row keeps that row intact and takes precedence over narrower fields
|
||
selected from the same row. For example, `rows[0,2].name,rows[1,3].version`
|
||
combines both fields for overlapping rows, while `rows[0,2],rows[1,3].version`
|
||
retains rows 0 and 1 whole.
|
||
|
||
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 no longer accepts command-local `--json=true` or `--json=false`.
|
||
Replace these with `--json-output=true` or `--json-output=false`, respectively.
|
||
Combine `--json-output` with bare `--json` when both Cutter command output and
|
||
the CLI result should use JSON; either argument order is accepted.
|
||
|
||
| 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. |
|
||
| `3` | `audit-release-exposure` completed with `--fail_on` and an exposed check meets that severity. Unknown and unassessed checks do not change this status. |
|
||
| `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. |
|
||
|
||
`rea mcp --http` is long-running and prints no structured result. It exits
|
||
`130` on SIGINT or `143` on SIGTERM after closing the listener, the session and
|
||
its providers, and `1` when that cleanup fails.
|
||
|
||
`rea environment-serve` is also long-running: it serves until SIGINT or
|
||
SIGTERM, closes the listener, then prints one structured
|
||
`{"status":"stopped", …}` document naming the URL, environment and tool count
|
||
and exits `130` or `143` through the shared cancellation handler below.
|
||
Refusals before binding (unreadable files, non-Evidence JSON, capture Evidence
|
||
in a format other than HAR, a manifest or state whose parent is not the
|
||
supplied evidence, an unbindable port) print a structured
|
||
error and exit `1`, as does a listener that fails after binding.
|
||
If shutdown fails, the command reports `cleanup_incomplete` with the retained
|
||
server resources. It preserves a primary listener diagnostic, or a
|
||
`shutdown_observation` naming the requested shutdown and its URL, environment,
|
||
tool count and Evidence identifiers. The successful `stopped` document is
|
||
returned only after cleanup is confirmed. The same in-process server owner
|
||
retains failed stages for retry; the CLI exposes no separate retry command.
|
||
`rea environment-build` is one-shot too: it prints its report and exits `0`,
|
||
or prints the refusing stage's structured error and exits `1`, writing nothing
|
||
when the refusal comes before the bundle is written. SIGINT cancels it with a
|
||
`cancelled` error; a cancellation before the bundle stage writes nothing.
|
||
A `cancelled` result does not by itself determine the exit status. Commands
|
||
that handle SIGINT or SIGTERM assign `130` or `143` after their operation and
|
||
cleanup settle; their structured result can be printed before that status is
|
||
assigned. Read the process status and typed result separately.
|
||
|
||
Commands with `--evidence_output` save the complete Evidence bundle before
|
||
delivering the selected view. For committed-file receipts, retained partial
|
||
Evidence and missing source records, see
|
||
[Evidence publication and source recovery](../reference/mcp-contracts.md#evidence-publication-and-source-recovery).
|
||
Other outputs have their own receipt shapes; for example,
|
||
[environment export](#export-an-environment-bundle) reports a published directory.
|
||
|
||
A failure that carries partial Evidence in `details.partial_observation`, such
|
||
as `provider_timeout` or `resource_constraint`, publishes that partial Evidence
|
||
to `--evidence_output` under the same new-file and atomic rules, then keeps its
|
||
error code, message and remediation when cleanup is confirmed. With `--detail summary`,
|
||
`details.partial_observation` holds the summary view of the partial Evidence
|
||
instead of the complete record, and `details.diagnostics.evidence_bundle`
|
||
reports the written path and byte count. Linked source records must all be
|
||
available before publication; missing sources leave the destination unchanged
|
||
and are reported in `details.source_closure`. A provider cleanup failure can
|
||
still publish its captured Evidence without clearing the cleanup error or its
|
||
resource ownership. If publication is refused before commit, for example because
|
||
the file already exists, the complete partial Evidence stays inline and `details.diagnostics.evidence_bundle_error` gives the
|
||
refusal's code, message and a limitation. A refusal after commit keeps the
|
||
receipt in `details.diagnostics.evidence_bundle` and the delivered view: when
|
||
staging cleanup stays incomplete, the code becomes `cleanup_incomplete`, the
|
||
original failure is retained in `details.execution_failure`, and `details` also carries `published`,
|
||
`published_path`, `bytes`, `cleanup: "incomplete"` and `resources`, as for a
|
||
successful run, and a later cancellation reports `cancelled` in
|
||
`evidence_bundle_error` with the signal's exit status. Without
|
||
`--evidence_output`, and for cancellation before publication or raw provider
|
||
observations, the failure output is unchanged.
|
||
|
||
When the reader of piped output closes early, as `rea ... | head` does, the
|
||
CLI stops writing, prints no error and exits `141` (`128 + 13`, the status of a
|
||
SIGPIPE-terminated writer). The operation itself may have completed; only its
|
||
output was declined.
|
||
|
||
`inspect-artifact` also returns a structured cancelled result. Its logging
|
||
wrapper sits outside the cancellation handler and replaces the signal-derived
|
||
status with the analysis failure 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`. For `setup` and
|
||
`environment-build`, explicit `--dry-run=true` and `--dry-run=false` are
|
||
accepted; empty or other values fail with `PARSE_ERROR` before any changes.
|
||
Every supplied value is checked even when a later occurrence overrides it.
|
||
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
|
||
```
|
||
|
||
`--token-count` reports a tokenx estimate for the selected emitted document,
|
||
including a requested full-output envelope and metadata. JSON uses the same
|
||
terminal indentation or compact piped representation as normal output; JSONL
|
||
uses its emitted line representation. The final newline is included (tokenx
|
||
assigns whitespace no tokens). This is an estimate, not a model tokenizer count.
|
||
Counting retains the existing bounded formatted-string allocation after capacity
|
||
admission; omit the flag to stream large JSON documents without materializing
|
||
the complete formatted text. Exhausted token windows display an empty range at
|
||
the total token count and have no next offset.
|
||
|
||
### `inspect-devicetree`
|
||
|
||
Inspect an explicit local FDT v16/v17 blob without execution or an external tool.
|
||
Returns header, reservations, node/property tree, derived standard values and
|
||
selected phandle references. See [devicetree inspection](../devicetree.md) for
|
||
limits and retained-view pagination.
|
||
|
||
```bash
|
||
rea inspect-devicetree /artifacts/board.dtb --json
|
||
rea inspect-devicetree /artifacts/board.dtb --detail summary --evidence_output /artifacts/board-evidence.json --json
|
||
```
|
||
|
||
### PE TLS and load configuration
|
||
|
||
```sh
|
||
rea inspect-pe-load-config /absolute/path/to/application.exe --json
|
||
```
|
||
|
||
Reports TLS callbacks and size-covered load-config fields without execution.
|
||
Use `--max-callbacks` and `--max-file-bytes` to set read budgets. See
|
||
[PE TLS and load configuration](../pe-load-config.md).
|
||
|
||
### Binary hardening
|
||
|
||
```sh
|
||
rea inspect-binary-hardening /absolute/path/to/program --json
|
||
```
|
||
|
||
Reports ELF, PE, and Mach-O hardening rows without execution. A missing import
|
||
is `unknown`, not `disabled`. Use `--max-file-bytes` to set the read budget. See
|
||
[binary hardening](../binary-hardening.md).
|
||
|
||
Bun standalone executables use the existing `inspect-artifact` and
|
||
`extract-artifact` commands to inventory and materialize embedded source,
|
||
sourcemaps and bytecode without running the executable. See
|
||
[Bun standalone executables](../bun-standalone.md) for layout coverage and limits.
|
||
|
||
### Release exposure
|
||
|
||
```sh
|
||
rea audit-release-exposure /absolute/path/to/MyApp.app --json
|
||
rea audit-release-exposure ./dist/MyApp.app --fail_on high --json
|
||
```
|
||
|
||
Reports what static analysis of a shipped `.app`, install directory, ASAR, or
|
||
executable recovers. `--fail_on high|medium|low` exits `3` when a completed
|
||
audit has an exposed check at that severity. Unknown and unassessed checks stay
|
||
in the report and do not change the exit status. See
|
||
[Release exposure](../release-exposure.md).
|
||
Deno compile executables use the same commands to inventory and materialize the
|
||
embedded virtual filesystem, remote modules, and recorded options. Inventory retains
|
||
embedded environment-file values and certificate bytes in local Evidence with their
|
||
counts and byte lengths, and extraction does not write them as files. The npm snapshot
|
||
length is reported and not decoded, and the executable is not run. See
|
||
[Deno compile executables](../deno-standalone.md).
|