# Reference

Look up an exact command, configuration field, result contract or API.
The generated pages follow the source tree this site was built from;
authored compatibility and protocol pages explain their evidence and scope. To learn the tool,
start at [Getting started](https://ambiqai.github.io/helia-profiler/getting-started/); to understand a choice,
the [User guide](https://ambiqai.github.io/helia-profiler/guide/); to see it done, [Examples](https://ambiqai.github.io/helia-profiler/examples/).

- [Engine configuration](https://ambiqai.github.io/helia-profiler/reference/engine-configuration/): Configure engine-specific options, source builds and dependency overrides.
- [Command line](https://ambiqai.github.io/helia-profiler/reference/cli/): Every argument and option with type, default and help text, one page per command, plus the JSON and Markdown artifacts an agent can read.
- [Configuration](https://ambiqai.github.io/helia-profiler/reference/configuration/): The ProfileConfig schema by top-level key, with defaults and CLI mappings where available.
- [Issue codes](https://ambiqai.github.io/helia-profiler/reference/issue-codes/): Every stable code a run or a comparison can report, with its severity and meaning.
- [Python API](https://ambiqai.github.io/helia-profiler/reference/api/): profile(), Session, the configuration models, the typed results and the error hierarchy, grouped by what they are for.
- [Compatibility table](https://ambiqai.github.io/helia-profiler/reference/compatibility/): One status per cell, each traced to a nightly hardware validation record or to the sources that label a target experimental.
- [Compatibility baseline](https://ambiqai.github.io/helia-profiler/reference/compatibility-baseline/): The exact module and engine revisions hpx qualifies, how a run stamps its qualification state, and what the baseline does not cover.
- [Wire protocol](https://ambiqai.github.io/helia-profiler/reference/wire-protocol/): Every line the profiler firmware prints and the one command the host writes back, for people changing the templates or the parser, not a user API.

## Commands at a glance

| Command | Does |
|---|---|
| [`hpx profile`](https://ambiqai.github.io/helia-profiler/reference/cli/profile/) | build, flash, capture, report |
| [`hpx analyze`](https://ambiqai.github.io/helia-profiler/reference/cli/analyze/) | static model analysis on the host |
| [`hpx compare`](https://ambiqai.github.io/helia-profiler/reference/cli/compare/) | compare two result bundles, optionally against a regression profile |
| [`hpx validate`](https://ambiqai.github.io/helia-profiler/reference/cli/validate/) | the hardware-in-the-loop suite over the registered models |
| [`hpx doctor`](https://ambiqai.github.io/helia-profiler/reference/cli/doctor/) | check the toolchains and probes; `--bundle` writes a redacted support archive |
| [`hpx boards`](https://ambiqai.github.io/helia-profiler/reference/cli/boards/), [`hpx engines`](https://ambiqai.github.io/helia-profiler/reference/cli/engines/) | list the registered boards and engines |
| [`hpx probes`](https://ambiqai.github.io/helia-profiler/reference/cli/probes/), [`hpx ports`](https://ambiqai.github.io/helia-profiler/reference/cli/ports/) | list and match J-Link probes and host serial ports |
| [`hpx target`](https://ambiqai.github.io/helia-profiler/reference/cli/target/) | reset helpers for the attached board |
| [`hpx power-on`](https://ambiqai.github.io/helia-profiler/reference/cli/power-on/) | hold the instrument's passthrough power on |
| [`hpx cache`](https://ambiqai.github.io/helia-profiler/reference/cli/cache/) | inspect or purge the local build caches |

## Conventions

- `hpx profile model.tflite` is a shortcut for `model.path`; with a config
  file, omit the positional argument and pass `--config hpx.yml`.
- A flag on the command line overrides the same field in the config file;
  the resolved configuration is recorded in the run's `run_metadata.json`.
- `-v` adds `INFO` logs and `-vv` adds `DEBUG`; every subcommand accepts
  `--help`.
- Exit codes: 0 on success, non-zero on any `HpxError`, and 3 for an
  invalid run under `--fail-on-invalid`.
- Machine-readable copies of the generated surfaces sit beside each page
  (`cli.json`, `schema.json`, `issues.json`, the Markdown renditions and
  `llms.txt`), and every content page has a Markdown rendition at the same
  route with `index.md` appended.