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
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.
tan 0.7.0 is a breaking release0.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.
tan 0.7.0 needs alp-sdk v0.17.0 or newertan 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:tanconsumesalp_orchestrate --emit build-planand--emit system-manifest, then runswest/bitbake/cmakeper slice itself, owns skip-vs-fail policy, and programs the hardware.- In-process generation —
generaterenders fromtan.plannerinside the process. Setting the environment variableTAN_GENERATE_EXECUTOR=subprocessis an opt-in escape hatch that spawns the SDK'sscripts/alp_project.pyinstead. - In-process validation — new in 0.7.0,
validateruns a port of the SDK's board.yaml validator insidetaninstead of spawningscripts/validate_board_yaml.py. When the bound SDK is newer than the port,tansays so (validate.sdk-validator-newer) because the SDK may have added rules the port does not apply. SettingTAN_VALIDATE_ENGINE=subprocessruns the bound SDK's ownscripts/validate_board_yaml.pyinstead. - The remaining spawns —
migrate/lock/qualityforward to the survivingwest 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.
tan build and the global flags — changed in 0.7.0In 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-interactiveand--ciare accepted ontan buildlike on every other verb (and, like there, have no build-specific effect).--pristineis now implemented — seetan build. - Retired:
--plan,--manifest,--manifest-fromand--no-auto-bootstraprefuse withbuild.flag-retiredand exit 2 (previouslycli.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;tanexecutes them. Nothing in alp-sdk builds or flashes any more. tan migrate/tan lock/tan qualityforward their tail verbatim towest 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 generaterenders fromtan.planner, whilewest alp-emitandscripts/alp_project.py --emitare the SDK-side front doors onto the SDK's own emitters.
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.
| 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
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.
| 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
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:
tancompares alp-sdk's SHA-256 pins with the SDK release'ssha256.sum, and downloads the toolchain archive itself, hashing it against the pin as it streams — the SDK's ownsetup.shfetches that archive with no check at all. A mismatch, an ambiguous sum entry, or a sum or archive that cannot be fetched refuses withbootstrap.toolchain-pin-mismatchorbootstrap.toolchain-pin-unverifiedand installs nothing.- It passes
--no-hosttoolstowest sdk install, so it needs nofileonPATH— and installs nodtc,openocd,bossacorqemu-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)
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:
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.
| 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.
--confirm is not a universal safety gate — two of the five backends ignore itOnly 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:.
| 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 |
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.
| 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
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
tan renode no longer existstan 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'sissues[]will never see one again. The registry went from 290 to 288 codes overall (26 removed, 24 added). --sim-modewent with the verb. Alp Studio's hardware simulator is unaffected — it consumes the image bundle, nottan.
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:
--alltogether with--targetis now refused rather than silently resolving to one of them.- An implicit
native-sim-overlaywhose on-disk file lacks the ownership banner is silently dropped, with warninggenerate.overlay-not-ownedat exit 0. So a baretan generatecan legitimately report 8 targets rather than 9 — that is not a failure. Asking for it explicitly (--target native-sim-overlay) still refuses withgenerate.would-overwriteand 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:
| 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.
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:
| 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 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).
| 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
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.
| 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 |
toolchain check can fail a host that passed beforetan 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.
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:
| 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
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
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.
alp.lock is generated on demand, not committed — changed in alp-sdk v0.17.0alp-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 --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.
| 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 |
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.
| 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 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). 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 — bootstrap the workspace, then install the CLI with
install.sh/install.ps1 - VS Code extension — the same SDK behind a GUI
board.yamlreference — the schematan validateenforces- Heterogeneous Builds — the orchestrated multi-core pipeline
tan buildfronts - Architecture — where the orchestrator fits into the build
alplabai/tan-cli— the CLI's own repository