Reference

CLI Reference

vynec commands and flags, project discovery, ESP32/Arduino hardware configuration and upload, and benchmark reports.

 text snippettext
vynec <script.vy> [flags] compile and run vynec <mode> <script.vy> [flags] explicit mode vynec build [path] build the current project vynec run [path] build and run the project vynec bench [file] benchmark project targets vynec init [path] scaffold a new project vynec hardware list list bundled board/preset labels vynec hardware show print resolved hardware as TOML vynec hardware setup install the selected core/libraries

Execution modes

FlagEffect
(none)Compile and run
--runCompile and run
--astInterpret directly; no C emitted
--verifyHash-check source, then interpret
--compileEmit C and compile a binary; stop
--emit-cWrite .vy.c; do not invoke the host compiler
--emit-asmWrite .vy.s via the host compiler
 shell snippetshell
vynec --ast script.vy vynec --compile script.vy vynec --emit-c script.vy vynec --emit-asm --native script.vy

Output and codegen

FlagEffect
-o <name> / --out <name>Set the output binary name
--nativeAdd -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)
--blasLower matched matrix calls to BLAS (desktop only)
--no-scratch-boundsElide generated scratch bounds checks
--quietSuppress notes and warnings
--strictEnable strict type checking
-h, --helpShow help
-V, --versionShow 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.

ProfileFlags
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
 shell snippetshell
vynec --run --c-profile diagnostic script.vy vynec --run --c-profile sanitize script.vy vynec --compile --c-profile sanitize --sanitizers address script.vy vynec --emit-asm --c-profile diagnostic script.vy

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

FlagEffect
--arduino <board>Target Arduino; currently uno
--arduino-flash / --flashUpload the built .hex with arduino-cli
--monitorOpen 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
 shell snippetshell
vynec --arduino uno sketch.vy vynec --arduino uno --flash --monitor --port COM3 sketch.vy

--arduino uno alone produces .elf and .hex. --flash and --monitor are post-build actions.

ESP32

FlagEffect
--esp32 <board>Target esp32, esp32s2, esp32s3, esp32c3, or esp32c6
--esp32-flashUpload the generated firmware with arduino-cli
--esp32-monitorOpen 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
 shell snippetshell
vynec --esp32 esp32 --esp32-flash --esp32-port COM3 examples/test/esp32_hello.vy vynec --preset hw950 --esp32-flash --esp32-port COM5 examples/test/esp32_touch.vy

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 optionEffect
--preset <name>Override the bundled preset (hw950, esp32, esp32s2, esp32s3, esp32c3, esp32c6)
--hardware-set section.key=valueRepeatable 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.

 shell snippetshell
vynec build vynec run vynec build examples/projects/srcnn vynec run examples/projects/srcnn

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

 shell snippetshell
vynec bench vynec bench src/main.vy --warmup 5 --iterations 200 vynec bench --report build/bench.json
FlagEffect
--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

 shell snippetshell
vynec init vynec init --name demo --kind ml --no-git vynec init --help
FlagEffect
--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|noWrite [device.cuda]
--license <id>AGPL-3.0-only, MIT, proprietary
--yesAccept defaults
--no-tuiForce non-interactive
--no-gitSkip 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

CodeMeaning
0Success
1Compilation failure; also used by normal runtime error checks
2C-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.

Examples

 shell snippetshell
vynec examples/hello.vy vynec --compile -o ml examples/training/ml_seq.vy vynec --blas --native -o matmul_blas examples/benchmark/matmul_1024_vlin.vy vynec --emit-asm --native examples/benchmark/matmul_1024.vy vynec --arduino uno --flash --port COM3 examples/arduino/blink.vy

See also