# Command line

The `helia-aot` command line is generated from the same configuration model the reference documents, so an option here is a setting there.

| Command | What it does |
| --- | --- |
| [helia-aot convert](https://ambiqai.github.io/helia-aot/reference/cli/#helia-aot-convert) | Convert a model to standalone C inference module. |
| [helia-aot list-targets](https://ambiqai.github.io/helia-aot/reference/cli/#helia-aot-list-targets) | List all supported target platform names. |
| [helia-aot target-info](https://ambiqai.github.io/helia-aot/reference/cli/#helia-aot-target-info) | Show the capabilities of a given target platform. |
| [helia-aot version](https://ambiqai.github.io/helia-aot/reference/cli/#helia-aot-version) | Display the version of the heliaAOT library. |

For a complete conversion, start with the [walkthrough](https://ambiqai.github.io/helia-aot/getting-started/convert/). Use YAML for nested lists and mappings; see [configuration precedence](https://ambiqai.github.io/helia-aot/guide/configuring/).

A conversion exits nonzero on failure. Capture both stdout and stderr when investigating it: conversion progress and error diagnostics go to stderr, while the final Results output goes to stdout, and some input failures retain Python tracebacks. Verbosity controls logging detail, not whether the conversion succeeded. See [troubleshooting](https://ambiqai.github.io/helia-aot/guide/troubleshooting/) and the [error reference](https://ambiqai.github.io/helia-aot/reference/errors/).

## helia-aot convert

Convert a model to standalone C inference module.

```sh
helia-aot convert [OPTIONS]
```

### General options

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `--path` | `str` | — | Path to yaml configuration |
| `--transforms` | `str` (repeatable) | `[]` | Transforms configuration |
| `--operators` | `str` (repeatable) | `[]` | Operator attributes and optimization knob overrides |
| `--verbose` | `int` | `1` | Verbosity level (default: 1) |
| `--force` / `--no-force` | `boolean` | `false` | Force conversion even if output exists (default: False) |
| `--keep-work-dir` / `--no-keep-work-dir` | `boolean` | `false` | Keep the temporary work directory and log its path (default: False) |
| `--log-file` | `str` | — | Optional log file path |

### Model options

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `--model.path` | `str` | `model.tflite` | Path to target model file (default: model.tflite) |
| `--model.subgraph` | `int` | `0` | Subgraph index (default: 0) |
| `--model.type` | `str` | — | Model type (e.g., tflite, litert) |
| `--model.name` | `str` | `model` | Model name (default: model) |
| `--model.description` | `str` | — | Description of the model |
| `--model.version` | `str` | `v1.0.0` | Model version (default: v1.0.0) |

### Module options

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `--module.path` | `str` | `output.zip` | Output path for the generated module. Use a directory for an unpacked module, a '.zip' suffix for a generic zip archive, or a '.pack' suffix for an Open-CMSIS-Pack archive (requires module.type=cmsis_pack). (default: output.zip) |
| `--module.type` | `neuralspot` \| `zephyr` \| `cmake` \| `nsx` \| `cmsis_pack` | `neuralspot` | Module type (default: neuralspot) |
| `--module.name` | `str` | `helia_aot_nn` | Module name (default: helia_aot_nn) |
| `--module.prefix` | `str` | `aot` | Prefix added to sources for unique namespace (default: aot) |
| `--module.schedule` | `table` \| `static` | `table` | Operator dispatch shape in the generated model: 'table' (default) keeps the runtime function-pointer table and per-node callback seam; 'static' emits straight-line direct calls (no table, no loop, no indirect dispatch). (default: table) |

### Test options

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `--test.enabled` / `--no-test.enabled` | `boolean` | `false` | Include test case (default: False) |
| `--test.tolerance` | `float` | `1` | Test tolerance (default: 1.0) |
| `--test.skip-verification` / `--no-test.skip-verification` | `boolean` | `false` | Skip runtime output verification (default: False) |
| `--test.golden-data` | `str` | — | Golden input/output npz file |
| `--test.num-iterations` | `int` | `1` | Number of times to run the same stimulus through the model (default: 1) |
| `--test.state-feedback` | `str` (repeatable) | `[]` | (output_index, input_index) pairs copied back between iterations for streaming recurrent-state carry |

### Memory options

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `--memory.planner` | `greedy` \| `greedy_by_size` \| `hill_climb` | `greedy` | Memory planner strategy (greedy_by_size and hill_climb are experimental) (default: greedy) |
| `--memory.planner-options` | `str` | `{}` | Planner tunables as JSON, validated against the selected planner's option schema (hill_climb: iterations, seed, max_stall_iterations) |
| `--memory.constraints` | `str` (repeatable) | — | Memory constraints (ordered by preference) |
| `--memory.tensors` | `str` (repeatable) | `[]` | Tensor attributes |
| `--memory.allocate-arenas` / `--no-memory.allocate-arenas` | `boolean` | `true` | If true, the module will use internal, statically allocated arenas. If false, the caller must bind every region via `<prefix>_bind_arena()` / `<prefix>_bind_arenas()` before model_init. (default: True) |
| `--memory.auto-hydrate-constants` / `--no-memory.auto-hydrate-constants` | `boolean` | `true` | Deprecated — retained for backwards compatibility but no longer changes generated runtime behavior. model_init always invokes hydrate_constants between context_init and the operator init loop. Override the weak hydrate_constants symbol for custom hydration mechanisms (DMA / async pre-stage / model swap). (default: True) |
| `--memory.dump-residency-json` / `--no-memory.dump-residency-json` | `boolean` | `false` | If true, write a machine-readable residency report (``<prefix>_residency.json``) alongside the emitted module. Mirrors the verbose log summary as JSON for tooling that needs to introspect arena layout, staged-vs-cold residency, and per-tensor placement post-planning. (default: False) |

### Platform options

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `--platform.name` | `str` | `apollo510_evb` | Target platform name (default: apollo510_evb) |
| `--platform.cpu` | `str` | — | CPU core type (e.g., cortex-m55) |
| `--platform.speeds` | `str` (repeatable) | `[]` | List of supported clock speeds in MHz |
| `--platform.memories` | `str` | `{}` | Memory sizes in bytes |
| `--platform.capabilities` | `str` (repeatable) | `[]` | List of SoC capabilities |
| `--platform.preferred-memory-order` | `str` (repeatable) | `[]` | Preferred memory order for allocations |
| `--platform.min-alignment` | `int` | — | Minimum alignment requirement in bytes |

### Documentation options

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `--documentation.html` / `--no-documentation.html` | `boolean` | `false` | Generate html documentation site (experimental). (default: False) |

### Optimization options

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `--optimization.goal` | `latency` \| `balanced` \| `size` \| `accuracy` | `balanced` | What auto knob values favor: latency, balanced (today's defaults), size or accuracy (default: BALANCED) |
| `--optimization.allow-approximate` / `--no-optimization.allow-approximate` | `boolean` | `false` | Allow auto knob values that change numerics relative to the knob's default (e.g. fast accumulation) (default: False) |
| `--optimization.accumulation` | `auto` \| `precise` \| `fast` | `auto` | FP16 accumulation: precise (standard layout, the library's default accumulation), fast (packed FP16 weights, one FP16 chain per output) or auto (default: AUTO) |
| `--optimization.kernel` | `auto` \| `specialized` \| `generic` | `auto` | Int8 convolution and depthwise entry: specialized (shape-specialized ns-cmsis-nn direct entries where they apply), generic (the general entries, fewer kernels linked) or auto; both are exact (default: AUTO) |

### Other options

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `-h` / `--help` | `boolean` | `false` | Show this message and exit. |

```text
Quick start:

helia-aot convert --model.path model.tflite --module.path ./out

helia-aot convert --path my-model.yaml --verbose 2

helia-aot convert --model.path model.tflite --module.type zephyr --test.enabled
```

## helia-aot list-targets

List all supported target platform names.

```sh
helia-aot list-targets [OPTIONS]
```

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `-h` / `--help` | `boolean` | `false` | Show this message and exit. |

## helia-aot target-info

Show the capabilities of a given target platform.

```sh
helia-aot target-info [OPTIONS]
```

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `--name` | `str` | required | Target platform name, as reported by `list-targets`. |
| `-h` / `--help` | `boolean` | `false` | Show this message and exit. |

## helia-aot version

Display the version of the heliaAOT library.

```sh
helia-aot version [OPTIONS]
```

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `-h` / `--help` | `boolean` | `false` | Show this message and exit. |