Skip to content

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: fid is 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

CommandWhat 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
testRun every test program in tests/bootstrap/
replInteractive 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 capabilities

Other backends (experimental)

CommandWhat 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

CommandWhat 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
lspLanguage 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

CommandWhat 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-cDump any intermediate representation
sourcemap <file.fd>IR value to source line mapping
versionPrint 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:

ToolRole
arkPackages: init, add --path/--git [--branch/--tag], install, remove, list, lock, update; manifest ark.toml, lock file ark.lock
scribeDocumentation from /// comments, as HTML or Markdown
veilFunction, 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 html

Good to know: the ark registry (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

Report an issue