docs / cli
Command-line interface
The fx binary in bin/ is the compiler and driver for the language package (0.9.74).
Everyday commands
| Command | Purpose |
|---|---|
fx doctor | Check C compiler + zspec paths |
fx version | Print version (expect v0.9.74) |
fx help | Show help |
fx new <name> | Create a project from a scaffold |
fx check <file.fx> | Parse and typecheck (--guest for guest ambient-io policy) |
fx run <file.fx> | Auto driver; IR → native when available; link and run |
fx build <file.fx> | Same backends as run (link; do not run) |
fx emit-c <file.fx> -o <dir> | Emit .c / .h only |
fx surface <file.fx> | Static module passport (JSON + Markdown) |
fx test / fx fuzz | Discover *_test.fx / property driver |
fx doctor
Reports whether gcc, clang, and/or zig are on your PATH,
and whether zspec headers/libraries can be found by walking up from the current directory.
Exit code 0 if at least one C compiler is found.
fx new
fx new hello
fx new tiny --scaffold minimal
fx new firmware --scaffold embedded
fx new mytool --scaffold cli
fx new mytool --scaffold tool # alias for cli
fx new guestapp --scaffold guest| Scaffold | Intent |
|---|---|
simple (default) | Named region + import std/vec; stages std/ |
minimal | Bare main returning 42 |
embedded | Tiny arena footprint; builtin vec_*; no staged std/ |
cli / tool | Result library; build with --cli (autohost argv) |
guest | Capability / guest ambient-io posture |
fx run / fx build
fx run main.fx # Auto: the primary compiler path when supported, else built-in fallback
fx run main.fx --emit-c # emit-C → native
fx run main.fx --driver foundry
fx run main.fx --driver sh # strict live lane (no fallback)
fx run lib.fx --cli # auto-link cli host (argv)
fx run lib.fx --host host.c
fx run main.fx --release
fx build main.fx -o out
Default driver is Auto: try the primary compiler path for supported programs; otherwise the
built-in engine inside bin/fx.
On that path, lowering defaults to IR → native when QBE is staged.
Pass --emit-c for readable C. Emit-C stays first-class.
Strict live lane: --driver sh does not support
--cli / --host — use Auto or --driver foundry for those.
Windows vs Linux IR: Linux discovers third_party/qbe/obj/qbe.
Windows discovers third_party/qbe/windows/qbe.exe when present (native PE).
Without qbe.exe, use --emit-c.
| Flag | Meaning |
|---|---|
--emit-c | Use emit-C → native instead of IR → native |
--driver auto|sh|foundry | Parse/emit driver |
--fallback-emit-c | Emit-C fallback when IR path cannot serve |
--cli | Auto-link packaged cli host (argv) |
--host <file.c> | Use this C file as main |
--guest / --no-guest | Guest ambient-io policy |
-o <dir> | fx build/--watch default out/; fx run without -o uses scratch + FXCACHE |
--release | Optimize more; less debug instrumentation |
--watch | Debounced rebuild; kills prior child; reuses FXCACHE |
--use <dir> | Native lib unit (link.args) |
--link / link-args helpers | Extra linker inputs |
Default linking expects gcc and the zspec library that matches your OS
(build/gcc or build/gcc-linux).
fx run does not forward program argv — use --cli / --host / scaffold cli.
fx emit-c / fx surface
fx emit-c main.fx -o out_c
fx emit-c main.fx -o out_c --surface
fx surface main.fxAgent / editor helpers
| Command | Role |
|---|---|
fx lsp | Language server (stdio) |
fx mcp | Lean MCP (check / locate / run / surface / emit_c, …) |
fx locate --c-file <f.c> --line <n> | Map a C line back to fx via .fxmap |
fx bind | C header → extern "c" stubs |
fx mod vendor|tidy|verify | Offline vendor/std + fx.sum pin |
Exit codes
Application main return values become process exit codes when you fx run
(the simple scaffold returns 42). Tooling failures use non-zero codes.
fx doctor exits 1 when no C compiler is found.
Package detail: docs/CLI.md.