Command-line reference
Every milo subcommand, its arguments and the flags it reads.
This page is generated by scripts/gen-lang-docs.ts from the commands and cliOptions keys of milo lang --json, which are projected from the same table milo --help prints. A command or flag cannot appear in one and be missing from the other.
Compiler commands
| Command | What it does |
|---|---|
run <file> [args] | Compile and run (no artifacts left behind). |
build <file> [-o out] | Compile to executable. |
hot <file> [-- args] | Run and patch function bodies on every save. |
test [file|dir...] | Run tests (*_test.milo, recursive in a dir; cwd by default). |
check <file> | Type-check only, no codegen. |
fix <file> | Apply every machine-applicable fix the check reports (&mut markers, imports, @ sigils, unused unsafe), in every file it reaches. |
harden <file|dir> | Rewrite into stricter Milo (index loop to for-in, match to ?, isSome to if let, last-use clone to move); prints a diff. |
emit-ast <file> | Emit the parsed AST as JSON. |
emit-mlir <file> | Emit the milo dialect module before milo-opt (the source-faithful top layer). |
emit-checked <file> | Emit the checked program (AST plus the checker's facts) as JSON. |
interp <file> | Run the program in the reference interpreter (no codegen); exit 3 = unsupported, 4 = stuck. |
emit-ir <file> | Emit LLVM IR. |
emit-obj <file> | Compile to object file (.o). |
build-lib <files...> | Compile to static library (.a). |
fmt <file...> | Format source files (to stdout unless -w). |
prove <file> | Prove contracts hold, via z3 (a runtime requirement: brew install z3 / apt install z3). |
safety <file> --safety=<level> | Check safety profile compliance. |
verify --profile <level> <file.milo | binary> | Check against a safety profile: a .milo source gets the profile's rules, the strict requirements matrix and prove --rte; a built binary gets its pinned build record, no allocation, no call cycles and the runtime-symbol allowlist. |
wcet <file> [-o out] | Emit OTAWA flow facts (loop bounds) for WCET analysis. |
lsp | Run the language server on stdio (what an editor launches). |
skill | Print language guide for LLMs. |
help | Print this help (also --help, -h). |
lang | The language's vocabulary as data: keywords, types, operators, builtins, warnings, attributes, commands. |
explain <name> | What one warning, @attribute or keyword means, with an example and how to silence it. |
trace <file> | A .milo entry: the requirements matrix (@req, milo prove verdicts, tests); any other file: list a record/replay trace's records. |
spec [--diff <git-ref> | --packet <outdir>] <entry.milo> | The spec lock: print the intent surface (requirements, contract clauses, invariants); --diff <ref> classifies changes since a git ref and asks z3 whether a changed clause only strengthens; --packet <outdir> writes a clean-room packet for an independent test author. |
evidence add|run|list <entry.milo> [<REQ>] | Evidence records that satisfy a requirement's verification claims the tool cannot check (inspection, review, demonstration, a test outside the unit env); records are JSON files committed beside requirements.json, pinned to the requirement text and the implementing code. |
trace-object <binary> | Per function of a binary built with -g: address range -> source line -> @req, plus a MILO-O rule ID on bounds checks, overflow traps, contract checks and drops; the percentage of code that traces. |
api <terms> | Search std signatures by name/doc. |
doc <file|dir> | Reference markdown from doc-comments. |
upgrade | update | Replace this milo binary with the newest release (deps: pkg update). |
run
milo run <file> [args]Compile and run (no artifacts left behind).
| Flag | Effect |
|---|---|
--record <trace> | Record this run to <trace> so it can be replayed exactly, e.g. to debug a failure after the fact (also MILO_RECORD=<trace>). |
--replay <trace> | Replay a recorded run: identical to the original, even if its files, servers or clock have changed since (also MILO_REPLAY=<trace>). |
build
milo build <file> [-o out]Compile to executable.
hot
milo hot <file> [-- args]Run and patch function bodies on every save. A body-only edit is swapped into the running program; a layout, signature or global change restarts it.
test
milo test [file|dir...]Run tests (*_test.milo, recursive in a dir; cwd by default). A test is a top-level fn test*() with no parameters; each runs in its own process, so a trap fails only that test.
| Flag | Effect |
|---|---|
--contracts | Instead, test every fn's requires/ensures on drawn inputs (any .milo). |
-t <pattern> | Run only tests matching (substring or regex). |
--test-name-pattern <pattern> | Long form of -t. |
--json | Machine-readable results. |
--coverage <dir> | Build -O0 with gcov counters; every test process adds to the .gcda files under <dir> (read by milo trace --coverage). |
check
milo check <file>Type-check only, no codegen.
| Flag | Effect |
|---|---|
--json | Machine-readable diagnostics, each with its fix when one is mechanical. |
fix
milo fix <file>Apply every machine-applicable fix the check reports (&mut markers, imports, @ sigils, unused unsafe), in every file it reaches.
harden
milo harden <file|dir>Rewrite into stricter Milo (index loop to for-in, match to ?, isSome to if let, last-use clone to move); prints a diff. An edit is kept only if the result type-checks, milo interp output is unchanged, and a second run finds nothing.
| Flag | Effect |
|---|---|
--write | Apply the rewrites in place. |
emit-ast
milo emit-ast <file>Emit the parsed AST as JSON.
| Flag | Effect |
|---|---|
--all | Include imported modules. |
--spans | Keep source spans. |
emit-mlir
milo emit-mlir <file>Emit the milo dialect module before milo-opt (the source-faithful top layer).
| Flag | Effect |
|---|---|
--all | The whole module: imported functions, glue, scaffold. |
--from-checked <json> | Skip the frontend, lower that emit-checked dump. |
emit-checked
milo emit-checked <file>Emit the checked program (AST plus the checker's facts) as JSON.
interp
milo interp <file>Run the program in the reference interpreter (no codegen); exit 3 = unsupported, 4 = stuck.
| Flag | Effect |
|---|---|
--live | Report live heap blocks at exit on stderr. |
emit-ir
milo emit-ir <file>Emit LLVM IR.
emit-obj
milo emit-obj <file>Compile to object file (.o).
build-lib
milo build-lib <files...>Compile to static library (.a).
fmt
milo fmt <file...>Format source files (to stdout unless -w).
| Flag | Effect |
|---|---|
-w | Write in place, printing each file that changed. |
prove
milo prove <file>Prove contracts hold, via z3 (a runtime requirement: brew install z3 / apt install z3).
| Flag | Effect |
|---|---|
--rte | Also prove no overflow, no out-of-bounds index, no division by zero. |
--dead | List branches and loop bodies the solver proves can never run (unknown is not reported). |
--emit-smt | Print the SMT-LIB2 obligations instead of solving them. |
--all | Include imported stdlib. |
--json | Machine-readable report. |
safety
milo safety <file> --safety=<level>
milo safety --listCheck safety profile compliance.
milo safety --list: List available safety profiles.
| Flag | Effect |
|---|---|
--json | Machine-readable violations. |
verify
milo verify --profile <level> <file.milo
milo binary>Check against a safety profile: a .milo source gets the profile's rules, the strict requirements matrix and prove --rte; a built binary gets its pinned build record, no allocation, no call cycles and the runtime-symbol allowlist.
| Flag | Effect |
|---|---|
--profile <level> | The safety profile (milo safety --list); do178 profiles make the requirements matrix strict. |
--json | Binary: machine-readable findings. |
--all | Binary: list every finding (default: first 8 per check). |
wcet
milo wcet <file> [-o out]Emit OTAWA flow facts (loop bounds) for WCET analysis.
| Flag | Effect |
|---|---|
--cycles | A Cortex-M cycle bound from the linked ELF (bare-metal ARM --target only). |
lsp
milo lspRun the language server on stdio (what an editor launches).
skill
milo skillPrint language guide for LLMs.
help
milo helpPrint this help (also --help, -h).
lang
milo langThe language's vocabulary as data: keywords, types, operators, builtins, warnings, attributes, commands.
| Flag | Effect |
|---|---|
--json | The full payload, for tooling. |
explain
milo explain <name>What one warning, @attribute or keyword means, with an example and how to silence it.
| Flag | Effect |
|---|---|
--json | The raw entry. |
trace
milo trace <file>A .milo entry: the requirements matrix (@req, milo prove verdicts, tests); any other file: list a record/replay trace's records.
| Flag | Effect |
|---|---|
--strict | (.milo) fail on an untraced fn, a requirement with no implementation or test, an UNKNOWN or FAILED clause. |
--safety=<do178 profile> | (.milo) same as --strict. |
--baseline <file> | (.milo) gaps listed in <file> stay warnings under --strict; new gaps fail (write one with --write-baseline <file>). |
--spec-base <git-ref> | (.milo) with --strict: fail on any unsigned spec weakening since <ref> (see milo spec). |
--requirements <file> | (.milo) requirements.json elsewhere than next to the entry. |
--tests <file|dir> | (.milo) where the @req tests live (default: *_test.milo beside the entry). |
--json | (.milo) the matrix as data; (trace file) {version, total, records: [{seq, kind, arg, payloadLen, offset}]}. |
--kind <prefix> | Only records whose kind starts with <prefix> (net., sched.). |
--payload <seq> | Write one record's payload bytes to stdout. |
--coverage | (.milo) run the @req tests with line counters and report covered/total lines of each fn body; with --strict an uncovered line fails (statement coverage only; needs llvm-cov). |
--refinement | (.milo) z3 checks the requirements' own clauses, no fn bodies: each parent ensures clause against its descendants' clauses on the same fn (REFINED, NOT REFINED with a counterexample, UNKNOWN, NOT COMPARABLE), and each fn's contract for satisfiability; with --strict, NOT REFINED and UNSAT fail (baseline keys refinement:<id>:<hash>, unsat:<fn>). |
--object <binary> | (.milo) add the address ranges of a binary built with -g that implement each requirement. |
spec
milo spec [--diff <git-ref>
milo --packet <outdir>] <entry.milo>The spec lock: print the intent surface (requirements, contract clauses, invariants); --diff <ref> classifies changes since a git ref and asks z3 whether a changed clause only strengthens; --packet <outdir> writes a clean-room packet for an independent test author.
| Flag | Effect |
|---|---|
--packet <outdir> | Write requirements.json plus one stub .milo per source file (declarations and contracts verbatim, pub fn bodies replaced by a panic, private code and comments dropped); refuses a non-empty <outdir>. |
--diff <git-ref> | Compare with the spec at <ref>: additions and strengthenings are ok; removals, text changes, weakenings (with a z3 counterexample) and undecided changes need an entry in spec-signoff.json (id, hash, who, why); exit 1 if any is unsigned. |
--json | The surface or the changes as data. |
evidence
milo evidence add|run|list <entry.milo> [<REQ>]Evidence records that satisfy a requirement's verification claims the tool cannot check (inspection, review, demonstration, a test outside the unit env); records are JSON files committed beside requirements.json, pinned to the requirement text and the implementing code.
| Flag | Effect |
|---|---|
add <entry.milo> <REQ> --method <m> --result pass|fail | Attest a result by hand: the tool cannot check it (recorded as attested). |
run <entry.milo> <REQ> --method <m> -- <cmd> [args...] | Run the command, keep its output as an artifact, and set the result from its exit code (recorded as run); exits with the command's code. It captures what ran, not whether the command measures the right thing. |
list <entry.milo> | One line per record with its state (PASS, FAILED, STALE). |
--env <e> | The environment of the claim (load, hil, target, ...); matched exactly against the requirement's verification entry. |
--measured "<text>" | What was measured, shown in the trace (e.g. "p95 212 ms"). |
--artifact <path> | (add) a file that backs the claim; its sha256 is recorded and a change makes the record stale. |
--note "<text>" | Free text. |
trace-object
milo trace-object <binary>Per function of a binary built with -g: address range -> source line -> @req, plus a MILO-O rule ID on bounds checks, overflow traps, contract checks and drops; the percentage of code that traces.
| Flag | Effect |
|---|---|
--strict | Fail on object code with no source line and no rule (untraced object code). |
--safety=<do178 profile> | Same as --strict. |
--entry <file.milo> | The source, when the binary's DWARF does not name it. |
--fn <name> | List only this function (repeatable); the totals still cover the whole binary. |
--json | The trace as data. |
api
milo api <terms>Search std signatures by name/doc.
| Flag | Effect |
|---|---|
--module std/x | Dump one module's full API. |
--markdown | Emit reference docs. |
--json | Every std symbol. |
doc
milo doc <file|dir>Reference markdown from doc-comments.
| Flag | Effect |
|---|---|
-o <dir> | Write one .md per module. |
upgrade
milo upgrade
milo updateReplace this milo binary with the newest release (deps: pkg update).
| Flag | Effect |
|---|---|
--check | Report the newest release, change nothing. |
--nightly | Install the rolling build of main. |
--tag <vX.Y.Z> | Install a specific release. |
Package commands
| Command | What it does |
|---|---|
init | new <name> | Create milo.json here / scaffold a new project. |
pkg add <pkg> | Add a library dependency (milo.json + milo.lock). |
pkg remove <pkg> | Drop a dependency and prune the lock. |
pkg install | Sync this project from milo.lock. |
pkg update [pkg] | Re-resolve dependency tags and rewrite the lock. |
pkg tree | pkg why <pkg> | Dependency graph / who pulls a package in. |
pkg vendor | Copy deps into ./vendor and rewrite to local paths. |
pkg publish | Validate, tag, push. |
pkg tool install <pkg> | Build and install a global executable (~/.local/bin). |
init
milo init
milo new <name>Create milo.json here / scaffold a new project.
add
milo pkg add <pkg>Add a library dependency (milo.json + milo.lock).
| Flag | Effect |
|---|---|
--dev | Record it under devDeps. |
remove
milo pkg remove <pkg>Drop a dependency and prune the lock.
install
milo pkg installSync this project from milo.lock.
| Flag | Effect |
|---|---|
--frozen | Fail if the lock is stale. |
update
milo pkg update [pkg]Re-resolve dependency tags and rewrite the lock.
tree
milo pkg tree
milo pkg why <pkg>Dependency graph / who pulls a package in.
vendor
milo pkg vendorCopy deps into ./vendor and rewrite to local paths.
publish
milo pkg publishValidate, tag, push.
tool
milo pkg tool install <pkg>
milo pkg tool uninstall <name>
milo pkg tool list [--repair]
milo pkg tool run <pkg> [args]Build and install a global executable (~/.local/bin).
milo pkg tool uninstall <name>: Remove an installed executable.milo pkg tool list [--repair]: List installed executables (--repair: rebuild the index).milo pkg tool run <pkg> [args]: Build and run a package's binary without installing.
Options
Parsed by every command that takes a source file. Each acts on the ones that apply to it: an optimization level matters to build and run, not to check.
| Option | Effect |
|---|---|
--release | Optimize (-O3). |
--debug | No optimization (-O0). |
-g | Emit DWARF line info (source-level lldb/hades); composes with any -O / --debug. |
-O<level> | Clang opt level: 0,1,2,3,s,z (default: -O2). |
--sanitize | Link with AddressSanitizer (requires clang). |
--sanitize=thread | Link with ThreadSanitizer instead (requires clang). |
--static-deps | Static-link native deps (openssl/sqlite) for a portable binary. |
--overflow-checks | Trap on +/-/* overflow at any -O (on by default in every mode). |
--no-overflow-checks | Wrap on +/-/* overflow at any -O (opt out of the default traps). |
--contract-checks | Assert loop invariants too at any -O (default: requires/ensures at every -O, loop invariants only at --debug). |
--no-contract-checks | Drop every contract assert at any -O. |
--strip-panic-locations | Blank source paths out of runtime panic messages (-g still embeds them). |
--noalias | Emit LLVM noalias on &mut parameters where no alias is reachable (the default). |
--no-noalias | Omit LLVM noalias on &mut parameters (on by default; for ruling it out of a miscompile). |
--hot | Build a hot-reload host: -O0, patchable functions, writes <out>.hot.json. |
--fast | Quick edit-loop build: -O0, wrapping, no contract asserts (~2x faster compile). |
--cgus=<n> | Codegen units compiled in parallel (default: auto, 1 for --release/-g). |
--deny=<warning> | Treat warning as error (e.g. --deny=unused-variable). |
--allow=<warning> | Suppress warning (e.g. --allow=unused-result). |
--expect=<warning> | Suppress it, and report if it stops occurring (e.g. --expect=index-clone). |
--deny-all | Treat all warnings as errors (off-by-default warnings: large-stack-array, mut-param-bundle, opaque-call-on-thread, replay-hole, single-variant-match, unused-import, unowned-pointer-copy, unchecked-ffi-contract, unused-move, unverified-extern). |
--json | Machine-readable output, for tooling instead of a human (api, lang, explain, check, prove, safety, test; see docs/json-api.md). |
--safety=<level> | Enforce safety profile (e.g. --safety=do178). |
--target=<name> | Cross-compile target (e.g. cortex-m3). |
--heap-size=<N> | Bare-metal heap cap in bytes or k/m (e.g. 64k); default: all free RAM. |
--replay-holes | List every extern call record/replay cannot capture (warning replay-hole). |
--max-stack-array=<N> | Large-stack-array warning threshold, bytes or k/m (default: 512k). |
--no-entry | Omit the C entry point, for a freestanding image with its own reset vector. |
--emit-header | With emit-obj, also write a C header for the exported symbols. |
--version | Print the compiler version and exit. |
--help | Print this help and exit (also -h). |
Also accepted, but left out of milo --help: milo pkg <verb> (its verbs are listed one per row in the package section), milo lex <file> (compiler-debug output, not a user-facing command).