# nsx flash

Build and flash a generated NSX app

## Usage

```text
nsx flash [-h] [--app-dir APP_DIR] [--board BOARD]
                 [--build-dir BUILD_DIR] [--toolchain TOOLCHAIN]
                 [--target TARGET] [--sdk-root SDK_ROOT]
                 [--probe-serial PROBE_SERIAL] [--jobs JOBS] [--update]
                 [--frozen] [--timeout SECONDS]
                 [app]
```

## Arguments

| Option | Value | Default | Description |
| --- | --- | --- | --- |
| app | value | optional | App name or directory (overrides --app-dir; resolved under ./ and ./examples) |

## Options

| Option | Value | Default | Description |
| --- | --- | --- | --- |
| --app-dir APP_DIR | value | . | App directory containing nsx.yml |
| --board BOARD | value | optional | Override board from nsx.yml |
| --build-dir BUILD_DIR | value | optional | Build directory override |
| --toolchain TOOLCHAIN | value | optional | Toolchain override (gcc, armclang, atfe) |
| --target TARGET | value | optional | Optional executable target to flash |
| --sdk-root SDK_ROOT | value | optional | Optional out-of-tree AmbiqSuite root passed as NSX_AMBIQSUITE_ROOT_OVERRIDE |
| --probe-serial PROBE_SERIAL | value | optional | Optional SEGGER J-Link USB serial number to use |
| --jobs JOBS | value | 8 | Parallel build jobs |
| --update | flag | optional | Re-resolve module constraints to upstream tip and re-vendor before flashing |
| --frozen | flag | optional | When a (re)configure is needed, error on any drift between nsx.yml, nsx.lock, and modules/ instead of correcting it; modules missing from modules/ are fetched at their locked revision and verified. Note: passing --probe-serial always forces a reconfigure; --frozen only changes how the accompanying module sync behaves, not whether it runs. |
| --timeout SECONDS | value | optional | Wall-clock budget per subprocess (seconds). Kills the whole process group on timeout. |

## Notes

J-Link Commander is discovered from `JLINK_PATH`, `PATH`, or the standard SEGGER install
locations on Linux, macOS and Windows. The resolved path is passed into CMake so discovery
is consistent across NSX operations.

Flashing uses the board-defined flash settings and requires the selected target's `.bin`
and the generated `jlink/<target>/flash_cmds.jlink` recipe. A successful process exit is
rejected unless J-Link reports an actual flash-download operation.

`--sdk-root` warns that `nsx.lock` and the SBOM no longer describe the flashed binary,
cannot be combined with `--frozen`, and forces a reconfigure when it differs from the
cached override. With `--frozen`, explicit probe selection still forces configure.

```bash
cd <app-dir>
nsx flash

# Flash another executable finalized by the same NSX/CMake project.
nsx flash --target hpx_profiler_power
```

`--app-dir` names the app directory containing `nsx.yml`; when it is omitted NSX searches
upward from the current directory. The positional `app` argument overrides `--app-dir` and
is resolved under the current directory and under `examples/`.

The out-of-tree SDK escape hatch is described under [SDK provider selection](/neuralspotx/guides/modules/sdk-providers/) in the guides.

`--target` names an executable to flash; omitting it selects the app's primary
executable.

`-v/--verbose`, `-q/--quiet` are parsed by `nsx` itself, so they go before the command name, as `nsx -v flash`.