# Header7F local investigation CLI

The CLI runs the **same pure Linux and typed-map engines as the browser** on saved files. It makes no network requests, uses no account or AI service, and does not collect data from a device. Node.js 22 or newer is required; no packages are needed for these commands. Keep the CLI beside its engine modules when copying it elsewhere.

From the extracted bundle directory:

```sh
node header7f-investigate.mjs --help
node header7f-investigate.mjs linux capture.json
node header7f-investigate.mjs linux capture.json --logs relevant-kernel-excerpt.txt --json investigation.json --markdown investigation.md
node header7f-investigate.mjs map --definition reviewed-map.json --incident incident.json --baseline baseline.json --json comparison.json --markdown comparison.md
```

Paths are literal filesystem arguments. There is no shell execution, automatic device discovery, stdin capture or URL input. Use files already collected through your approved workflow. `/dev`, `/sys` and `/proc` inputs are refused. The separate Linux collector has its own collection and config-read boundaries.

## Input contracts

- **Linux:** one `header7f.linux-evidence.v1` JSON capture, at most 1 MiB. Optional `--logs` supplies a UTF-8 excerpt of at most 256 KiB and explicitly replaces the JSON's kernel-log input for this run. The combined serialized capture and log must remain within 1 MiB.
- **Typed map:** `header7f-device-map-v1`, at most 512 KiB, with explicit device/IP/revision/address-space/ordering, source provenance and user review. Incident and optional baseline use `header7f-mapped-capture-v1`, at most 2 MiB each. Map ID, revision, document fingerprint, scope and declared device instance must match. The existing schema also bounds fields and supplied byte/word arrays.
- Inputs must be saved regular files containing valid UTF-8. Missing bytes/words remain unknown; malformed values are rejected. PCI configuration offsets, context bits and BAR offsets remain separate address spaces.

Map imports support the typed-map contract, not the prepared QDMA investigation-bundle format or PDF files. Build and review the typed map in Spec Lab first. Raw PDF extraction, live capture, cloud saving and device writes are outside this CLI.

## Reports and CI decisions

JSON goes to stdout unless `--json PATH` is supplied. `--markdown PATH` additionally writes a readable report. Reports contain the exact engine analysis; mapped reports also contain the exact baseline comparison. Inputs and exports may contain proprietary evidence, so review them before sharing or putting them in CI logs.

| Exit | Meaning |
| --- | --- |
| `0` | All selected mapped fields were captured and no modeled issue/change was found. With no baseline, no change comparison was performed. |
| `1` | The Linux engine found a modeled attention condition, or the mapped comparison contains captured changes. |
| `2` | No modeled attention/change took priority, but evidence is incomplete. |
| `3` | Invalid input, arguments, scope, encoding or output destination; no valid investigation decision was produced. |

Priority is **invalid → modeled issue/change → incomplete → selected checks clear**. Reports explicitly say whether an issue and incomplete evidence coexist. A changed field can be expected; exit `1` is a review signal, not a root-cause verdict.

**Exit `0` never means hardware is healthy or DMA completed.** Linux metadata normally leaves mapping, completion and interrupt-delivery evidence missing, so a capture with no modeled fault usually returns `2`. The CLI does not measure performance, establish full protocol compliance, validate physical provenance or prove the absence of faults.

A shell/CI runner may stop on exits `1` or `2`. Preserve the report and handle the status according to the investigation; do not silently reinterpret incomplete evidence as a pass.

## Output protection

Only explicit `--json`/`--markdown` paths are written. Existing outputs are refused unless `--force` is supplied. Inputs cannot be overwritten even with `--force`, including hard-link and symlink aliases. Output symlinks and duplicate output files are refused. Both output destinations are checked before existing files are truncated. Output files are private (`0600`) when newly created.

Errors use short messages on stderr without echoing evidence, raw parser exceptions, filesystem paths or tokens. A filesystem failure can leave a partially written report; this is reported as exit `3`. This is a local CLI, not a sandbox for untrusted machine access.

## Run the included synthetic example

Keep all four .mjs files in this directory. No installation or packages are needed.

```sh
node header7f-investigate.mjs map --definition examples/map.json --incident examples/incident.json --baseline examples/baseline.json
```

This intentionally returns exit 1: CTRL changed from 0x12345678 to 0x12345679, while STATUS was not captured. Compare the output with examples/report.json and the recorded execution in examples/cli-synthetic-run.json. Exit 1 is a review signal, not a hardware fault verdict. To see exit 0 for the selected captured fields, use examples/baseline.json as both incident and baseline. To see incomplete evidence (exit 2), omit --baseline when using examples/incident.json.

## Integrity and source evaluation

Compare this ZIP's SHA-256 with the published cli-release.json before copying it to an isolated lab. The release is unsigned; a checksum checks integrity, not publisher identity. files.json records the included files' SHA-256 values. Read SOURCE-LICENSE.txt: this is source for local evaluation, with no new open-source or redistribution license granted by the bundle.

Repository process tests cover the extracted ZIP and all four CLI exit codes; test tooling is not included in this download.