CLI Reference
vynec commands and flags, project discovery, ESP32/Arduino hardware configuration and upload, and benchmark reports.
Execution modes
| Flag | Effect |
|---|---|
| (none) | Compile and run |
--run | Compile and run |
--ast | Interpret directly; no C emitted |
--verify | Hash-check source, then interpret |
--compile | Emit C and compile a binary; stop |
--emit-c | Write .vy.c; do not invoke the host compiler |
--emit-asm | Write .vy.s via the host compiler |
Output and codegen
| Flag | Effect |
|---|---|
-o <name> / --out <name> | Set the output binary name |
--native | Add -march=native to the host compile |
--c-profile <name> | Generated C: release (default), diagnostic, or sanitize |
--sanitizers <list> | With sanitize: address, undefined, or both (default) |
--blas | Lower matched matrix calls to BLAS (desktop only) |
--no-scratch-bounds | Elide generated scratch bounds checks |
--quiet | Suppress notes and warnings |
--strict | Enable strict type checking |
-h, --help | Show help |
-V, --version | Show version |
Generated-C build profiles
Profiles select downstream host compiler flags independently of how vynec itself was built. Both --c-profile diagnostic and --c-profile=diagnostic forms are accepted.
| Profile | Flags |
|---|---|
release | -O3 -w, preserving the existing portable default |
diagnostic | -O2 -g -Wall -Wextra -Wformat=2 |
sanitize | -O1 -g -Wall -Wextra -Wformat=2 -fsanitize=address,undefined -fno-sanitize-recover=all -fno-omit-frame-pointer |
Diagnostic and sanitize profiles support desktop compile/run/assembly, including the build/run project commands. They reject interpreter-only, emit-C-only, and firmware modes. bench rejects profile overrides. Windows GCC supports diagnostic builds and explicitly rejects sanitizer requests; supported POSIX host toolchains provide the sanitizer compiler/linker runtimes.
--sanitizers address, --sanitizers undefined, and --sanitizers address,undefined select address checks, undefined-behavior checks, or both. Both is the default; undefined,address is equivalent. Detector selection requires the sanitize profile. Unknown/missing values and unsupported combinations return 2, not an apparently successful uninstrumented build.
These flags instrument the generated executable, not the interpreter or the C++ compiler. Profiles do not alter region policies, floating-point defaults, or enable --no-scratch-bounds. Debug data and instrumentation have explicit costs; use release for performance comparisons. Arena poison/reuse regressions remain necessary because sanitizers cannot detect every stale reference within a mapped arena block.
Arduino
| Flag | Effect |
|---|---|
--arduino <board> | Target Arduino; currently uno |
--arduino-flash / --flash | Upload the built .hex with arduino-cli |
--monitor | Open arduino-cli monitor after flashing |
--port <device> / --device-port <device> | Serial port, for example COM3 |
--baud <rate> | Monitor baud rate; default 115200 |
--fqbn <string> | Override the board identifier |
--arduino uno alone produces .elf and .hex. --flash and --monitor are post-build actions.
ESP32
| Flag | Effect |
|---|---|
--esp32 <board> | Target esp32, esp32s2, esp32s3, esp32c3, or esp32c6 |
--esp32-flash | Upload the generated firmware with arduino-cli |
--esp32-monitor | Open the serial monitor after building/uploading |
--esp32-port <device> | ESP32 upload/monitor port |
--esp32-baud <rate> | ESP32 monitor baud; default 115200 |
--esp32-build-property <key=value> | Repeatable Arduino CLI build-property override |
The project workflow below is the shorter path for initialized hardware. See ESP32 & Hardware for runtime and peripheral details.
Projects
Embedded projects load hardware.toml automatically. vynec build compiles without uploading; vynec run compiles, uploads, resets and starts the board. Monitoring is opt-in with --monitor. Generated firmware and sketches live under build/firmware/.
| Hardware option | Effect |
|---|---|
--preset <name> | Override the bundled preset (hw950, esp32, esp32s2, esp32s3, esp32c3, esp32c6) |
--hardware-set section.key=value | Repeatable typed TOML override, e.g. display.rotation=1 |
--port <device> | Override configured upload/monitor port for either board family |
--baud <rate> | Override configured serial baud |
hardware show and hardware setup also accept --preset and --hardware-set. Configuration precedence is CLI → TOML → preset defaults. vynec init --kind embedded --preset hw950 --port COM5 --name demo creates a project ready for the short workflow after vynec hardware setup.
For orientation, esp32.display_init() uses the resolved configuration; esp32.display_init(0..3) overrides it explicitly in source. Changed hardware options cause a clean Arduino object rebuild so a subsequent run uploads the new configuration instead of stale cached firmware.
The HW-950 starter runs touch polling continuously. It reports geometry, touch-driver/calibration status, contact coordinates and arena heartbeats. Send C through the monitor to explicitly start four-corner calibration.
Without a path, the driver walks up from the current directory until it finds project.toml, then uses src/main.vy, then main.vy. Project configuration is applied before explicit CLI flags, so flags still win.
See Projects & Tooling for the manifest schema and templates.
Benchmark
| Flag | Effect |
|---|---|
--warmup <n> | Warm-up runs before measuring |
--iterations <n> | Measured runs |
--report <path> | Override the JSON report path |
Project benchmarks use [bench] from project.toml. Board targets are skipped. Single-file mode writes <stem>_bench.json next to the source unless --report is given.
Init
| Flag | Effect |
|---|---|
--name <name> | Project name; suppresses the TUI |
--kind <kind> | blank, ml, embedded, scientific, sr, mixed |
--targets <list> | desktop, arduino-uno, esp32, esp32s2, esp32s3, esp32c3, esp32c6, hw950, coral, jetson |
--board <name> | Embedded board alias; must match a selected preset |
--preset <name> | Bundled embedded configuration, e.g. hw950 |
--port <device> / --baud <rate> | Save connection settings in hardware.toml |
--libraries <list> | Comma-separated library names |
--cuda yes|no | Write [device.cuda] |
--license <id> | AGPL-3.0-only, MIT, proprietary |
--yes | Accept defaults |
--no-tui | Force non-interactive |
--no-git | Skip git init and the initial commit |
Exit codes: 0 success, 1 cancel, 2 non-interactive without a name or a terminal smaller than 80×24, 3 project.toml already exists, 4 generation or configuration error.
Exit codes
| Code | Meaning |
|---|---|
0 | Success |
1 | Compilation failure; also used by normal runtime error checks |
2 | C-profile option misuse or unsupported profile/mode combination |
Compile-and-run forwards the generated program's termination status, including nonzero explicit exits. POSIX signal termination is represented as 128 + signal. Init has its separate status contract documented above.
Diagnostics go to stderr. Color is enabled only when stdout is a terminal and NO_COLOR is unset.