CLI Reference
The star-lang command is the StarLang compiler and runtime.
Commands
run
Compile and execute a .star file. Always runs in debug mode (console.log enabled).
compile
Compile a .star file to .starbc bytecode. Always compiles in release mode (console.log stripped).
Output:
compile hello.star
emit hello.starbc
size 453 bytes (234 opcodes, 14 constants, 1 functions)
time 0.3 ms
embed
Compile a .star file into a self-contained C header for embedding the image directly into firmware (e.g. an ESP32 build). The header defines a single star_image[] byte array plus star_image_len; the VM's star_vm_load parses the constants, event types, and code straight out of it.
star-lang embed hello.star # → hello.star.image.h
star-lang embed hello.star star_image.h # explicit output path
star-lang embed hello.star --debug # keep console.log in the image
By default the image is compiled in release mode (console.log stripped). Pass --debug (or -g) to keep console.log output — useful for on-device bring-up.
Output:
VM-only targets
On RAM-constrained boards (classic ESP32) the compiler does not fit on-device, so the workflow is: compile on the host with embed, flash the image into firmware, and let the on-chip VM execute it. Updating a program means re-embedding and reflashing the image — the VM itself stays put.
deploy
Compile a .star file and stream the image to a device running the resident VM firmware over serial — no reflash per iteration. The device runs it and streams console.log output back.
star-lang deploy main.star # default port /dev/ttyUSB0
star-lang deploy main.star --port /dev/ttyUSB1
star-lang deploy main.star --release # strip console.log
Before sending, deploy asks the device which native modules its firmware registered and aborts if the image needs one the firmware lacks, naming the missing module — rather than failing later at image load:
error: device firmware is missing native module(s): mqtt
device provides: math, time, json, queue, crypto, wifi, config
flash a firmware that includes them: star-lang flash --port /dev/ttyUSB0
If a config <file> is declared in star.mod, that file is provisioned to the device first (the device has no filesystem); it persists across runs.
flash
Build the device runtime firmware and write it to the board over serial. flash reads the project's star.mod and embeds exactly the device libraries it requires (e.g. wifi, mqtt, ws) — a minimal image with no unused libs shipped. Afterwards new programs only need deploy, as long as they use libraries already in the firmware.
Adding a device library to star.mod that the firmware was not built with requires another flash; deploy checks this first and names the missing module rather than failing at image load.
Requires the ESP-IDF toolchain on PATH (source its export.sh first); flash errors out if idf.py is not found.
init
Create a new project with starter files.
Creates:
myproject/
star.mod — module definition & dependencies
main.star — entry point
.vscode/launch.json — debug configuration
The generated star.mod:
Add native module dependencies with require:
See the star.mod reference for details.
test
Run test files. Discovers and executes test_*.star files in a directory.
Run a single test file:
If no path is given, tests the current directory:
Output:
PASS test_arithmetic.star
PASS test_functions.star
PASS test_variables.star
3 passed, 0 failed, 3 total
update
Update star-lang and star-lsp to the latest version.
version
Show version and build date.
Output: star-lang 0.1.4 (May 28 2026)
Debug vs Release
| Command | Mode | console.log |
Use case |
|---|---|---|---|
run |
Debug | Included in bytecode | Development, testing |
compile |
Release | Stripped by compiler | Production, deployment |
run always compiles in debug mode — console.log calls are included in the bytecode. compile always produces release bytecode — console.log calls are stripped entirely with zero runtime cost.
Exit Codes
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Error (compile error, file not found, runtime error) |