Skip to main content

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: 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), 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:

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
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:

PlatformAsset
Windows x86_64tan-x86_64-pc-windows-msvc.zip
macOS x86_64tan-x86_64-apple-darwin.tar.gz
macOS arm64tan-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:

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) — 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):

FlagMeaning
--project PATHProject root (default: the current directory)
--board-yaml PATHExplicit board.yaml path; overrides project resolution
--sdk-root PATHalp-sdk checkout root
--target EMITGeneration target for generate / explain
--allRun against all relevant targets
--format text|jsonOutput format; json emits the machine-readable envelope
--verbose / --quietMore diagnostic detail / suppress non-essential output
--no-colorDisable ANSI colour
--non-interactiveNever prompt; fail instead of asking
--ciCI mode: implies --non-interactive and disables colour
--versionPrint 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.
  • 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 headlesstan build / tan flash / tan size / tan image / tan clean / tan run
Scaffolding, validating, compiling a model, checking the host, opening a console, decoding a faulttan init / tan validate / tan model / tan doctor / tan monitor / tan faultdecode
Inspecting (read-only) or resetting an attached module over J-Link, without flashingtan probe / tan reset
Writing the board-derived config files without a full buildtan generate (or west alp-emit <mode> from a west workspace)
Locking deps, migrating board.yaml, running the quality gateswest 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.
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. 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 and reset are new. renode was removed in 0.6.0 — see below. 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​

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.

OptionMeaning
--templateProject template id
--from-exampleSDK example category/name to copy verbatim (conflicts with --template)
--topologyNew 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
--nameProject name; creates a sub-directory when provided
--destinationDestination directory (default: the current directory or --project)
--som / --skuTarget SoM SKU written into the generated board.yaml, e.g. E1M-AEN701
--coresComma-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-yamlRender this file verbatim as the scaffolded board.yaml instead of the planned one
--previewShow planned files without writing anything
--forceAllow 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​

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.

OptionMeaning
--skuNew SoM SKU, e.g. E1M-NX9555
--soc-refSilicon triple-colon ref, e.g. nxp:imx9:imx95
--familyHuman-readable family slug, e.g. nxp-imx9
--vendorVendor display name for the SoC JSON (default: soc-ref vendor segment)
--display-namePreset display name (default derived from the SKU)
--inference-backendethos_u / drpai / deepx_dxm1 / tbd (default tbd)
--ethos-u-variantu55 / u85; required with --inference-backend ethos_u. u65 was dropped in 0.7.0 along with the i.MX 93 module that carried it
--coresComma-separated canonical core ids (default: a tbd_core0 placeholder)
--default-boardStock carrier board (default E1M-EVK)
--default-hw-revDefault hardware revision (default r1)
--output-rootRoot to generate metadata/ under (default: the SDK checkout)
--dry-runValidate and print the planned files; write nothing
--forceOverwrite an existing preset for this SKU

tan bootstrap — prepare the workspace and the cross toolchain​

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.

OptionMeaning
--sdk-root PATHThe alp-sdk checkout to bootstrap
--workspace PATHPut the west workspace here (moves the checkout — see above)
--no-toolchainNew in 0.7.0. Skip the arm-zephyr-eabi toolchain phase
--no-patchesNew 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-westSkip the pip installs / the west steps
--print-envPrint 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-partialReport 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-runShow the planned commands without running them

tan build — build the project (multi-core aware)​

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.

OptionMeaning
--plan-from FILERead the plan from a JSON file instead of invoking the SDK, show it, and build nothing
--materialiseWrite the plan's generated files (shared artefacts + per-slice config) under the build root and stop
--executeMaterialise 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)
--nativeAccepted 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 DIRProject tree the slices run under and artefacts are written below (default: the board.yaml's directory, else the current directory)
--pristineImplemented 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 / --defineNew 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 IDScope -D to the Zephyr slice(s) with this core id; repeatable (default: every Zephyr slice)
--board TARGETNew 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-bootstrapRetired — 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:

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​

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.

OptionMeaning
--flashProgram the board after the build (hardware targets only)
--core CORE_IDFlash only this slice
--confirmArm the flash confirm gate
--atoc-unqueryableNew 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-atocNew 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 / --formatAs 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​

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:.

OptionMeaning
APP_PATH (argument, optional)App directory (default .); a non-. value overrides --project
--coreFlash only the slice with this core_id (skips every other slice and all helpers)
--helperFlash only the helper MCU with this name (skips all slices and every other helper)
--dry-runPrint the command each backend would run; spawn nothing. Also bypasses the required-tool PATH gate
--confirmArm 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-unqueryableNew 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-atocOverride 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
--readbackAfter 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-resetFlow 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-configSign 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
--ramAEN 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 SECONDSWith --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-heWith --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 SNJ-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-PORTSelect the J-Link at this USB port path (e.g. 3-4.2), for benches with cloned probe serials. Linux only
--jlink PATHThe 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 PATHAlif 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)
--recoverAuthorise 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-rootOverride the build root holding system-manifest.yaml (default <app_path>/build)
--skip-missing-toolsWarn + skip an entry whose backend tools are all absent from PATH. No effect under --dry-run
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​

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.

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

tan image — assemble a flashable bundle​

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​

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​

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 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: 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​

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​

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:

ModeArtefactEmitted by
zephyr-confPer-core Zephyr alp.conf Kconfig fragmentalp_project.py
cmake-argsPer-core -D CMake argument listalp_project.py
yocto-confPer-core local.conf fragmentalp_project.py
dts-overlayBoard DTS overlay (bus aliases + pin array)alp_project.py
native-sim-overlaynative_sim overlay: alp,pin-array on zephyr,gpio-emulalp_project.py
hw-info-hBuild-time hw_info.h macro headeralp_project.py
west-librarieswest.yml fragment for libraries: depsalp_project.py
zephyr-boardPer-core Zephyr board tree (directory — see below)alp_project.py
composed-route-tableJSON route-table dump (demonstrator)alp_project.py
carrier-netlistStudio-facing carrier nets + BOM JSON handoffalp_project.py
os-topologyPer-core natural-vs-effective OS factsalp_project.py
scaffoldNew-project {path, contents}[] envelope for a templatealp_project.py
system-manifestFull-system manifest (slices, boot order)orchestrator
dts-reservationsDTS reserved-memory overlay (cross-core carve-outs)orchestrator
linux-ownership-dtsPer-project Linux (A55) core-ownership devicetree fragment for the RZ/V2N family (build/generated/linux-ownership.dtsi); new in alp-sdk v0.17.0alp_project.py (alp_orchestrate/linux_ownership.py)
ipc-contract-hCross-core IPC contract headerorchestrator
dts-partitionsDTS fixed-partitions overlay (storage: entries)orchestrator
storage-mounts-cStatic C storage mount tableorchestrator
tfm-sysbuild-confTF-M sysbuild child-image overlay (security.psa:)orchestrator
build-planPer-slice build plan, JSON (IDE / CI / tan consumers)orchestrator
kconfigBoard-scoped, user-settable Kconfig symbol menu for the prj.conf LSP, JSONorchestrator

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.

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​

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:

FamilyGeneratedStill hand-authored
Alif Ensemble (E1M-AEN*)board.yml, Kconfig.alp_<board>, twister .yaml, -pinctrl.dtsi, _defconfig, Kconfig.defconfig, .dtsboard.cmake, bare Kconfig
Renesas RZ/V2N (E1M-V2N* / E1M-V2M*, m33_sm)board.yml, Kconfig.alp_<board>, twister .yaml, -pinctrl.dtsi, _defconfig, .dtsboard.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 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​

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).

OptionMeaning
--offlineRun only the structural checks that ship in tan
--format text|json|diagnostic-v1|sarifjson 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​

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 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​

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.

OptionMeaning
--fixRun 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
--buildAccepted for compatibility only. The build-readiness checks it used to gate now always run, so it no longer changes anything
--project / --sdk-root / --board-yamlWhich 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.

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 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​

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:

OptionMeaning
--break-ubootAfter 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
--captureHeadless capture instead of an interactive console: no TTY needed, raw bytes stored. Needs --duration and/or --until
--duration SECONDS / --until REGEXWith --capture: how long to read, and/or stop at the first line matching the regex. No match in time is an error
--log FILEWith --capture: write the raw bytes to this file
--send TEXTWith --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 REGEXWith --capture: change the baud rate on the first line matching --on, then keep capturing
--filterConsole 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 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.

OptionMeaning
--coreThe core you mean to probe; also picks the manifest slice. identify checks the attach against it (probe.core-mismatch)
--probe-serial / --probe-usb-pathSelect the J-Link, exactly as for tan flash
--build-rootBuild root holding system-manifest.yaml (default <project>/build)
--jlinkThe J-Link Commander binary to use

tan reset — one nRESET pulse​

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​

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 # 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.

OptionMeaning
--checkGenerate and schema-validate in memory instead of writing; non-zero on a broken generator or a local-path leak
--workspaceWorkspace root (default: the west topdir)
--boardboard.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 --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 JSON report and writes nothing. Exactly one of --check / --preview / --apply is required.

OptionMeaning
--check / --preview / --applyMode (exactly one, required)
--allEvery board.yaml under the repo
--boardA single board.yaml path (default: ./board.yaml)
--no-verifySkip the post-apply regeneration of derived files
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.

west alp-quality — run the quality gates​

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.

ProfileRuns
prAll hard gates — exactly the gates CI's PR lane runs. The one to reach for before pushing
fullThe pr set plus the informational (non-gating) checks
releaseAll hard gates
quickA fast subset: 39 tasks in alp-sdk v0.17.0 (against 77 for pr and release and 80 for full)
OptionMeaning
--profilequick / pr / full / release (required)
--jsonWrite a JSON report to this path
--junitWrite a JUnit XML report to this path
--sarifWrite 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 above.

Environment​

VariableEffect
ZEPHYR_BASEChecked 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_ROOTRoot 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=1Arms the flash confirm gate, like --confirm
TAN_VALIDATE_ENGINE=subprocessRun the bound SDK's own scripts/validate_board_yaml.py instead of tan's in-process port
TAN_GENERATE_EXECUTOR=subprocessRun the SDK's scripts/alp_project.py for tan generate instead of rendering in-process
ALP_VELA_CONFIGOptional 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). 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​

Questions about this page? Email contact@alplab.ai