Docs/Toolchain/CLI Reference
CLI Reference
Every fid command, the few that only fidesc has, and the companion tools ark, scribe and veil.
~4 min read
On this page
Good to know:
fidis the compiler.fidesc, the earlier compiler in Rust, is frozen: it runs the test suite and has a few extra commands, marked below.
Build & run
| Command | What it does |
|---|---|
run <file.fd> [--trace] [--max-steps N] [--leaks] [--checked-alloc] | Interpret the program. --leaks reports memory never freed; --checked-alloc catches use after free |
emit <file.fd> -o <out> [--target <t>] | Native executable, written by fid itself (no assembler, linker or C compiler): Windows x64 by default, --target x86_64-linux|aarch64-linux|riscv64-linux for a static Linux executable |
ccompile <file.fd> -o <out> [--debug|--release] [--target <t>] | Through C: needs a C compiler ($CC, gcc, clang, zig cc, tcc or MSVC). -O2 by default, --debug for -O0; --target cross-compiles with zig cc |
build <file.fd> -o <out> | emit on Windows, ccompile elsewhere. --no-opt, --lto, --no-cache. --native (old PIR path) crashes |
test <file.fd> | Run every fn test_*() in the file, each in its own process, and time every fn bench_*(). The file has no main |
test | Run every test program in tests/bootstrap/ |
repl | Interactive REPL |
Embedded and capability flags
fid emit firmware.fd --bare -o firmware.bin # x86-64 Multiboot kernel, no stdlib (experimental; boots under QEMU)
fid emit kernel.fd --boot -o kernel.bin # the same, for a kernel entry point (experimental)
fid emit app.fd --checked-alloc -o app.exe # guard pages around every block (written, not run yet)
fid build app.fd --caps "IO,FS" -o app # leave out code that needs other capabilitiesOther backends (experimental)
| Command | What it does |
|---|---|
wasm <file.fd> -o <out.wasm> [--wat] | WebAssembly for WASI: modules validate and run; not every suite program passes yet |
gpu <file.fd> --target spirv|ptx [-o out] [--text] | GPU kernels: SPIR-V or NVIDIA PTX (output does not validate yet) |
compile <file.fd> -o <out.s> | x86-64 assembly text (old PIR path) |
codegen <file.fd> --target <arch> | Assembly for x86-64, ARM64 or RISC-V (old PIR path; the ARM64 and RISC-V text is wrong) |
codegen <file.fd> --elf|--macho|--coff <o> | Relocatable object files (old PIR path; ELF objects are malformed) |
fid build-x86 <file.fd> (an older x86 stack-machine backend) writes an executable that crashes; use fid emit --target x86_64-linux. fidesc build --target x86-64|arm64-linux|riscv64-linux (frozen) writes Linux executables directly; its ARM64 and RISC-V runtimes are stubs.
Developer tools
| Command | What it does |
|---|---|
check <file.fd> | Type, borrow and effect checks only, no code generation |
fmt <file.fd> | Format a source file |
lint <file.fd> [--perf] | Unused functions and imports, unwrap() outside tests; --perf adds loop-hazard warnings. Names from use imports are reported as undefined today |
explain <file.fd> [--alloc] [name] | Which run-time checks were removed or kept, and why; --alloc lists allocation sites |
audit <file.fd> [--stdlib] [--strict] | List every unsafe block the program reaches |
qualify <file.fd> [-o out.json] | Safety evidence as JSON: rules, their tests, the program’s annotations; always NOT_QUALIFIED |
verify <file.fd> | Check the IR (terminators, block and value references) |
bench <file.fd> [-n <count>] | Timing statistics (mean, median, stddev) |
profile <file.fd> | Per-function timing |
notebook <file.fd> [-o out.html] | /// blocks become markdown cells; code runs with its output inline |
lsp | Language Server over stdio |
parse-header <file.h> -o <out.fd> | Fid FFI bindings from a C header |
Only in fidesc (frozen): watch (rebuild and restart on save, Linux), debug, autopsy, replay, sbom, spdx, diagram, diff-test, link, --post-mortem, --opt-level. (fid watch is accepted but runs bench.)
Compiler introspection
| Command | What it does |
|---|---|
tokens / ast / ir <file.fd> | Token stream, AST, or SSA IR |
pir <file.fd> [1|2|3|all] [--opt] | Typed PIR at any level |
opt <file.fd> [passes] | Run the old PIR optimizer and print statistics (panics today) |
dump-tokens / dump-ast / dump-ir / dump-pir / dump-c | Dump any intermediate representation |
sourcemap <file.fd> | IR value to source line mapping |
version | Print the version. The main branch prints fid 0.8.0-unstable; the v0.8.0 installer’s binary prints fid 0.1.0 |
--borrowck=off|warn|on controls the borrow checker (default: on).
Companion tools
ark, scribe and veil are separate binaries, and fid ark, fid scribe, fid veil run them too:
| Tool | Role |
|---|---|
ark | Packages: init, add --path/--git [--branch/--tag], install, remove, list, lock, update; manifest ark.toml, lock file ark.lock |
scribe | Documentation from /// comments, as HTML or Markdown |
veil | Function, line and instruction coverage, as text or HTML |
ark init myproject
ark add mylib --git https://github.com/user/mylib
scribe src/ --output docs/
veil main.fd --format htmlGood to know: the
arkregistry (search,publish) is planned; path and git dependencies work today.
Typical workflow
fid run main.fd # iterate
fid check main.fd # fast type check
fid test tests.fd # run the tests
fid build main.fd -o app # ship