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/sketch.ts --emit cpp --outDir out| Option | Description |
|---|---|
--emit <mode> | cpp (single file) or split (separate .cpp/.h). Default: split. |
--target <platform> | Target platform string (default: generic). |
--outDir, --out-dir <path> | Output directory (default: input file directory). |
--emit-maps <bool> | Emit source maps (true/false, default: true). |
cuttlefish build [options]
Build using the entry point from cuttlefish.config.ts.
cuttlefish build --compile --upload --port COM4Build options chain in order: --compile → --upload → --monitor:
| Option | Description |
|---|---|
--compile | Compile generated output via the framework toolchain. Requires a build target. |
--upload | Upload firmware to the board. Requires --compile and --port. |
--monitor | Open an interactive serial monitor after upload. Requires --port. |
--expect [file] | Run hardware tests via @typecad/expect (discover and validate over serial). For the full-featured runner, prefer cuttlefish-test. |
--build-target <id> | Framework-specific build target / FQBN (the board ID Arduino uses; e.g. arduino:avr:uno, esp32:esp32:esp32). |
--port <port> | Serial port (COM4, /dev/ttyACM0). |
--baud <rate> | Baud rate for --monitor (default: 9600). |
--framework <pkg> | Framework package override (e.g. @typecad/framework-arduino). |
--watch, -w | Watch for file changes and retranspile. Incompatible with --monitor. |
--diagnostics | Generate diagnostics.md and diagnostics.json (call graph, memory use, task analysis). |
⚙️ Advanced details — tree-shaking options
Tree-shaking (removing unused code) is on by default. These flags let you tune it.
| Option | Description |
|---|---|
--no-tree-shake | Disable dead-code elimination. |
--keep-unused-enums / --keep-unused-classes / --keep-unused-types / --keep-unused-variables | Retain specific unused symbols. |
--entry-point <name> | Add a custom entry-point symbol (repeatable). |
cuttlefish create [name] [options]
Create a new Cuttlefish project. Runs an interactive wizard if no --target is given.
cuttlefish create my-project --target arduino-uno| Option | Description |
|---|---|
--target, -t <id> | Target: native, arduino-uno, esp32-devkit, esp32s3. |
--board, -b <id> | Alias for --target. |
--framework, -f <pkg> | Framework: arduino, avr, native. |
--baud <rate> | Serial baud rate (default: 9600). |
--no-sketch | Skip generating the starter sketch. |
--outDir, -o <path> | Output directory (default: ./<name>). |
cuttlefish preview [--config <path>] [--port <port>]
Start a browser preview of the configured UI display. Uses cuttlefish.config.ts by default.
cuttlefish map-error <mapFile> [options]
Map a C++ error location back to TypeScript source.
cuttlefish map-error out/sketch.ino.thcppmap.json --line 42 --column 10 --message "error: 'foo' was not declared"| Option | Description |
|---|---|
--line, --cpp-line <n> | Required. C++ line number. |
--column, --cpp-column <n> | C++ column (default: 1). |
--cpp-file <path> | C++ file path. |
--message <text> | Error message. |
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/includecuttlefish gen-libdefs <input.ts>
Generate library definitions from a TypeScript file’s imports.
cuttlefish gen-libdefs src/sensor.tsCommon workflows
cuttlefish build --compile --board @typecad/board-arduino-uno
cuttlefish build -w --compile --upload --port COM4
cuttlefish build --diagnostics
cuttlefish create my-esp32 --target esp32-devkitFor hardware tests, use the dedicated cuttlefish-test binary — see Expect Assertion API.
On This Page