---
title: "tan CLI"
description: "tan is the Alp SDK's sole user-facing command-line front door (ADR-0020, end-state B). One verb set scaffolds a project, builds it (multi-core aware), runs it headless on native_sim, checks its footprint against the SoM memory budget, flashes it, bundles it for OTA, cleans it, inspects the generated configuration, validates board.yaml, compiles AI models, sanity-checks the host environment, opens a serial console, and scaffolds the metadata for porting a new SoM."
source: https://docs.alplab.ai/sdk/tools/cli
---

# The `tan` CLI

`tan` is the Alp SDK's **sole user-facing command-line front door** (ADR-0020, end-state B). One verb set scaffolds a project, builds it (multi-core aware), runs it headless on `native_sim`, checks its footprint against the SoM memory budget, flashes it, bundles it for OTA, cleans it, inspects the generated configuration, validates `board.yaml`, compiles AI models, sanity-checks the host environment, opens a serial console, and scaffolds the metadata for porting a new SoM.

There is **no `alp` binary**. ADR-0020 Phase 4 retired the SDK-side build executor; the SDK's `pyproject.toml` registers only `alp-mcp`, and `alp_cli` survives as an SDK-side **library** — never a user-installed command, and no longer something `tan` shells out to. `alp_orchestrate`'s own `--help` says it plainly: *"Planner/emit CLI for board.yaml (the executor was retired -- ADR-0020 Phase 4)."*

`tan` is the headless companion to the [VS Code extension](https://docs.alplab.ai/sdk/tools/vscode): both front doors drive the same SDK, so a `validate` in CI matches what the editor sees.

## Install

`tan` is a standalone, **independently-versioned, public Python program** ([`alplabai/tan-cli`](https://github.com/alplabai/tan-cli)), shipped as a self-contained PyInstaller freeze. You install it **separately** from the SDK bootstrap, and it needs no Python interpreter and no toolchain on the host:

```bash
curl -fsSL https://raw.githubusercontent.com/alplabai/tan-cli/main/install.sh | sh
# or, on a host that has wget instead of curl:
wget -qO- https://raw.githubusercontent.com/alplabai/tan-cli/main/install.sh | sh
```

```powershell title="Windows PowerShell"
irm https://raw.githubusercontent.com/alplabai/tan-cli/main/install.ps1 | iex
```

The released version is **`0.7.0`** (2026-10-13). The installers download the release for your platform, verify its SHA-256 digest, and install it for the current user. On Linux and macOS the installer itself needs only a downloader (`curl` **or** `wget`), `tar`, and `sha256sum` (macOS: `shasum`); a pristine `ubuntu:24.04` image ships neither `curl` nor `wget`, so install one first. `install.ps1` uses only PowerShell built-ins. For a system-wide install, pass the flag through to the script — `curl ... | sh -s -- --system`, or `&([scriptblock]::Create((irm .../install.ps1))) -System` on Windows; a bare `--system` piped into `sh` / `iex` never reaches the installer.

:::caution[`tan` 0.7.0 is a breaking release]
0.7.0 is a minor bump rather than the planned 0.6.1 because it breaks v0.6.0 consumers. The changes most likely to reach you: it needs **alp-sdk v0.17.0** (below); `tan bootstrap` now installs the cross toolchain by default; `tan doctor` gains a `toolchain` check that can **fail** on a host that passed before; a Flow D (`alif_mram_jlink`) MRAM write needs a second acknowledgement flag; the `swd_probe` flash backend is gone; and **E1M-NX9101** (NXP i.MX 93) is no longer planned or buildable from a `board.yaml` or `--som` that names it. Each is covered in its verb's section below.
:::

Each release publishes exactly **four** archives — PyInstaller `--onedir` freezes:

| Platform | Asset |
|---|---|
| Windows x86_64 | `tan-x86_64-pc-windows-msvc.zip` |
| macOS x86_64 | `tan-x86_64-apple-darwin.tar.gz` |
| macOS arm64 | `tan-aarch64-apple-darwin.tar.gz` |
| Linux x86_64 (glibc) | `tan-x86_64-unknown-linux-gnu.tar.gz` |

From a checkout, `python3 -m pip install ./python` installs the same program from source; that path needs **Python 3.12 or newer** and should go into a virtual environment (a PEP 668 host such as stock Debian / Ubuntu refuses a bare system-interpreter install with `error: externally-managed-environment`). The Python distribution is named **`tan-cli`** — the import package and the console script stay `tan` — but it is not published to PyPI yet, so use a release archive or a source checkout. There is **no `-musl` asset, no arm64 Linux and no arm64 Windows** — a frozen binary has to be built on the architecture it runs on, and the release builds on four runners. `install.sh` detects a musl host and refuses **before** downloading. The Linux archive is frozen on Debian 11 and requires **GLIBC_2.30** or newer, measured from the binary's own bundled payload at build time; Debian 11+ / Ubuntu 20.04+ / RHEL 9+ are comfortably above it. Every archive plus `checksums.txt` carries a GitHub build-provenance attestation — verify with `gh attestation verify <file> --repo alplabai/tan-cli`.

:::warning[`tan` 0.7.0 needs alp-sdk v0.17.0 or newer]
`tan` 0.7.0 requires an alp-sdk that contains commit `4b206c8a60d56af318741491a6fecdc499dfcd36` (the AEN SoM `power_domains:` block); **v0.17.0 is the first stable release that does**, and v0.16.0 does not. Its vendored project scaffold and its validator port are pinned to alp-sdk `v0.17.0` itself (`84132b98a53a9f0e5ef9e7622a38c6d637439873`), and the doc links in scaffolded project READMEs point at that tag.

There is still **no global SDK-version check** in `tan` — no constant, no comparison, no up-front refusal. An older checkout fails where the missing metadata is first needed instead: `tan build` on **any** Zephyr board fails Kconfig configure (`Aborting due to Kconfig warnings`, an undefined `ALP_SDK_SOM_HW_REV`), and AEN and V2N / V2M boards fail earlier, at `tan generate --target zephyr-board` (exit 3, `generate.emit-failed`). `tan` 0.7.0 also reads and scaffolds **som-preset schema v2 only**: against a pre-v2 SDK, `tan presets` lists no SoMs (with a `presets.som-schema-version-skipped` warning), `tan size` reports every budget unknown, and `tan new-som` cannot find `som-preset-v2.schema.json`. Upgrade `tan` and the SDK together.

The per-revision gate is unchanged: `hw_rev` compatibility is read out of alp-sdk's own `metadata/e1m_modules/<family>/hw-revisions.yaml`. As of 0.7.0, `tan validate` and `tan diff` report an unknown or unbuildable revision under their own codes — `validate.hardware-revision-unknown` / `validate.hardware-revision-not-buildable` (and the `diff.` equivalents) — instead of the generic `validate.failed` / `diff.failed`.
:::

`sdk.discovery-divergent` is a warning worth knowing: it fires only when **neither** `--sdk-root`, the project pin, nor the global default supplied the SDK root, and the narrow and wide discovery ladders then resolve to **different checkouts**. `size`, `image`, `clean`, `run` and `validate` print it on the default text channel as well as in the JSON envelope.

When a project's `.alp/sdk-path` pin cannot be resolved, `tan presets`, `clean`, `diff`, `lock`, `migrate`, `quality`, `examples`, `generate`, `bootstrap`, `new-som` and `explain --code` now put `sdk.project-pin-unresolved` **first** in `issues[]`, ahead of the command's own refusal — a script keyed on `issues[0]` sees a different code than it did under 0.6.0.

First install through to first build, in order:

```bash
curl -fsSL https://raw.githubusercontent.com/alplabai/tan-cli/main/install.sh | sh
git clone --branch v0.17.0 https://github.com/alplabai/alp-sdk   # the default branch, dev, carries unreleased changes
tan bootstrap --sdk-root ./alp-sdk     # also installs the arm-zephyr-eabi toolchain
tan init --name my-app
cd my-app
tan validate
tan build
tan size
tan run --flash --confirm
```

The bootstrap scripts — `scripts/bootstrap.sh` on Linux / macOS / WSL2, `scripts/bootstrap.ps1` on native Windows (see [Installation](https://docs.alplab.ai/sdk/installation)) — editable-install the alp-sdk checkout into the workspace venv. That brings in the SDK's internal Python tooling (the `alp_cli` **library** modules that `scripts/validate_board_yaml.py` and friends import, plus `alp-mcp`), not a user command: it never puts an `alp` executable on your PATH. As of alp-sdk **v0.17.0** there is no `python -m alp_cli <verb>` front door either — its command-line wrappers were retired once `tan` had ported every one of them, and `scripts/alp_cli/` now holds only library modules.

## What `tan` runs itself, and what it delegates

`tan` both plans and executes. Every verb is a **native Python implementation inside `tan`** — `model`, `monitor`, `new-som` and `faultdecode` included; those were ports, not forwards. `tan` does not forward any verb to `python -m alp_cli`.

- **`tan`'s own build executor** — `build`, `flash`, `size`, `image`, `clean`, `run`. alp-sdk is **plans-only** here: `tan` consumes `alp_orchestrate --emit build-plan` and `--emit system-manifest`, then runs `west` / `bitbake` / `cmake` per slice itself, owns skip-vs-fail policy, and programs the hardware.
- **In-process generation** — `generate` renders from `tan.planner` inside the process. Setting the environment variable `TAN_GENERATE_EXECUTOR=subprocess` is an opt-in escape hatch that spawns the SDK's `scripts/alp_project.py` instead.
- **In-process validation** — **new in 0.7.0**, `validate` runs a port of the SDK's board.yaml validator inside `tan` instead of spawning `scripts/validate_board_yaml.py`. When the bound SDK is newer than the port, `tan` says so (`validate.sdk-validator-newer`) because the SDK may have added rules the port does not apply. Setting `TAN_VALIDATE_ENGINE=subprocess` runs the bound SDK's own `scripts/validate_board_yaml.py` instead.
- **The remaining spawns** — `migrate` / `lock` / `quality` forward to the surviving `west alp-*` extension commands.

Where `tan` does delegate, it is a **thin wrapper** — the actual logic lives in the same scripts and packages the `west alp-*` commands drive (`scripts/alp_orchestrate/`, `scripts/alp_project.py`, `scripts/validate_board_yaml.py`). `tan` adds discoverability and sane defaults; it never forks the behaviour.

`tan` resolves the SDK checkout itself, in this order: `--sdk-root`, the project's `.alp/sdk-path` pin (written by `tan init`), the user's machine-global default pointer, then an `alp-sdk` checkout near the project. The global default is one pointer shared by every project on the host and is last-writer-wins, so another project's `tan bootstrap` can repoint it; `tan` warns (`sdk.global-default-foreign-project`) rather than resolving silently. When nothing resolves, it says so rather than guessing.

`tan sdk list`, `tan sdk current` and `tan sdk remove <version|path>` work; `remove` refuses the active or pinned install, or a path outside the cache root (default `~/.alp/sdk-cache`), unless you pass `--force`. `tan sdk install` and `tan sdk switch` are **not ported yet** and refuse — clone the SDK yourself and use `--sdk-root`, or let `tan init` write the project pin.

### Global flags

These apply to every verb (they replace several per-verb flags the retired Python CLI carried):

| Flag | Meaning |
|---|---|
| `--project PATH` | Project root (default: the current directory) |
| `--board-yaml PATH` | Explicit `board.yaml` path; overrides project resolution |
| `--sdk-root PATH` | alp-sdk checkout root |
| `--target EMIT` | Generation target for `generate` / `explain` |
| `--all` | Run against all relevant targets |
| `--format text\|json` | Output format; `json` emits the machine-readable envelope |
| `--verbose` / `--quiet` | More diagnostic detail / suppress non-essential output |
| `--no-color` | Disable ANSI colour |
| `--non-interactive` | Never prompt; fail instead of asking |
| `--ci` | CI mode: implies `--non-interactive` and disables colour |
| `--version` | Print the version and exit. Unlike the ten above, this is a real root-callback option |

Mechanically these are two different things, which matters when one of them is refused. `--version` and `--format` are declared on the root callback. The other ten are **injected per command** by `accept_global_flags()` (`tan/core/global_flags.py`), hidden from `--help`, and accepted-then-dropped on any command that does not act on them. `--format` is additionally relocatable: `tan --format json build` and `tan build --format json` are the same thing.

`--format` is `text|json` on every verb **except `tan validate`**, which also accepts `diagnostic-v1` and `sarif`. The pre-subcommand position relocates over the union, so `tan --format sarif validate` works.

:::info[`tan build` and the global flags — changed in 0.7.0]
In 0.6.0, `tan build` refused twelve flags with `cli.command-deferred` (exit 1). As of 0.7.0 nothing on `tan build` is deferred any more:

- **Accepted:** `--target`, `--all`, `--verbose`, `--quiet`, `--no-color`, `--non-interactive` and `--ci` are accepted on `tan build` like on every other verb (and, like there, have no build-specific effect). `--pristine` is now **implemented** — see [`tan build`](#tan-build--build-the-project-multi-core-aware).
- **Retired:** `--plan`, `--manifest`, `--manifest-from` and `--no-auto-bootstrap` refuse with **`build.flag-retired`** and exit **2** (previously `cli.command-deferred`, exit 1), and the message names the replacement. A script that matched the old code or exit status needs updating.

Unattended runs need no flag: `tan` treats itself as non-interactive when **stdin or stderr** is not a TTY, or when `--format json` is in effect. Never stdout — piping stdout alone does not make it non-interactive.
:::

## `tan` vs `west alp-*` — which do I use?

Four `west alp-*` extension commands survive ADR-0020 Phase 4 (`scripts/west-commands.yml`): **`alp-lock`**, **`alp-migrate`**, **`alp-quality`**, **`alp-emit`**. The build/flash/image/size/renode/clean extensions were retired along with the executor.

| You are… | Use |
|---|---|
| Building, flashing, sizing, bundling, cleaning, or running headless | `tan build` / `tan flash` / `tan size` / `tan image` / `tan clean` / `tan run` |
| Scaffolding, validating, compiling a model, checking the host, opening a console, decoding a fault | `tan init` / `tan validate` / `tan model` / `tan doctor` / `tan monitor` / `tan faultdecode` |
| Inspecting (read-only) or resetting an attached module over J-Link, without flashing | `tan probe` / `tan reset` |
| Writing the board-derived config files without a full build | `tan generate` (or `west alp-emit <mode>` from a west workspace) |
| Locking deps, migrating `board.yaml`, running the quality gates | `west alp-lock` / `west alp-migrate` / `west alp-quality` — or their pass-through twins `tan lock` / `tan migrate` / `tan quality` |

Rules of thumb:

- The multi-slice build surface is **`tan`'s**, not the SDK's. alp-sdk emits plans; `tan` executes them. Nothing in alp-sdk builds or flashes any more.
- `tan migrate` / `tan lock` / `tan quality` forward their tail **verbatim** to `west alp-migrate` / `west alp-lock` / `west alp-quality`, so the flag references below apply to either spelling.
- The generated-artefact catalog has several front doors: `tan generate` renders from `tan.planner`, while `west alp-emit` and `scripts/alp_project.py --emit` are the SDK-side front doors onto the SDK's own emitters.

:::note[The extension commands need an alp-sdk-manifest workspace]
`west alp-*` only resolves when **alp-sdk is the workspace's manifest repo** — west discovers the commands through the manifest's `self.west-commands` (or a consuming manifest's `projects.alp-sdk.west-commands`), not through `zephyr/module.yml`. A workspace initialised from the plain upstream Zephyr manifest reports `unknown command "alp-migrate"`. `scripts/bootstrap.sh` gets this right (#769) and hard-fails at bootstrap time if `west alp-migrate` doesn't resolve in the new workspace; see [Installation](https://docs.alplab.ai/sdk/installation). `tan` itself does not depend on this — it locates the SDK checkout directly.
:::

## Verb reference

`tan 0.7.0` ships **33 verbs**, all native Python:

`bootstrap`, `build`, `clean`, `completion`, `debug-config`, `diff`, `doctor`, `examples`, `explain`, `faultdecode`, `flash`, `generate`, `image`, `init`, `inspect`, `kconfig`, `lock`, `migrate`, `model`, `monitor`, `new-som`, `pinmux`, `presets`, `probe`, `quality`, `reset`, `run`, `scaffold`, `sdk`, `size`, `support-bundle`, `trace`, `validate`

That is two more than `tan 0.6.0`'s 31: [`probe`](#tan-probe--read-only-j-link-inspection) and [`reset`](#tan-reset--one-nreset-pulse) are new. `renode` was removed in 0.6.0 — see [below](#renode-retired). `tan --help` and `tan <verb> --help` are the authoritative reference. As of 0.7.0, `tan --version` and `tan <verb> --help` no longer import every command module, so they start faster.

### `tan init` — scaffold a new project

```bash
tan init --template minimal-app --name my-app --som E1M-AEN801
tan init --from-example audio/i2s-tone --name tone-demo
tan init --template minimal-app --name my-app --preview   # show planned files, write nothing
tan init --template multicore-mailbox --name mbox --som E1M-AEN801            # dual-Zephyr M55-HP + M55-HE
tan init --topology m55_hp:zephyr,m55_he:zephyr --name mbox --som E1M-AEN801  # pick the template by topology
```

Expands a project template — or, with `--from-example`, copies one of the SDK's ready-made example projects verbatim (`tan examples` lists them; the value is the example's `category/name` source dir under the SDK's `examples/` directory). `tan explain --template <id>` describes a template before you commit to it, including which SKUs its `tan init --som` accepts.

`tan init`'s own template ids are `minimal-app`, `zephyr-app`, `sensor-starter`, `iot-starter`, `edge-ai-starter`, `board-diagnostics` and — **new in 0.7.0** — `multicore-mailbox`, which scaffolds a dual-Zephyr project with one app per M55 core. This is a smaller id space than the SDK's template catalog; use `--from-example` for any other SDK example.

| Option | Meaning |
|---|---|
| `--template` | Project template id |
| `--from-example` | SDK example `category/name` to copy verbatim (conflicts with `--template`) |
| `--topology` | **New in 0.7.0.** `core_id:os[,core_id:os...]` — instead of naming a template, select the SDK catalog template whose own `cores:` topology matches exactly (e.g. `m55_hp:zephyr,m55_he:zephyr`). Mutually exclusive with `--template`, `--from-example` and `--cores`; needs a resolved SDK checkout |
| `--name` | Project name; creates a sub-directory when provided |
| `--destination` | Destination directory (default: the current directory or `--project`) |
| `--som` / `--sku` | Target SoM SKU written into the generated `board.yaml`, e.g. `E1M-AEN701` |
| `--cores` | Comma-separated cores to **splice onto** the chosen template, `id[:os]` (e.g. `m33_sm:zephyr,a55_cluster:yocto`). The OS is inferred from the id when omitted, but that inference is honoured only for the plan's app core — any other id can only be added app-less, as `:off` or (on a Cortex-A id) `:yocto` |
| `--board-yaml` | Render this file verbatim as the scaffolded `board.yaml` instead of the planned one |
| `--preview` | Show planned files without writing anything |
| `--force` | Allow overwriting existing files |

`tan init --som` now refuses SoM inputs it used to drop silently (exit 0, `issues: []`, the example's `board.yaml` written unchanged): a flow-style `som:` block in the example refuses with `init.som-flow-style-unsupported`, and a `som:` block built from a YAML alias, an un-overridden `<<:` merge key, or a flow mapping split across lines refuses with `init.som-block-unsupported`. `E1M-NX9101` is no longer a SKU `tan` knows: neither `tan` 0.7.0 nor alp-sdk v0.17.0 carries it, so a `--som` or `board.yaml` naming it is not planned or buildable.

`tan scaffold --template <id> --name <name>` is the in-project sibling: it adds a module to an existing project, with the same `--destination` / `--preview` / `--force` contract.

### `tan new-som` — scaffold metadata for a new SoM port

```bash
tan new-som --sku E1M-NX9555 --soc-ref nxp:imx9:imx95 --family nxp-imx9
tan new-som               # interactive: prompts for every field
```

The vendor-N+1 porting kit, implemented natively in `tan`. Generates the two metadata skeletons a new SoM port needs — `metadata/e1m_modules/<SKU>.yaml` (the SoM preset) and, when the target SoC has no spec yet, `metadata/socs/<vendor>/<family>/<part>.json` — with every schema-required hardware-fact field present as an explicit `TBD` placeholder. **Values are never invented**; the JSON records what is still pending in the schema-sanctioned `_pending_reason` + `notes` fields. Both skeletons are schema-valid on arrival, and the command finishes by printing a numbered porting checklist (fill the TBDs, extend the schema `sku` pattern for a brand-new family, register the silicon ref, validate, regenerate, run the conformance suite).

The scaffold is committable as-is: every input is validated *before* anything is written (a rejected invocation never leaves half-written files). Use `--dry-run` to see the planned files — and run the full validation — without writing anything. In a pipe or CI, missing required flags fail fast with an explicit list instead of dropping into the prompts. The full walkthrough lives in the SDK's [`docs/porting-new-som.md`](https://github.com/alplabai/alp-sdk/blob/main/docs/porting-new-som.md).

| Option | Meaning |
|---|---|
| `--sku` | New SoM SKU, e.g. `E1M-NX9555` |
| `--soc-ref` | Silicon triple-colon ref, e.g. `nxp:imx9:imx95` |
| `--family` | Human-readable family slug, e.g. `nxp-imx9` |
| `--vendor` | Vendor display name for the SoC JSON (default: soc-ref vendor segment) |
| `--display-name` | Preset display name (default derived from the SKU) |
| `--inference-backend` | `ethos_u` / `drpai` / `deepx_dxm1` / `tbd` (default `tbd`) |
| `--ethos-u-variant` | `u55` / `u85`; required with `--inference-backend ethos_u`. `u65` was dropped in 0.7.0 along with the i.MX 93 module that carried it |
| `--cores` | Comma-separated canonical core ids (default: a `tbd_core0` placeholder) |
| `--default-board` | Stock carrier board (default `E1M-EVK`) |
| `--default-hw-rev` | Default hardware revision (default `r1`) |
| `--output-root` | Root to generate `metadata/` under (default: the SDK checkout) |
| `--dry-run` | Validate and print the planned files; write nothing |
| `--force` | Overwrite an existing preset for this SKU |

### `tan bootstrap` — prepare the workspace and the cross toolchain

```bash
tan bootstrap --sdk-root ./alp-sdk                     # workspace + venv + west + arm-zephyr-eabi toolchain
tan bootstrap --sdk-root ./alp-sdk --no-toolchain      # skip the toolchain phase
tan bootstrap --sdk-root ./alp-sdk --workspace /path/to/alp-workspace
tan bootstrap --print-env                              # reprint the ZEPHYR_BASE / activate lines
```

Prepares west, Zephyr, the Python environment and the SDK's dependencies into a workspace venv **next to the SDK checkout** — `west init -l` makes the checkout's **parent** the west topdir. Starting in an empty directory, that is the current directory, so the venv is `./.venv`. `--workspace <path>` instead **moves** the `alp-sdk` checkout to `<path>/alp-sdk` and updates the machine-global `~/.alp/sdk-default` pointer to it, so run it before anything else references the old path.

**Changed in 0.7.0 — `bootstrap` now installs the cross toolchain by default.** As a blocking final phase it acquires the Zephyr SDK `arm-zephyr-eabi` toolchain that real-silicon builds need, into the artifact-keyed store `~/.alp/toolchains/zephyr-sdk-<version>-arm-zephyr-eabi/` (or under `$ALP_TOOLCHAIN_ROOT`), shared by every project pinning that version. The version comes from the SDK checkout's own `metadata/toolchains.json`, so an alp-sdk pin bump reaches you on the next `tan bootstrap` without a `tan` upgrade. A second run against the same pin re-verifies the existing install rather than reinstalling. What the phase verifies:

- `tan` compares alp-sdk's SHA-256 pins with the SDK release's `sha256.sum`, and downloads the toolchain archive itself, hashing it against the pin as it streams — the SDK's own `setup.sh` fetches that archive with no check at all. A mismatch, an ambiguous sum entry, or a sum or archive that cannot be fetched refuses with `bootstrap.toolchain-pin-mismatch` or `bootstrap.toolchain-pin-unverified` and installs nothing.
- It passes `--no-hosttools` to `west sdk install`, so it needs no `file` on `PATH` — and installs no `dtc`, `openocd`, `bossac` or `qemu-system-*`. A real-silicon Zephyr build needs none of them.
- On a host the pinned Zephyr SDK publishes no archive for (an Intel Mac, for example), the phase is skipped with a message rather than failing.

`--no-toolchain` skips the phase; the rest of `bootstrap` is unaffected and `native_sim` builds never need the cross toolchain. On native Windows the phase checks for a 7-Zip-compatible extractor before it downloads anything.

The SDK release listing goes through the GitHub API, whose anonymous quota is counted **per source IP** — behind a shared office egress, a VPN or a CI runner pool it can be exhausted by traffic that is not yours (`403 API rate limit exceeded`). Set **`TAN_GITHUB_TOKEN`** (no scopes needed); `tan` also reads `GH_TOKEN` and `GITHUB_TOKEN`, in that order, so an existing `gh auth login` session or a CI job's token is used automatically. The token is taken from the environment only — there is deliberately no `--github-token` flag — never appears in argv, logs, `--dry-run` output or the JSON envelope, and is offered to `api.github.com` alone, not to the CDN that serves the archive.

| Option | Meaning |
|---|---|
| `--sdk-root PATH` | The alp-sdk checkout to bootstrap |
| `--workspace PATH` | Put the west workspace here (moves the checkout — see above) |
| `--no-toolchain` | **New in 0.7.0.** Skip the `arm-zephyr-eabi` toolchain phase |
| `--no-patches` | **New in 0.7.0.** Skip applying the SDK's `zephyr/patches.yml` to the Zephyr and module trees. Builds that need those patches will not compile; use it only to leave an adopted workspace's module trees untouched |
| `--no-pip` / `--no-west` | Skip the pip installs / the west steps |
| `--print-env` | Print the environment-variable lines and exit. The venv-activation line it prints is a **comment** — sourcing the output sets `ZEPHYR_BASE` and `ZEPHYR_TOOLCHAIN_VARIANT` but does not activate the venv |
| `--allow-partial` | Report success even when a dependency install failed and the workspace cannot build; the failures are still printed and reported as issues. For when the missing packages are ones you know you do not need |
| `--dry-run` | Show the planned commands without running them |

### `tan build` — build the project (multi-core aware)

```bash
tan build                      # materialise the plan + run every slice's build command
tan --project my-app build     # same, for a project outside the cwd
tan build --pristine           # wipe every slice's build dir first
tan build -D CONFIG_X=y --core m55_hp       # extra CMake definition on one Zephyr slice
tan build --plan-from plan.json             # show a saved plan, build nothing
tan build --plan-from plan.json --execute   # run a pinned, reviewed plan file
```

`tan build` asks the SDK for `--emit build-plan` — the machine-readable, write-free build recipe, one entry per non-`off` core, carrying the resolved app source dir, the exact tool command, and the environment — materialises the plan's generated files under the build root, then runs each slice's `west` / `bitbake` / `cmake` command. It writes `build/system-manifest.yaml`: the single source of truth that `tan flash`, `tan size`, `tan image`, and OTA consume. It never runs the produced binary itself — that's `tan run`. It never bootstraps a workspace implicitly either — an unbootstrapped workspace fails with `build.plan-unavailable`; run `tan bootstrap` yourself.

| Option | Meaning |
|---|---|
| `--plan-from FILE` | Read the plan from a JSON file instead of invoking the SDK, show it, and build nothing |
| `--materialise` | Write the plan's generated files (shared artefacts + per-slice config) under the build root and stop |
| `--execute` | Materialise the plan **and** run each slice's command, even when the plan came from `--plan-from` — for running a pinned, reviewed plan file reproducibly. Cannot be combined with `--materialise` (`build.conflicting-flags`, exit 2) |
| `--native` | Accepted and inert: a bare `tan build` is already native. It does **not** override the show-only mode `--plan-from` implies — use `--execute` for that |
| `--build-root DIR` | Project tree the slices run under and artefacts are written below (default: the `board.yaml`'s directory, else the current directory) |
| `--pristine` | **Implemented in 0.7.0.** Force-wipe every slice's build dir before dispatch. It never touches a dir `tan` can't vouch for (one named by an explicit `-d` / `--build-dir` in the slice's own command, or a plan cwd outside `build/`); a slice the wipe declines is reported as `build.pristine-skipped`, so "pristine" never silently means "incremental" |
| `-D NAME=VALUE` / `--define` | **New in 0.7.0**, repeatable. A CMake definition passed after `--` to `west` on every Zephyr slice (or those named by `--core`), applied after the plan's own arguments so it overrides them — except `EXTRA_CONF_FILE` / `EXTRA_DTC_OVERLAY_FILE`, which are appended to `tan`'s own list. `BOARD` and `Python3_EXECUTABLE` are refused |
| `--core ID` | Scope `-D` to the Zephyr slice(s) with this core id; repeatable (default: every Zephyr slice) |
| `--board TARGET` | **New in 0.7.0.** Build a plain Zephyr app that has **no** `board.yaml` as a single Zephyr slice for this board target, e.g. `alp_e1m_aen803_m55_he/ae822fa0e5597ls0/rtss_he`. The app is `--project` (default `.`); `west`, the toolchain, the SDK and host Python resolve as for a planned build, and the run writes `system-manifest.yaml` so `tan flash` / `size` / `image` work on it |
| `--plan` / `--manifest` / `--manifest-from` / `--no-auto-bootstrap` | **Retired** — refused with `build.flag-retired` (exit 2), naming the replacement. Read `build/system-manifest.yaml` directly instead of `--manifest`; use `--plan-from FILE` instead of `--plan` |

`tan build` resolves the cross toolchain (`${TOOLCHAIN_ROOT}`) from the store `tan bootstrap` installs into, as well as from an existing Zephyr SDK install. A `ZEPHYR_BASE` in the environment that names a different tree than the resolved west workspace's `zephyr/` is **ignored** (`build.zephyr-base-ignored`, info); to build against another tree, run `tan` from that workspace.

alp-sdk's own contribution to this pipeline is fully inspectable without `tan`:

```bash
PYTHONPATH=scripts python3 -m alp_orchestrate --input board.yaml --emit build-plan
PYTHONPATH=scripts python3 -m alp_orchestrate --input board.yaml --emit system-manifest
```

### `tan run` — build, then run it

```bash
tan run                        # build, then execute the produced native_sim binary
tan run --flash                # hardware target: build, then program the board
tan run --flash --core m33_sm  # …flashing only one slice
tan run --flash --confirm      # …and arm the flash confirm gate
tan run --flash --confirm --atoc-unqueryable   # an AEN Flow D (MRAM) slice also needs this
```

A thin orchestrator over the native `build` + `flash` engines — it reuses them, never re-derives them. The host-vs-hardware target is read from what the build produces (a `native_sim` binary ⇒ host), so `run` needs no board selector: `board.yaml` already names the target. `--flash` is a **required opt-in** on hardware; without it, `run` on a hardware project builds and reports but never programs the board — text mode prints `run: built; pass --flash to program the board.` It is ignored for a native_sim/host target, which always runs the produced binary and never flashes.

| Option | Meaning |
|---|---|
| `--flash` | Program the board after the build (hardware targets only) |
| `--core CORE_ID` | Flash only this slice |
| `--confirm` | Arm the flash confirm gate |
| `--atoc-unqueryable` | **New in 0.7.0.** On an AEN Flow D slice (`alif_mram_jlink`), acknowledge that the write **replaces the entire ATOC**. Use the flag here rather than `flash_args.atoc_unqueryable: true`: every `run --flash` regenerates `build/system-manifest.yaml` first, so a hand-added manifest key does not survive |
| `--replace-atoc` | **New in 0.7.0.** On a Flow A slice (`zephyr_west_flash` with the `alif_flash` runner, over the SE-UART), override that runner's pre-burn ATOC guard. Flag only; reaches at most one write per run |
| `--project PATH` / `--board-yaml PATH` / `--sdk-root PATH` / `--format` | As elsewhere |

`--flash` without `--confirm` calls the flash engine with the gate unarmed. The equivalent arming outside the flag is `ALP_FLASH_FORCE=1` in the environment, or `flash_args.confirm: true` in the manifest. When every slice is gated, nothing reaches the device, and the run exits **1** with `flash.nothing-flashed`. A Flow D slice that is armed but not acknowledged with `--atoc-unqueryable` comes back `failed`, not `planned`.

:::danger[`--confirm` is not a universal safety gate — two of the five backends ignore it]
Only three flash backends read the confirm gate: **`yocto_wic`** (also registered under the alias `yocto_wic_to_sd_or_emmc`), **`xspi_flashwriter`**, and the AEN Flow D **`alif_mram_jlink`** path. The other two — **`zephyr_west_flash`** and **`baremetal_cmake_flash`** — **write the attached device unconditionally, with or without `--confirm`.** (`tan` 0.7.0 removed the sixth, `swd_probe`; a manifest that still declares it refuses with `flash.entry-failed`.)

`tan run --confirm`'s own `--help` text still says that without it every slice comes back `planned`. That is **false** for those two backends; `tan flash --help` states it correctly. **`--dry-run` on `tan flash` is the only preview that covers every backend.** Do not treat an un-confirmed `tan run --flash` as a rehearsal.
:::

### `tan flash` — program the built project

```bash
tan build && tan flash                     # the whole system, one-liner
tan flash --core m33_sm                    # one slice only
tan flash --helper gd32_bridge             # one helper MCU only
tan flash --dry-run                        # print commands, touch nothing
tan flash --confirm                        # arm the write on gated backends
tan flash --confirm --atoc-unqueryable     # AEN Flow D (MRAM): also acknowledge the ATOC replacement
tan flash --ram --core m55_he --confirm    # AEN Flow C: RAM-run over J-Link, never writes MRAM
```

Walks `build/system-manifest.yaml` (produced by `tan build`) and programs every slice + helper MCU via the registered flash backends, in `boot_order:`.

| Option | Meaning |
|---|---|
| `APP_PATH` (argument, optional) | App directory (default `.`); a non-`.` value overrides `--project` |
| `--core` | Flash only the slice with this `core_id` (skips every other slice **and** all helpers) |
| `--helper` | Flash only the helper MCU with this name (skips all slices and every other helper) |
| `--dry-run` | Print the command each backend *would* run; spawn nothing. Also bypasses the required-tool PATH gate |
| `--confirm` | Arm the confirm gate on the backends that have one — `yocto_wic`, `xspi_flashwriter` and Flow D `alif_mram_jlink`. Without it (or `ALP_FLASH_FORCE=1`, or `flash_args.confirm: true`) those three only preview and the run exits non-zero. `zephyr_west_flash` and `baremetal_cmake_flash` have **no** confirm gate and write regardless |
| `--atoc-unqueryable` | **New in 0.7.0, required for a confirmed Flow D write.** Acknowledge that an `alif_mram_jlink` MRAM write **replaces the entire ATOC** (manifest spelling: `flash_args.atoc_unqueryable: true`). See the warning below |
| `--replace-atoc` | Override the `alif_flash` west runner's pre-burn ATOC guard on a Flow A `zephyr_west_flash` slice (over the SE-UART). Reaches at most one write per run (`flash.replace-atoc-ambiguous` otherwise — narrow with `--core`). Never accepted in place of `--atoc-unqueryable` |
| `--readback` | After a Flow D write, re-read every written region in a **fresh** J-Link session and compare SHA-256. The write's own `verifybin` compares against J-Link's flash cache, so the envelope reports it as `cache-verified`; a matching read-back upgrades that to `readback-verified`, a mismatch fails the entry (`flash.readback-mismatch`) |
| `--no-reset` | Flow D: send **no** reset/run commands after the write, so you can attach a console first. This means no reset command is sent — not that the core is guaranteed stopped. The envelope says `jlink.reset: not-sent` |
| `--no-device-config` | Sign the Flow D slot0 ATOC **without** a `DEVICE` entry. By default the ATOC `tan` signs leads with one (from `flash_args.setools_device_config`, else SETOOLS' own `build/config/app-device-config.json`), and the run refuses with `flash.device-config-missing` when neither exists — because the write replaces the whole ATOC, omitting it deletes the resident firewall, HFXO-trim and `SE_BOOT_INFO` configuration |
| `--ram` | AEN **Flow C**: load the slice's ITCM/SRAM-linked image over J-Link and run it, **never writing MRAM**. Needs exactly one slice (`--core`), which must be the M55-HE core, and `--confirm`. Refuses an image not linked for RAM (`flash.ram-image-not-ram-linked`). To get such an image, set `diagnostics.link: itcm` in `board.yaml`: as of 0.7.0 `tan build` then links the M55-HE slice into ITCM itself (E1M-AEN801 / E1M-AEN803 only, and only when the project has its own M55-HE app) |
| `--ram-console` / `--wait SECONDS` | With `--ram`: after `--wait` seconds (default 1.5) read `ram_console_buf` over SWD and report it as `ramConsole.text` |
| `--watch ADDR[:WORDS][@PERIOD-MS]` | With `--ram`, repeatable: sample target memory with read-only `mem32` reads (default every 100 ms, 1 word, at most 64) during the `--wait` window. Samples land in `data.watch[]`. The HP TCM windows `0x50000000`–`0x57FFFFFF` are refused |
| `--assume-he` | With `--ram`: proceed when the attached-core check has **no** evidence either way. It never overrides positive HP evidence (`flash.ram-core-mismatch`) or a contradiction (`flash.ram-core-unconfirmed`) |
| `--probe-serial SN` | J-Link serial for this run, overriding `flash_args.jlink_serial`. Refused when several visible probes share it (`flash.probe-ambiguous`); `alif_mram_jlink` only |
| `--probe-usb-path BUS-PORT` | Select the J-Link at this USB port path (e.g. `3-4.2`), for benches with cloned probe serials. Linux only |
| `--jlink PATH` | The J-Link Commander binary to use; otherwise resolved from the environment, `PATH`, then a SEGGER install root — never from the project's `.venv` |
| `--setools-dir PATH` | Alif SETOOLS install used to auto-sign a Flow D slot0 ATOC (licence-gated, obtained from Alif). Precedence: this flag, then `SETOOLS_DIR`, then `flash_args.setools_dir` — and the manifest source is **never executed** for a confirmed write (`flash.setools-untrusted-source`) |
| `--recover` | Authorise a recovery flash of a helper MCU Alp Lab programs in production (`flash_policy: recovery_only`). Bricked devices only, with Alp Lab-supplied binaries; must be combined with `--helper NAME`. As of alp-sdk v0.17.0 no shipped preset declares a local flash method for the GD32 bridge or the CC3501E, so a plain `tan flash` skips both |
| `--build-root` | Override the build root holding `system-manifest.yaml` (default `<app_path>/build`) |
| `--skip-missing-tools` | Warn + skip an entry whose backend tools are all absent from PATH. No effect under `--dry-run` |

:::danger[A Flow D write replaces the whole ATOC — new acknowledgement in 0.7.0]
Flow D (`alif_mram_jlink`, the AEN MRAM path) has no SE-UART channel to enumerate what is already resident, so **any boot entry the new ATOC does not name is silently delisted** — and the Secure Enclave still reports `[SES] ATOC ok`. As of 0.7.0 a confirmed Flow D write **refuses** until you acknowledge that with `--atoc-unqueryable` (or `flash_args.atoc_unqueryable: true`), reporting `flash.atoc-replacement-unacknowledged`. `--confirm` arms the write; `--atoc-unqueryable` acknowledges the replacement; you need both. A preview still previews.

When a manifest carries several Flow D slices (for example `m55_he` and `m55_hp`), 0.7.0 signs **one** ATOC that names `DEVICE` and every slice, writes each app to its slot0, then writes the package once; before, it signed one ATOC per slice at the same address, so the second write delisted the first core. `--core` still writes one entry, and its preview names the other slice(s) it would delist.
:::

**What "reset" means on a Flow D envelope (changed in 0.7.0).** Program-counter samples inside the new image's address range are no longer accepted as proof the new image is running, because an older image linked at the same slot0 address satisfies the same test. Such samples now only set `jlink.coreRunning`; `jlink.reset` stays `unconfirmed` and the info-level `flash.jlink-reset-unconfirmed` is raised. A `DHCSR` `S_RESET_ST` read still confirms the reset, and when that is gone `tan` reads Zephyr's kernel uptime (`curr_tick`, address taken from the flashed ELF) and reports `jlink.reset: "booted"` with `resetConfirmedBy: "uptime"` if the image provably booted after the write. **Expect the info issue on healthy flashes** of an app that sleeps: `ok` and the exit code are unchanged.

**`--ram` and the cycle counter.** When `tan`'s J-Link session ends it clears `DEMCR.TRCENA` (bit 24), which stops the DWT cycle counter (`CYCCNT`) and ITM trace in the running image shortly after start while the envelope still reports `ok: true`. Firmware that reads `CYCCNT` or emits trace must set `TRCENA` again after start. Every successful `--ram` run carries the info issue `flash.ram-debugger-detach-clears-trcena` as a reminder.

**Changed in `tan` 0.6.0 — a filter that matches nothing now fails.** Passing `--core` or `--helper` and matching no entry raises `flash.nothing-matched` at severity **error**, counts as a failure, and exits **1**. Before 0.6.0 it was an unconditional *warning* that never touched the failure count, so `tan flash --core <typo> && echo flashed` printed `flashed` over an untouched board. With **no** filter at all (an empty manifest) it stays a `warning` and exits **0** — that case is unchanged. Two related codes landed alongside it: `flash.entries-skipped` (warning; every matched target was skipped before dispatch) and `flash.nothing-flashed` (error, exit 1; every target came back `planned` because the confirm gate was never armed).

**Wrong-board guard: `flash_args.expect_dpidr` now round-trips a bare YAML hex.** An unquoted `expect_dpidr: 0x0BE12477` used to decay to the decimal string `199304311` and **refuse the correct board**; it is now normalised back to `0x0BE12477` form. A paired width guard refuses anything that is not 8 hex digits, at plan time — so it surfaces under `--dry-run` too:

```
<method>: flash_args.expect_dpidr = <value> is not a full 32-bit SW-DP ID (8 hex digits) -- refusing to arm the wrong-board guard with a value short enough to match more than one board (ARM's own JEP106 designer field, 0x477, is shared by every ARM SW-DP).
```

Set `ALP_FLASH_REQUIRE_DPIDR` to require the guard rather than merely honour it when declared.

### `tan size` — footprint vs the SoM memory budget

```bash
tan build && tan size            # does each image fit the silicon?
tan size --fail-over-budget      # CI gate: non-zero exit when over
tan size --format json           # machine-readable (VS Code extension)
```

Walks `build/system-manifest.yaml`, measures every Zephyr slice's `zephyr.elf`, and compares FLASH and RAM usage against the budget resolved from the SoM's SoC metadata — **before** you flash. A slice whose budget can't be resolved is skipped and reported, **never guessed**.

| Option | Meaning |
|---|---|
| `APP_PATH` (argument, optional) | App directory (default `.`) |
| `--build-root` | Override the build root (default `<app_path>/build`) |
| `--board SKU` | Override the SoM SKU used to resolve the memory budget (default: `hw_info.sku` from the manifest). Distinct from the global `--board-yaml` |
| `--fail-over-budget` | Exit non-zero if any slice exceeds its resolved budget |

### `tan image` — assemble a flashable bundle

```bash
tan build && tan image           # produces build/image-bundle/
```

Reads `build/system-manifest.yaml` and assembles a single flashable bundle under `build/image-bundle/`: per-slice `tar.gz` archives, helper-MCU firmware, and a `bundle-manifest.json` with per-artefact SHA-256s. Takes an optional `APP_PATH` argument and `--build-root`. As of 0.7.0 it deletes the previous `bundle-manifest.json` before pruning old archives, so a run that fails mid-assembly no longer leaves a manifest naming archives that were deleted or re-hashed.

### `tan clean` — remove build outputs

```bash
tan clean                        # remove <app>/build + orchestrator state cache
tan clean --dry-run              # list what would go, delete nothing
```

Removes the per-project build directory and the orchestrator's `.alp-build-state.json`. Takes an optional `APP_PATH` argument (default `.`) and `--build-root`.

Two safety refusals are new in 0.7.0. `tan build` records each slice's `build_dir` in `build/system-manifest.yaml` as an absolute path, so a project copied or renamed with its `build/` still names the **original** project's slice trees; `tan clean` now refuses any slice dir that lies inside another project's tree (`clean.unsafe-target`, naming that project) and still cleans this project's own build root. Pointing `--build-root` at the build directory itself (`tan clean --build-root build`) now refuses with `clean.unsafe-build-root` instead of silently removing nothing.

### `tan renode` — removed in v0.6.0 {#renode-retired}

:::danger[`tan renode` no longer exists]
`tan` **v0.6.0** removed the `renode` verb, and alp-sdk **v0.16.0** removed everything behind it — the four `pr-renode-*` CI workflows, the platform models (`metadata/renode/alif_ensemble_e8.repl` / `.resc`, `metadata/renode/renesas_rzv2n.repl` / `.resc`), the Renode-only fixtures under `tests/renode/`, and the `examples/aen/aen-sim-vision/` example whose only run path it was. [ADR 0022](https://github.com/alplabai/alp-sdk/blob/main/docs/adr/0022-python-executor-renode-retirement.md) Amendment 2 (2026-08-17) is the decision; the order to read is *accepted 2026-08-04 → withdrawn 2026-08-07 → re-instated and widened 2026-08-17*.

- A script calling `tan renode ...` now fails as an **unknown command** — the verb does not resolve.
- All **26 `renode.*` issue codes are unpublished**, not merely unused: a consumer matching on one in the JSON envelope's `issues[]` will never see one again. The registry went from **290 to 288** codes overall (26 removed, 24 added).
- `--sim-mode` went with the verb. Alp Studio's hardware simulator is unaffected — it consumes the image bundle, not `tan`.

**What to do instead.** Build and flash real hardware (`tan build` + `tan flash`), or run a single image headless under `native_sim` with `tan run` when that image has no cross-core dependency. **There is no simulated substitute for the cross-core RPMsg handshake** — that must be verified on silicon. alp-sdk records the cost without hedging: it loses pre-silicon simulator coverage outright, with no replacement planned, and after this change no CI job boots any alp-sdk image on any core.

[`diagnostics.sim_console:`](https://docs.alplab.ai/sdk/board-yaml#diagnostics-block) is **retained** in `board.yaml` — schema, metadata and emitters. It emits `CONFIG_RAM_CONSOLE=y` for headless cores on behalf of Alp Studio's simulator, and never was a `tan renode` key.
:::

### `tan generate` — write the board-derived config files

```bash
tan generate                              # every generate target for this board
tan generate --target zephyr-conf         # just the per-core Zephyr fragment
tan generate --target native-sim-overlay --force # overwrite an existing native_sim overlay
```

Renders the board-derived config in-process from `tan.planner` and writes it into the project. Without `--target` it produces the full default set; `--force` allows overwriting an existing native_sim overlay (an explicit `--target native-sim-overlay`); no other target consults it. Setting `TAN_GENERATE_EXECUTOR=subprocess` switches to the opt-in escape hatch that spawns the SDK's `scripts/alp_project.py` instead.

`--target` accepts **12 targets**. Nine are in the default / `--all` set: `zephyr-conf`, `dts-overlay`, `native-sim-overlay`, `cmake-args`, `yocto-conf`, `carrier-netlist`, `west-libraries`, `hw-info-h`, and `os-topology`. Three more are explicit-only and never run as part of the default set: `zephyr-board` (which additionally requires `--core`), `composed-route-table`, and `ipc-contract-h`.

`carrier-netlist` is a board-level export (the deterministic carrier nets + BOM handoff Alp Studio consumes) rather than a per-core build config, and `native-sim-overlay` is the Zephyr overlay (`alp,pin-array` on `zephyr,gpio-emul`) that makes a GPIO app resolve under `native_sim`.

Two behaviours changed in `tan` 0.6.0:

- **`--all` together with `--target` is now refused** rather than silently resolving to one of them.
- **An *implicit* `native-sim-overlay` whose on-disk file lacks the ownership banner is silently dropped**, with warning `generate.overlay-not-owned` at exit **0**. So a bare `tan generate` can legitimately report **8** targets rather than 9 — that is not a failure. Asking for it explicitly (`--target native-sim-overlay`) still refuses with `generate.would-overwrite` and exit **3** unless you pass `--force`.

`zephyr-board` without `--core` fails with `generate.invalid-target` and exit **2**.

`tan explain --target <mode>` describes a generation target; `tan trace` shows the generation decisions a build would make, and `tan diff` shows how `board.yaml` normalisation changes the effective config.

#### The full emit catalog {#emit-catalog}

The generate targets are a subset of the SDK's **one catalog** of generated artefacts. Every mode is emitted by the single implementation that owns it — a front door only routes:

| Mode | Artefact | Emitted by |
|---|---|---|
| `zephyr-conf` | Per-core Zephyr `alp.conf` Kconfig fragment | `alp_project.py` |
| `cmake-args` | Per-core `-D` CMake argument list | `alp_project.py` |
| `yocto-conf` | Per-core `local.conf` fragment | `alp_project.py` |
| `dts-overlay` | Board DTS overlay (bus aliases + pin array) | `alp_project.py` |
| `native-sim-overlay` | `native_sim` overlay: `alp,pin-array` on `zephyr,gpio-emul` | `alp_project.py` |
| `hw-info-h` | Build-time `hw_info.h` macro header | `alp_project.py` |
| `west-libraries` | `west.yml` fragment for `libraries:` deps | `alp_project.py` |
| `zephyr-board` | **Per-core Zephyr board tree** (directory — see below) | `alp_project.py` |
| `composed-route-table` | JSON route-table dump (demonstrator) | `alp_project.py` |
| `carrier-netlist` | Studio-facing carrier nets + BOM JSON handoff | `alp_project.py` |
| `os-topology` | Per-core natural-vs-effective OS facts | `alp_project.py` |
| `scaffold` | New-project `{path, contents}[]` envelope for a template | `alp_project.py` |
| `system-manifest` | Full-system manifest (slices, boot order) | orchestrator |
| `dts-reservations` | DTS reserved-memory overlay (cross-core carve-outs) | orchestrator |
| `linux-ownership-dts` | Per-project Linux (A55) core-ownership devicetree fragment for the RZ/V2N family (`build/generated/linux-ownership.dtsi`); new in alp-sdk v0.17.0 | `alp_project.py` (`alp_orchestrate/linux_ownership.py`) |
| `ipc-contract-h` | Cross-core IPC contract header | orchestrator |
| `dts-partitions` | DTS fixed-partitions overlay (`storage:` entries) | orchestrator |
| `storage-mounts-c` | Static C storage mount table | orchestrator |
| `tfm-sysbuild-conf` | TF-M sysbuild child-image overlay (`security.psa:`) | orchestrator |
| `build-plan` | Per-slice build plan, JSON (IDE / CI / `tan` consumers) | orchestrator |
| `kconfig` | Board-scoped, user-settable Kconfig symbol menu for the `prj.conf` LSP, JSON | orchestrator |

`west alp-emit <mode>` exposes the orchestrator subset for west-centric scripting: `system-manifest`, `ipc-contract-h`, `dts-reservations`, `dts-partitions`, `storage-mounts-c`, `tfm-sysbuild-conf`, `build-plan`, `kconfig`. Read-only — it prints to stdout and builds nothing. The rest are reachable from `scripts/alp_project.py --emit <mode>` (which delegates the project-level ones to the same orchestrator emitters), so no mode can produce different bytes depending on which front door you used.

`scaffold` is the odd one out on inputs: it materialises a **new** project, so there is no `board.yaml` to find yet — it takes `--template <catalog-id>` and `--sku <SKU>` instead (`metadata/templates/catalog-v1.json` holds nine ids: `minimal`, `peripheral`, `sensor`, `multicore-rpmsg`, `gateway`, `edge-ai`, `diagnostics`, `iot` — the only one still `preview` — and `multicore-mailbox`).

Every template record carries a `cores: [{id, dir, os}, ...]` array transcribing its canonical example's own `board.yaml` `cores:` map, drift-checked against it. `multicore-mailbox` is the first template with two explicit `os: zephyr` cores — `{ id: m55_hp, dir: ./src, os: zephyr }` and `{ id: m55_he, dir: ./peer, os: zephyr }` — so scaffolding applies each core's own `--core` substitution to that core's own `CMakeLists.txt` (`src/` gets `--core m55_hp`, `peer/` gets `--core m55_he`) instead of stamping one scalar core onto every core directory.

`kconfig` is the odd one out on *dependencies*: it projects a board-scoped, user-settable Kconfig symbol menu (`{schemaVersion, board, core, symbols[]}`) for the VS Code `prj.conf` LSP, and to do so it configures a throwaway stub app via `west build --cmake-only` — so unlike every other mode it is **workspace-dependent** (`--core` is required and it exits loudly when `ZEPHYR_BASE` / `kconfiglib` aren't available, rather than emitting a partial menu). It is therefore outside the hermetic emit-snapshot gate; a cross-repo golden-fixture conformance check keeps its envelope in lockstep with the `tan` and VS Code consumers instead.

:::info[Machine-readable mode registry]
`metadata/emit-registry-v1.json` is the single source of truth for the emit-mode set — which modes exist, which CLI parses each, and the module + function that implements it. Frontends (the VS Code extension, Alp Studio) read that file instead of hand-mirroring these lists, and a drift gate (`scripts/check_emit_registry.py`) asserts it matches the real `--emit` choices parsed out of the CLIs.
:::

#### `zephyr-board` — generate a Zephyr board tree {#emit-zephyr-board}

```bash
PYTHONPATH=scripts python3 scripts/alp_project.py --input board.yaml \
    --emit zephyr-board --core m55_hp --output build/boards/alp_e1m_aen801_m55_hp/
west build --board-root build/boards -b alp_e1m_aen801_m55_hp/ae822fa0e5597ls0/rtss_hp <app>
```

Generates a per-core Zephyr board tree from the SoM preset + SoC JSON (#523) — the Zephyr board artefacts are derived from metadata rather than hand-maintained. This mode is the odd one out among the emitters: it writes a **directory of files, not a stream**, so both `--core` and `--output` are **required**, and `--output` names the board directory itself (not its parent).

Coverage is honestly partial, and differs by family:

| Family | Generated | Still hand-authored |
|---|---|---|
| Alif Ensemble (`E1M-AEN*`) | `board.yml`, `Kconfig.alp_<board>`, twister `.yaml`, `-pinctrl.dtsi`, `_defconfig`, `Kconfig.defconfig`, `.dts` | `board.cmake`, bare `Kconfig` |
| Renesas RZ/V2N (`E1M-V2N*` / `E1M-V2M*`, `m33_sm`) | `board.yml`, `Kconfig.alp_<board>`, twister `.yaml`, `-pinctrl.dtsi`, `_defconfig`, `.dts` | `board.cmake`, bare `Kconfig` |

**Changed in alp-sdk v0.17.0:** the RZ/V2N family now generates its pinctrl `.dtsi`, `_defconfig` and board `.dts` too — they read the hand-authored `metadata/e1m_modules/v2n/supervisor-links.yaml`, and the `.dts` adds the OpenAMP reserved-memory block when the SoM preset sets `topology.m33_sm.openamp_ipc`. (Before v0.17.0 only the three family-agnostic files were generated for V2N.) The i.MX 93 family is gone along with E1M-NX9101.

`board.cmake` and the bare `Kconfig` are **never** generated, for any family, and nothing in the emit, the CLI output or the JSON envelope says so — copy both across by hand when you use a generated tree as the board directory. The bare `Kconfig` matters more than it looks: on AEN it turns on the custom E8 MPU region table, and its absence is silent — the build succeeds and falls back to Zephyr's generic two-region map.

See [`carrier-netlist`](https://docs.alplab.ai/sdk/board-yaml#carrier-netlist-studio-handoff) in the `board.yaml` reference for what the Studio handoff contains — and, just as importantly, what it deliberately excludes.

### `tan validate` — check a `board.yaml`

```bash
tan validate                        # the resolved project's board.yaml
tan --board-yaml path/to/board.yaml validate
tan validate --format json          # machine envelope for an IDE / LSP / CI
tan validate --offline              # structural checks only, no SDK checkout needed
tan validate --format sarif         # SARIF 2.1.0 log for code-scanning CI
```

Runs the SDK's rich board.yaml validator against the resolved `board.yaml` — JSON-Schema pass, SoM / preset cross-references, peripheral-vs-SoC capability check — rendering every finding as a Rust-style diagnostic block with an `ALP-Bxxx` code. **As of 0.7.0 it runs in-process**, as a port of the SDK's validator inside `tan`, instead of spawning `scripts/validate_board_yaml.py`; `TAN_VALIDATE_ENGINE=subprocess` restores the spawn. When the bound SDK is newer than the port, `tan` warns (`validate.sdk-validator-newer`) because the SDK may reject a board the port accepts. `--offline` runs only `tan`'s own structural checks, which need no SDK checkout.

Exit 0 means no hard errors. Non-clean outcomes have their own issue codes — `validate.schema-violation`, `validate.missing-preset`, `validate.hardware-revision`, and, new in 0.7.0, `validate.hardware-revision-unknown` (pick a revision that exists) and `validate.hardware-revision-not-buildable` (pick a revision whose status is buildable).

| Option | Meaning |
|---|---|
| `--offline` | Run only the structural checks that ship in `tan` |
| `--format text\|json\|diagnostic-v1\|sarif` | `json` is the machine envelope (outcome, issue count, resolved `board.yaml` path); `diagnostic-v1` and `sarif` print only the structured document to stdout, so both are safe to pipe |

The versioned machine diagnostics are governed by alp-sdk's `metadata/schemas/diagnostic-v1.schema.json` — the IDE/LSP/CI-facing contract that replaces parsing terminal prose. Its ranges are **zero-based** (LSP `Position`/`Range` convention), while a SARIF 2.1.0 log's regions are **one-based** per the SARIF spec; the human renderer's Rust-style 1-based `line:col` is unchanged by either. **Changed in 0.7.0:** both formats now emit a `file:` URI, or a percent-encoded relative reference, in `uri` / `artifactLocation.uri` instead of a raw host path.

### `tan model` — compile, screen and benchmark AI models

```bash
tan model build                          # compile board.yaml `models:` entries into .alpmodel packages
tan model doctor                         # which NPU-compiler toolchains this host has
tan model check                          # static NPU-eligibility screen, no NPU toolchain needed
tan model list                           # declared models next to what is already built
tan model zoo --sku E1M-AEN801           # the SDK's model zoo, filtered to bench-validated entries for a SoM
tan model add <id>                       # add a zoo model to the project
tan model prep model.onnx --calibration samples/   # INT8-quantize with an accuracy report
tan model run model.onnx                 # time a host reference run
tan model ab model.onnx --against other.onnx       # compare two models
```

A native `tan` command with nine subcommands (0.6.0 had only `build`). `build` compiles every `models:` entry declared in `board.yaml` into a `.alpmodel` package via the SoM-appropriate backend (Vela for Ethos-U, DRP-AI for RZ/V2N, …) — see [Inference](https://docs.alplab.ai/sdk/api/inference#building-a-package) for the end-to-end flow. `check` answers `npu-eligible`, `cpu-certain` or `undetermined` — deliberately never "fits", which is reserved for a real compile or a bench measurement; `check --exact` attempts a real compile instead (Ethos-U only, via `vela`). `run` and `ab` time a **host** reference run unless you add `--device`, which reports the on-device tier from a `--capture FILE` or live — a live run RAM-runs the built `diagnostics.link: itcm` project over J-Link, resets the whole device, and therefore needs `--confirm`; it never writes MRAM. Run `tan model --help` for every flag.

### `tan doctor` — host readiness preflight

```bash
tan doctor                                   # can this host build and flash the resolved project?
tan doctor --fix                             # …and run the manifest's install command for missing prerequisites
tan doctor --format json                     # machine-readable report
```

Hardware-free: it diagnoses whether this host can build and flash — the SDK checkout, the west workspace and its venv, `ZEPHYR_BASE`, the host build tools read from the SDK's own `metadata/bootstrap.json`, and the cross toolchain — and names what is missing on *this* host together with the command that fixes it. It exits non-zero when any check fails. Run it first whenever a build machine misbehaves; it needs none of the build tools itself.

| Option | Meaning |
|---|---|
| `--fix` | Run the manifest's own install command for any missing host prerequisite. Only in an **interactive** text-mode run (a real terminal on both stdin and stderr); `--non-interactive`, `--ci` and `--format json` all disable it, so it is not a scripted-onboarding remedy. `tan` never spawns `sudo` itself: a `sudo`-prefixed command runs only when `tan` is already root, otherwise it is printed for you to run |
| `--build` | Accepted for compatibility only. The build-readiness checks it used to gate now always run, so it no longer changes anything |
| `--project` / `--sdk-root` / `--board-yaml` | Which project and SDK to check |

:::warning[New in 0.7.0: the `toolchain` check can fail a host that passed before]
`tan doctor` gains a **`toolchain`** check for the resolved project: it compares the toolchain `tan bootstrap` installed (its verification stamp) against the version pinned in the SDK's `metadata/toolchains.json` — never mere directory existence. A version-skewed or never-verified install is a **`fail`** that names `tan bootstrap` as the fix, and makes `tan doctor` exit **4**. A toolchain found outside `tan`'s store is reported with the caveat that it was never compared with the pin. The separate `zephyrSdk` check still answers the broader "is there any Zephyr SDK toolchain on this host at all" question.

`tan bootstrap`, `tan doctor` and `tan build` no longer point you at a hand-run `west sdk install -t arm-zephyr-eabi` when the toolchain is missing — that path downloads the toolchain archive with no integrity check. They now say to run `tan bootstrap`, which verifies it.
:::

:::caution[Windows: executables are resolved by absolute path]
`doctor` resolves `git`, `py`, `python` and `python3` to an **absolute path** before spawning them, via a hand-rolled `%PATH%` walk — `shutil.which` / `where.exe` put the current directory *ahead* of `PATH`, which is a real hijack surface. One consequence is visible: on Windows an **extension-less** file on `%PATH%` is not a match, so a host whose `git` / `cmake` / `ninja` is an extension-less POSIX shim reports it **missing**. On native Windows, `tan doctor` also flags a missing 7-Zip-compatible extractor, which `west sdk install` needs to unpack the Zephyr SDK.
:::

When `tan` has **no confirmed install command** for a host's package manager — anything that is not `apt`/`dnf` on Linux, `brew` on macOS or `winget` on Windows — it degrades to a host-neutral hint rather than guessing a package name, and the machine-readable `data.missingPrerequisites[].command` field becomes **`null`**, never prose:

```
tan has no confirmed install command for this host: <tools>. Install them with your OS's package manager and put them on PATH, then run `tan bootstrap`.
```

`tan` also confirms an install command's *installer* is actually on PATH before offering it. `pacman` is deliberately never probed — see [Installation](https://docs.alplab.ai/sdk/installation#linux-fedora--rhel-derivatives) for why.

`tan support-bundle` packages `inspect` + `trace` + `doctor` into one diagnostic export when you need to hand the state to someone else.

### `tan monitor` — serial console

```bash
tan monitor --port COM7                # Windows
tan monitor --port /dev/ttyUSB0        # Linux
tan monitor                            # lists available ports if none given
tan monitor --port /dev/ttyUSB0 --break-uboot                           # stop at the U-Boot prompt, then stay interactive
tan monitor --capture --port /dev/ttyUSB0 --until 'Booting Zephyr' --log boot.log   # headless capture
```

A native `tan` command, with stdio kept attached so the terminal stays interactive. Opens pyserial's miniterm (`Ctrl+]` to quit). Baud defaults to 115200 (`--baud` to override). When no port is given, or the requested one doesn't exist, it lists every serial port on the host and exits non-zero instead of hanging on a wrong device. `--port` also takes pyserial URLs such as `rfc2217://host:port` for a networked serial server.

New in 0.7.0:

| Option | Meaning |
|---|---|
| `--break-uboot` | After opening the port, send the autoboot interrupt key repeatedly until the U-Boot prompt appears (or `--break-timeout`, default 30 s, passes), then continue in the interactive console on the same open port. `--break-key` (default: a space) and `--prompt` (default `=> `) tune it; with `--non-interactive` it stops after the break-in. Power-cycle the board yourself |
| `--capture` | Headless capture instead of an interactive console: no TTY needed, raw bytes stored. Needs `--duration` and/or `--until` |
| `--duration SECONDS` / `--until REGEX` | With `--capture`: how long to read, and/or stop at the first line matching the regex. No match in time is an error |
| `--log FILE` | With `--capture`: write the raw bytes to this file |
| `--send TEXT` | With `--capture`, repeatable: write text to the console (escapes `\xNN \r \n \t \\`, no newline added) — at the start, after `--send-after`, or on the first line matching `--send-on` |
| `--reopen-at BAUD` / `--on REGEX` | With `--capture`: change the baud rate on the first line matching `--on`, then keep capturing |
| `--filter` | Console output filter: `colors` (default — colours render, every other escape is neutralised), `default` / `nocontrol` / `printable` (strip control codes), or `direct` (raw bytes — unsafe for untrusted targets) |

### `tan probe` — read-only J-Link inspection

```bash
tan probe identify --core m55_he                # SW-DP ID, access port, CPUID, core verdict
tan probe read 0x80010000 4                     # four 32-bit words
tan probe identify --probe-usb-path 3-4.2 --format json
```

**New in 0.7.0.** A read-only J-Link inspector, so a bench no longer needs raw `JLinkExe` for "what is attached?". `identify` runs the same SW-DP ID preflight `tan flash` uses and reports the access port, CPUID and a core verdict; `read ADDR [WORDS]` is a bounded `mem32` (default 4 words, at most 256; the address must be 4-byte aligned). It **never** writes, erases, halts, resets or runs the target. `read` refuses the `0x50000000`–`0x5FFFFFFF` window on every core (`probe.read-unsafe-region`). With a `build/system-manifest.yaml` present, the slice's `flash_args` supply `expect_dpidr` (which `identify` compares) and the J-Link serial and speed.

| Option | Meaning |
|---|---|
| `--core` | The core you mean to probe; also picks the manifest slice. `identify` checks the attach against it (`probe.core-mismatch`) |
| `--probe-serial` / `--probe-usb-path` | Select the J-Link, exactly as for `tan flash` |
| `--build-root` | Build root holding `system-manifest.yaml` (default `<project>/build`) |
| `--jlink` | The J-Link Commander binary to use |

### `tan reset` — one nRESET pulse

```bash
tan reset --probe-usb-path 3-4.2
tan reset --probe-usb-path 3-4.2 --confirm-console /dev/ttyUSB0 --expect 'Booting Zephyr'
```

**New in 0.7.0.** Pulses nRESET once through J-Link — `r0`, wait `--pulse-ms` (default 100), `r1` — with no connect, no halt, no connect-under-reset and no retry; it does not flash. `tan` only **claims** a reset when you give it a console to watch: with `--confirm-console PORT --expect REGEX`, the port is opened before the pulse and the reset counts as observed only if a line matching it arrives within `--confirm-window` seconds (default 3) after J-Link exits. Pick a banner printed some time *after* reset; text emitted before J-Link exits is not counted. Without `--confirm-console` the result is `resetObserved: unknown`. `--confirm-baud` (default 115200) and `--confirm-timeout` (default 30 s) tune the watch.

### `tan explain` / `tan faultdecode` — inspection and diagnostics

```bash
tan explain                            # overview of everything explainable
tan explain --template minimal-app     # what a project/module template produces
tan explain --target zephyr-conf       # what a generation target emits
tan explain --code ALP-B001            # an alp-sdk diagnostic or error code: cause + fix
tan faultdecode fault.txt              # decode an ARMv8-M (M33/M55) fault dump
tan faultdecode --cfsr 0x8200 --format json
```

`tan explain` describes a project or module template, a generation target, or — with `--code` — an alp-sdk diagnostic or error code (e.g. `ALP-B003`, `ALP_ERR_NO_BACKEND`), read from the bound SDK checkout. Pass one selector at a time; an unknown id fails with the catalog of valid ids. `tan faultdecode` is a native `tan` command that decodes a Cortex-M fault-register dump into a human-readable cause chain (`--format json` emits the machine-readable report).

`tan explain --code` replaces the SDK-side `python -m alp_cli explain`, which alp-sdk v0.17.0 retired together with the rest of the `alp_cli` command-line wrappers.

`tan inspect` (resolved project/debug context), `tan presets` (SKUs and catalogue defaults), `tan pinmux` (the E1M pad → silicon function capability table), and `tan examples` round out the read-only inspection verbs.

## West-only commands

Three `west alp-*` commands operate on the workspace or the repo rather than on one app. `tan migrate` / `tan lock` / `tan quality` forward to them verbatim, so the flags below are the flags either spelling takes.

### `west alp-lock` — dependency lock file {#west-alp-lock}

```bash
west alp-lock                        # write ./alp.lock for the workspace
west alp-lock --check                # generate + schema-validate in memory; non-zero on a broken generator
west alp-lock --board path/to/board.yaml
```

Writes **`alp.lock`**, the dependency lock — the resolved identity of everything the build consumes: the workspace's **SDK version**, west project pins, curated library versions, Python requirements, and metadata digests.

:::info[`alp.lock` is generated on demand, not committed — changed in alp-sdk v0.17.0]
alp-sdk no longer tracks `alp.lock` in the repository. Its `digests.metadata` field is a single hash over the whole `metadata/**` tree, so any two changes touching different metadata files conflicted on that one line. The generator is a pure function of tracked files, so regenerating from the same commit reproduces the identical document.

`west alp-lock --check` therefore no longer diffs against a committed copy — there isn't one. It builds a lock in memory and validates it against `metadata/schemas/alp-lock-v1.schema.json`, failing on a broken generator or a local-path leak.
:::

| Option | Meaning |
|---|---|
| `--check` | Generate and schema-validate in memory instead of writing; non-zero on a broken generator or a local-path leak |
| `--workspace` | Workspace root (default: the west topdir) |
| `--board` | `board.yaml` to record `resolution.board` from |

The lock carries no `sdk.revision` (retired in alp-sdk v0.16.0, #1615): `alp-lock-v1.schema.json` still declares the property (`"type": ["string", "null"]`) only so an older lock validates. For "which SDK commit produced **this artifact**", use the build receipt (`scripts/build_receipt.py`) — fields `source.sdkRevision` and `source.sdkDirty`.

`alp.lock` is also the input to the deterministic SBOM: `scripts/gen_sbom.py` renders a **CycloneDX 1.5** document from it with a stable, lock-derived serial number and no wall-clock field, so the same lock always produces the same SBOM.

### `west alp-migrate` — `board.yaml` migration engine {#west-alp-migrate}

```bash
west alp-migrate --check             # report versions; non-zero on drift
west alp-migrate --preview           # unified diff + diagnostic-v1 JSON, no writes
west alp-migrate --apply             # rewrite in place, then regen derived files
west alp-migrate --apply --all       # every board.yaml under the repo
```

Versions and migrates a `board.yaml` **byte-faithfully** — comments, flow style and indentation survive a migration, so an applied migration produces a reviewable diff rather than a reformatted file. `--preview` prints a unified diff plus a [`diagnostic-v1`](https://docs.alplab.ai/sdk/board-yaml) JSON report and writes nothing. Exactly one of `--check` / `--preview` / `--apply` is required.

| Option | Meaning |
|---|---|
| `--check` / `--preview` / `--apply` | Mode (exactly one, required) |
| `--all` | Every `board.yaml` under the repo |
| `--board` | A single `board.yaml` path (default: `./board.yaml`) |
| `--no-verify` | Skip the post-apply regeneration of derived files |

:::note[The migration registry is empty — and that's the point]
No migration exists yet. The engine is in place so that the *first* real schema change can ship with a migration rather than a breakage, but today `--check` passes on everything and `--apply` is a no-op. This is coupled to `board.yaml`'s **lazy** versioning: an absent `schemaVersion:` **is** version 1, so hand-written and external projects are never "out of date" and never need the key. See [`schemaVersion`](https://docs.alplab.ai/sdk/board-yaml#schema-version).
:::

### `west alp-quality` — run the quality gates {#west-alp-quality}

```bash
west alp-quality --profile pr        # exactly the gates CI runs
west alp-quality --profile full
west alp-quality --profile pr --json r.json --junit r.xml --sarif r.sarif
```

Runs the quality-task registry (`metadata/quality-tasks-v1.json`) for a named profile and emits a human summary plus optional JSON, JUnit XML, and SARIF reports. The registry is the single source of truth for which `check_*.py` gates exist, whether each is a **hard gate** or informational, and which profiles run it — `scripts/test-all.sh` derives its required-gate list from the same registry rather than a hand-maintained array, which is what keeps local and CI from drifting apart.

| Profile | Runs |
|---|---|
| `pr` | All hard gates — exactly the gates CI's PR lane runs. The one to reach for before pushing |
| `full` | The `pr` set plus the informational (non-gating) checks |
| `release` | All hard gates |
| `quick` | A fast subset: 39 tasks in alp-sdk v0.17.0 (against 77 for `pr` and `release` and 80 for `full`) |

| Option | Meaning |
|---|---|
| `--profile` | `quick` / `pr` / `full` / `release` (required) |
| `--json` | Write a JSON report to this path |
| `--junit` | Write a JUnit XML report to this path |
| `--sarif` | Write a SARIF report to this path |

Only tasks marked as gates affect the exit code; informational tasks report but never fail the run.

The fourth surviving extension command, **`west alp-emit`**, is the read-only inspector for the orchestrator's emit subset — see [the emit catalog](#emit-catalog) above.

## Environment

| Variable | Effect |
|---|---|
| `ZEPHYR_BASE` | Checked by `tan doctor`. `tan build` always uses the resolved west workspace's own `zephyr/`; a `ZEPHYR_BASE` naming a different tree is ignored and reported |
| `ALP_TOOLCHAIN_ROOT` | Root of the cross-toolchain store `tan bootstrap` installs into and `tan build` / `tan doctor` read (default `~/.alp/toolchains`) |
| `TAN_GITHUB_TOKEN` (then `GH_TOKEN`, `GITHUB_TOKEN`) | Authenticates `tan bootstrap`'s GitHub API calls for the toolchain download; needs no scopes |
| `ALP_FLASH_FORCE=1` | Arms the flash confirm gate, like `--confirm` |
| `TAN_VALIDATE_ENGINE=subprocess` | Run the bound SDK's own `scripts/validate_board_yaml.py` instead of `tan`'s in-process port |
| `TAN_GENERATE_EXECUTOR=subprocess` | Run the SDK's `scripts/alp_project.py` for `tan generate` instead of rendering in-process |
| `ALP_VELA_CONFIG` | Optional path to a vendor Vela config `.ini` for `tan model` on Ethos-U. Unset (the common case), Vela uses Arm's built-in system config; `tan model doctor` reports it as an optional prerequisite |

There is no environment variable that selects the SDK checkout: `tan` resolves it from `--sdk-root`, the project pin, the global default, or a nearby checkout (see [above](#what-tan-runs-itself-and-what-it-delegates)). The verbs that shell out to the SDK backend export `ALP_SDK_ROOT` and put `<sdk>/scripts` on `PYTHONPATH` for their sub-processes — the same wiring the `west alp-*` wrappers use, so a `tan`-invoked orchestrator run behaves identically to a west one. For the slices it builds, `tan` reads the plan's own `env` / `envAppendPath` entries (sourced from the SDK's `--emit build-plan`) to set up `EXTRA_ZEPHYR_MODULES` and `PYTHONPATH`.

## See also

- [Installation](https://docs.alplab.ai/sdk/installation) — bootstrap the workspace, then install the CLI with `install.sh` / `install.ps1`
- [VS Code extension](https://docs.alplab.ai/sdk/tools/vscode) — the same SDK behind a GUI
- [`board.yaml` reference](https://docs.alplab.ai/sdk/board-yaml) — the schema `tan validate` enforces
- [Heterogeneous Builds](https://docs.alplab.ai/sdk/heterogeneous-builds) — the orchestrated multi-core pipeline `tan build` fronts
- [Architecture](https://docs.alplab.ai/sdk/architecture) — where the orchestrator fits into the build
- [`alplabai/tan-cli`](https://github.com/alplabai/tan-cli) — the CLI's own repository
