# Build, flash and view [Configure and build](https://ambiqai.github.io/neuralspotx/getting-started/configure-and-build/) and [Flash, reset and view](https://ambiqai.github.io/neuralspotx/getting-started/flash-and-view/) walk the five commands in order. This page is the working reference for their behavior: what each one does when you run it repeatedly, how they find your app, and the few behaviors that surprise people. Full option tables are generated from the CLI itself and live under [the CLI reference](https://ambiqai.github.io/neuralspotx/reference/cli/). ## Which commands know about your app `configure`, `build`, `flash`, `view` and `clean` find the app by walking up from your working directory until they find an `nsx.yml`, so you can run them from anywhere inside the tree. They all take `--app-dir` to point somewhere else, and all take a positional `app` argument that resolves under `./` and `./examples`. `reset` and `probes` are not app-aware. `probes` enumerates the J-Link probes attached to the machine. `reset` talks to a target directly and requires `--device`, so the app-directory framing does not apply to it. ## Configure `nsx configure` resolves the module graph, writes `nsx.lock` if there is not one, syncs `modules/` to match it, and runs CMake to generate `build//`. It is safe to re-run. NSX re-configures on its own when `build.ninja` is missing or when you pass `--probe-serial`, which always forces a reconfigure because the probe serial is baked into the generated SEGGER command files. ## Build `nsx build` configures first if no build tree exists, so on a fresh app `nsx build` alone is enough. It drives Ninja through CMake and leaves the linked image, the `.bin` and the `.map` in `build//`. `--jobs`, `--target` and `--update` are accepted by both `build` and `flash`. `--jobs` sets the parallelism. `--target` selects a CMake target to build, or an executable to flash. `--update` re-resolves constraints to upstream tip and re-vendors first. :::caution[`--sdk-root` and `--frozen` are mutually exclusive] `--sdk-root` points the build at an SDK tree on your machine instead of the vendored one. That tree is not recorded in `nsx.lock`, so the build is no longer reproducible from the lock and NSX rejects the combination rather than producing a binary it cannot account for: ```text --sdk-root (/opt/AmbiqSuite) cannot be combined with --frozen: ... Drop one of the two flags. ``` ::: ## Flash `nsx flash` builds if the image is missing or out of date, then drives the generated SEGGER flash target. NSX reads J-Link's own output to decide whether the program actually happened, looking for either a `Flash download: Total` summary or a `Skipped. Contents already match` notice. If J-Link exits successfully but prints neither, NSX tells you rather than assuming success, because different J-Link Commander releases word the summary differently. The device was most likely programmed; the echoed J-Link output above the message is what to read. `--probe-serial` selects one probe when several are attached. Run `nsx probes` to list them. ## View `nsx view` opens the SEGGER SWO viewer against the running firmware. ### The reset policy By default `view` resets the target as it attaches, so you see output from the start of `main`. Four SoCs are the exception and default to attaching without a reset: `apollo3p`, `apollo4l`, `apollo4p` and `apollo510b`. On those, NSX says what it is doing: ```text Using attach-only SWO view for this secure-reset SoC; flash first or pass --reset-on-open to force a reset. ``` This set is defined in the NSX source, not inferred from the SoC family name, so it does not line up neatly with "all Apollo4" or "all secure parts". Override it either way with `--reset-on-open` or `--no-reset-on-open`. `--reset-delay-ms` controls how long NSX waits after the reset before reading, and defaults to 400. ### Capturing instead of watching `--capture ` writes the stream to a file as well as the terminal, and `--duration ` stops the viewer after a fixed time. Together they are what you want in a script or a CI job, where no one is there to press Ctrl-C. Prefer `--duration` to wrapping the command in `timeout`. NSX stops the SEGGER viewer when the command ends: on Ctrl-C, when `--duration` expires, and on an error. On Linux and macOS it also stops the viewer when `nsx` receives `SIGTERM` or `SIGHUP`, as from `timeout`, `kill` or a canceled CI step, and then exits with status 128 plus the signal number. On Linux the viewer also exits if `nsx` is killed outright, and on Windows it is tied to `nsx` by a job object. A viewer left running would hold the J-Link SWO port and block the next `nsx view` on any board. ## Reset `nsx reset --device ` resets a target without touching an app. The device name is the J-Link device identifier for the part, which for a generated app appears as the `-device` argument in `build//build.ninja`. ## Clean ```bash nsx clean # run the build system's clean target nsx clean --full # remove the build directory outright nsx clean --reset # also remove modules/ and .nsx/ ``` `--reset` takes the app back to the state of a fresh clone, so the next `nsx configure` re-fetches everything from `nsx.lock`. It prompts before discarding locally modified files under `modules/`; `--force` skips the prompt. ## A working loop ```bash nsx build # compile nsx flash # build if needed, then program nsx view # watch SWO output ``` After the first configure, `nsx flash` on its own covers the common case: it builds what changed and programs the result. If something in that loop fails, [Troubleshooting](https://ambiqai.github.io/neuralspotx/guides/apps/troubleshooting/) is organized around the messages NSX actually prints.