# Create your first app

`nsx create-app` writes a standalone app directory and, unless you tell it not to, clones
the starter modules that board needs into it. Nothing else on your machine changes.

```text
$ nsx create-app hello_ap510 --board apollo510_evb
Created app 'hello_ap510' at: /home/you/hello_ap510
Next steps:
  1) cd /home/you/hello_ap510
  2) Run `nsx configure --app-dir .`
  3) Run `nsx build --app-dir .`, `nsx flash --app-dir .`, or `nsx view --app-dir .`
Cloning into '/home/you/hello_ap510/modules/nsx-ambiq-sdk'...
Cloning into '/home/you/hello_ap510/modules/nsx-pmu-armv8m'...
```

Captured on macOS 26 with an Apollo510 EVB target configuration. The app path is
replaced by `/home/you/hello_ap510`, and Git advisory output is omitted for clarity.
The CLI prints your own absolute path.

`--board` defaults to `apollo510_evb`, so you can leave it off for that target. Run
`nsx board list` for the 17 packaged boards, or read the
[board matrix](https://ambiqai.github.io/neuralspotx/modules/boards/) for each board's SoC, tier, provider and
declared toolchains.

## What it wrote

```text
hello_ap510/
├── .gitignore
├── CMakeLists.txt
├── README.md
├── boards/
│   └── apollo510_evb/
├── cmake/
│   ├── nsx/
│   └── presets/
├── modules/
├── nsx.yml
└── src/
    └── main.c
```

| Path | What it is |
| --- | --- |
| `nsx.yml` | The app manifest: board and SoC target, toolchain, release channel, starter profile and the module list. This is the file you edit. |
| `CMakeLists.txt` | An ordinary top-level CMake file. It declares `cmake_minimum_required(VERSION 3.24)`, includes the packaged NSX support, and links your executable against `nsx::board_apollo510_evb` and `nsx::runtime_core`. |
| `src/main.c` | The generated application. |
| `cmake/nsx/` | Packaged CMake support: module wiring, the three toolchain files, the SEGGER flash and reset templates. Regenerated by NSX rather than hand-edited. |
| `cmake/presets/` | `CMakePresets.json`, so editors and IDEs can open the project directly. |
| `boards/apollo510_evb/` | The vendored board module: `board.yaml`, plus the board, BSP, SoC, memory and debug CMake fragments. |
| `modules/` | Where vendored modules land. After a default `create-app` it holds the starter set, here `nsx-ambiq-sdk` and `nsx-pmu-armv8m`. Gitignored. |
| `README.md` | A short readme for the generated app, including the build and flash sequence. |

There is no `nsx.lock` and no `build/` yet. Both appear when you run
[`nsx configure`](https://ambiqai.github.io/neuralspotx/getting-started/configure-and-build/).

The generated `src/main.c` is a one-second SWO heartbeat:

```c
#include "nsx_core.h"

int main(void)
{
    nsx_core_config_t cfg = {
        .api = &nsx_core_V1_0_0,
    };
    (void)nsx_core_init(&cfg);

    nsx_itm_printf_enable();

    while (1) {
        nsx_printf("nsx hello from generated app\r\n");
        nsx_delay_us(1000000);
    }
}
```

## Choosing a template

`--template` picks the scaffold flavor.

| Template | What you get |
| --- | --- |
| `default` | The minimal app above: a SWO printf loop. |
| `npu-tflm` | TFLite Micro inference on the Ethos-U85 NPU. It seeds `nsx-helia-rt` and `nsx-npu`, turns on heliaRT's Ethos-U dispatch, and ships a Vela model harness plus a `tools/tflite_to_header.py` converter. The generated README covers the offline Vela compilation step. |

The NPU template targets boards whose SoC NSX registers as carrying an Ethos-U85 NPU,
which today is `atomiq110_fpga_turbo`:

```bash
nsx create-app pd_npu --board atomiq110_fpga_turbo --template npu-tflm
```

## Scaffolding without the starter modules

`--no-bootstrap` writes the app but skips the clones, which is what you want when you plan
to pick modules yourself or when you have no network. The app then has no `boards/`
directory and an empty `modules/`, and `nsx.yml` records `baseline: none`. NSX tells you
what to do next:

```text
Created app 'my_app' at: /home/you/my_app
Starter modules were not bootstrapped (--no-bootstrap).
Next steps:
  1) cd /home/you/my_app
  2) Run `nsx module list --app-dir .`
  3) Add modules with `nsx module add <module> --app-dir .`
```

Browse what you can add in the [module catalog](https://ambiqai.github.io/neuralspotx/modules/catalog/).

The remaining options are `--soc`, which overrides the SoC that the board would otherwise
imply, and `--force`, which allows writing into a directory that is not empty. Both are
documented on the [`nsx create-app`](https://ambiqai.github.io/neuralspotx/reference/cli/create-app/) reference
page.

## Next

[Configure and build](https://ambiqai.github.io/neuralspotx/getting-started/configure-and-build/) the app you just
created.