CLI Reference

The cuttlefish command-line tool transpiles TypeScript to C++, manages projects, and interfaces with hardware toolchains. Hardware tests use the separate cuttlefish-test binary (see Testing).

cuttlefish <input.ts> [options]

Transpile a TypeScript file to C++. Transpilation is always performed first.

cuttlefish src/main.ts --emit cpp --outDir out

cuttlefish build [options]

Build using the entry point from cuttlefish.config.ts.

cuttlefish build --compile --upload --port COM4

Build options chain in order: --compile → --upload → --monitor:

cuttlefish create [name] [options]

Create a new Cuttlefish project. Interactive on a terminal (it asks only what the flags didn’t set); piped/CI runs with a --target are non-interactive.

cuttlefish create my-project --target esp32s3_devkitc

cuttlefish board sync [zephyr-base] / cuttlefish board regen

The board catalog is generated from your Zephyr tree, and the project-local board module (.cuttlefish/board.ts + board.json) is generated from the catalog.

• board sync rebuilds the catalog from the tree — the refresh path after west update. It prints what changed (added/changed/removed board variants), then regenerates the current project’s board module so the sync lands immediately. Pass an explicit path to a different Zephyr checkout to sync from.
• board regen re-emits the project’s board module from the active catalog. The module also regenerates automatically on build whenever any input moves (the config’s board, the catalog, the Zephyr tree); this command refreshes it explicitly.

cuttlefish board sync
cuttlefish board regen

cuttlefish preview [--config <path>] [--port <port>]

Start a browser preview of the configured UI display. Uses cuttlefish.config.ts by default.

npx @typecad/ui --config

Interactive wizard that sets up a display. It asks which display you use and how it is wired, then writes the display section of cuttlefish.config.ts and a preview script into package.json. See Display Configuration.

cuttlefish doctor

Check the active framework’s environment — the framework configured in cuttlefish.config.ts provides the check; frameworks without doctor support say so.

cuttlefish doctor

• Zephyr verifies west is discoverable (PATH, ZEPHYR_BASE, a micromamba environment, or a well-known workspace), checks the Zephyr version against the supported range, and confirms the configured board target exists — suggesting west boards when it doesn’t.

Run this before --compile/--upload if a build fails with a missing-toolchain or missing-core error.

cuttlefish licenses [--all] [--strict]

Audit the licenses of the libraries this project depends on. The Zephyr framework scans the kernel and every west list manifest project. By default the scan is scoped to what the project actually links; --all widens it. Each dependency’s SPDX license is resolved and classified by copyleft risk.

cuttlefish licenses
cuttlefish licenses --all        # audit the whole west workspace
cuttlefish licenses --strict     # exit non-zero on unknown or strong-copyleft licenses

Output sorts worst-first: strong copyleft ([COPYLEFT]), weak copyleft ([weak copyleft]), permissive (✓), then unknown (UNKNOWN). A summary line reports the count of each. Dependencies whose license can’t be determined are listed in a warnings block with their location so you can inspect them.

cuttlefish library <search|install|init|validate>

The library package manager. npm keywords are the catalog — every library package carries the marker cuttlefish-library plus one category keyword, and search scans the npm registry with those terms. See Library Packages for the full picture.

cuttlefish library search                  # every published library (--json for machine output)
cuttlefish library search --category led   # one of the 12 categories
cuttlefish library search ws2812           # free text within libraries
cuttlefish library install <pkg...>        # npm install into the nearest project package.json
cuttlefish library init [name]             # scaffold a new library package (interactive)
cuttlefish library validate [path]         # validate a package: manifest, shims, keywords, AUTOSAR strict

init prompts for package name, framework, category, and board targets — every prompt has a flag override (--framework, --category, --targets, --dir, --yes). The scaffold passes validate as generated; exit code 1 with named errors when it doesn’t.

cuttlefish gen-decls <file.cpp|--all <dir>>

Generate TypeScript .d.ts declarations from C++ headers.

cuttlefish gen-decls src/sensor.h
cuttlefish gen-decls --all ./vendor/include

--all scans a directory for C++ files; without it the argument is a single .h/.cpp file. No declaration file is created when a header declares no classes or constants.

Common workflows

cuttlefish build --compile --build-target esp32s3_devkitc/esp32s3/procpu
cuttlefish build -w --compile --upload --port COM4
cuttlefish build --diagnostics
cuttlefish create my-esp32 --target esp32s3_devkitc

For hardware tests, use the dedicated cuttlefish-test binary — see Expect Assertion API.