The CLI
Everything ships as typecad-hal — run it through npx @typecad/hal or
install it. The whole toolchain is one binary: the daily loop is create, build, test.
commands
The full command list. Global options: --help, and the port can always come from the TYPECAD_HAL_PORT environment variable.
Example first
| Command | What it does |
|---|---|
| typecad-hal create [name] | Scaffold a project for a board target |
| typecad-hal build | Transpile, and with flags compile, upload, monitor |
| typecad-hal test [files...] | Flash and run hardware tests |
| typecad-hal board sync | regen | Rebuild the board catalog / regenerate the board module |
| typecad-hal preview | Browser preview of a UI screen |
| typecad-hal doctor | Verify the toolchain (west, SDK, board target) |
| typecad-hal licenses | SPDX audit of the Zephyr tree and its projects |
| typecad-hal sbom | Emit/verify the build-true SBOM (CycloneDX 1.6 or SPDX 2.3) |
| typecad-hal audit | Security baseline over the last build’s merged Kconfig + devicetree |
| typecad-hal trace capture | report | view | Runtime trace: record the board, summarize it, serve the live timeline |
| typecad-hal library search | install | init | validate | The library-package catalog |
| typecad-hal query | Ask the board module questions |
| typecad-hal gen-decls | Generate .d.ts from C++ headers |
| typecad-hal clean | Remove generated output |
| typecad-hal debug-server start | stop | Drive the west GDB server for debugging |
terminal
typecad-hal create my-project --target xiao_ble/nrf52840
typecad-hal build --compile --upload --monitor --port COM4build
The transpile-and-flash pipeline. Flags chain: --compile builds, --upload flashes, --monitor watches the serial port. Most flags have sensible defaults; the config file covers the rest.
Example first
| Flag | Meaning |
|---|---|
| --compile | Run west build |
| --upload | Flash — requires --compile |
| --monitor | Attach a serial monitor after upload — waits out post-flash re-enumeration instead of racing it |
| --watch, -w | Rebuild on changes (not combinable with --monitor) |
| --expect [file] | Run hardware tests after the build |
| --port / --baud | Serial port for upload/monitor/tests |
| --diagnostics | Write the build report (Markdown/JSON) |
| --debug | Native GDB source-level debugging (F5 in VS Code) — boards without a debug probe fail with debug-unsupported-target |
| --force | Bypass the cached lint gate |
| --skip-type-check / --no-transpile | Partial runs for special cases |
Tree-shaking
Unused code never reaches the board — reachability from the entry point decides. Flags override:
| Flag | Meaning |
|---|---|
| --no-tree-shake | Keep everything |
| --keep-unused-enums / -classes / -types / -variables | Keep one category |
| --entry-point <name> | Additional entry point — repeatable |
Everything else
| Flag | Meaning |
|---|---|
| --autosar[=off|warn|strict] | AUTOSAR C++14 checks on the generated code (bare flag = strict) |
| --autosar-arxml | Emit the deviation file for ARXML consumers |
| --strict-css | UI CSS warnings become errors |
| --emit cpp | split | Single file or per-source split (default split) |
| --emit-maps / --build-target / --framework | Source maps, target override, framework override |
create
Scaffolds a project: config file, tsconfig wired to the board module, a blink starter, and tests — installed and ready to build.
Example first
| Flag | Meaning |
|---|---|
| --target, -t / --board, -b | The board target, e.g. xiao_ble/nrf52840 |
| --framework, -f | Framework package (default: @typecad/framework-zephyr) |
| --probe, --flash <id> | Named probe method — stlink, jlink, dfu, uf2... |
| --port, -p / --baud | Serial defaults for the project |
| --no-starter / --no-install | Skip the blink starter / skip npm install |
| --outDir, -o | Where the project goes |