Skip to content

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 ​

CommandWhat 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.
lspRun the language server on stdio (what an editor launches).
skillPrint language guide for LLMs.
helpPrint this help (also --help, -h).
langThe 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 | updateReplace this milo binary with the newest release (deps: pkg update).

run ​

sh
milo run <file> [args]

Compile and run (no artifacts left behind).

FlagEffect
--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 ​

sh
milo build <file> [-o out]

Compile to executable.

hot ​

sh
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 ​

sh
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.

FlagEffect
--contractsInstead, 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.
--jsonMachine-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 ​

sh
milo check <file>

Type-check only, no codegen.

FlagEffect
--jsonMachine-readable diagnostics, each with its fix when one is mechanical.

fix ​

sh
milo fix <file>

Apply every machine-applicable fix the check reports (&mut markers, imports, @ sigils, unused unsafe), in every file it reaches.

harden ​

sh
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.

FlagEffect
--writeApply the rewrites in place.

emit-ast ​

sh
milo emit-ast <file>

Emit the parsed AST as JSON.

FlagEffect
--allInclude imported modules.
--spansKeep source spans.

emit-mlir ​

sh
milo emit-mlir <file>

Emit the milo dialect module before milo-opt (the source-faithful top layer).

FlagEffect
--allThe whole module: imported functions, glue, scaffold.
--from-checked <json>Skip the frontend, lower that emit-checked dump.

emit-checked ​

sh
milo emit-checked <file>

Emit the checked program (AST plus the checker's facts) as JSON.

interp ​

sh
milo interp <file>

Run the program in the reference interpreter (no codegen); exit 3 = unsupported, 4 = stuck.

FlagEffect
--liveReport live heap blocks at exit on stderr.

emit-ir ​

sh
milo emit-ir <file>

Emit LLVM IR.

emit-obj ​

sh
milo emit-obj <file>

Compile to object file (.o).

build-lib ​

sh
milo build-lib <files...>

Compile to static library (.a).

fmt ​

sh
milo fmt <file...>

Format source files (to stdout unless -w).

FlagEffect
-wWrite in place, printing each file that changed.

prove ​

sh
milo prove <file>

Prove contracts hold, via z3 (a runtime requirement: brew install z3 / apt install z3).

FlagEffect
--rteAlso prove no overflow, no out-of-bounds index, no division by zero.
--deadList branches and loop bodies the solver proves can never run (unknown is not reported).
--emit-smtPrint the SMT-LIB2 obligations instead of solving them.
--allInclude imported stdlib.
--jsonMachine-readable report.

safety ​

sh
milo safety <file> --safety=<level>
milo safety --list

Check safety profile compliance.

  • milo safety --list: List available safety profiles.
FlagEffect
--jsonMachine-readable violations.

verify ​

sh
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.

FlagEffect
--profile <level>The safety profile (milo safety --list); do178 profiles make the requirements matrix strict.
--jsonBinary: machine-readable findings.
--allBinary: list every finding (default: first 8 per check).

wcet ​

sh
milo wcet <file> [-o out]

Emit OTAWA flow facts (loop bounds) for WCET analysis.

FlagEffect
--cyclesA Cortex-M cycle bound from the linked ELF (bare-metal ARM --target only).

lsp ​

sh
milo lsp

Run the language server on stdio (what an editor launches).

skill ​

sh
milo skill

Print language guide for LLMs.

help ​

sh
milo help

Print this help (also --help, -h).

lang ​

sh
milo lang

The language's vocabulary as data: keywords, types, operators, builtins, warnings, attributes, commands.

FlagEffect
--jsonThe full payload, for tooling.

explain ​

sh
milo explain <name>

What one warning, @attribute or keyword means, with an example and how to silence it.

FlagEffect
--jsonThe raw entry.

trace ​

sh
milo trace <file>

A .milo entry: the requirements matrix (@req, milo prove verdicts, tests); any other file: list a record/replay trace's records.

FlagEffect
--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 ​

sh
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.

FlagEffect
--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.
--jsonThe surface or the changes as data.

evidence ​

sh
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.

FlagEffect
add <entry.milo> <REQ> --method <m> --result pass|failAttest 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 ​

sh
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.

FlagEffect
--strictFail 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.
--jsonThe trace as data.

api ​

sh
milo api <terms>

Search std signatures by name/doc.

FlagEffect
--module std/xDump one module's full API.
--markdownEmit reference docs.
--jsonEvery std symbol.

doc ​

sh
milo doc <file|dir>

Reference markdown from doc-comments.

FlagEffect
-o <dir>Write one .md per module.

upgrade ​

sh
milo upgrade
milo update

Replace this milo binary with the newest release (deps: pkg update).

FlagEffect
--checkReport the newest release, change nothing.
--nightlyInstall the rolling build of main.
--tag <vX.Y.Z>Install a specific release.

Package commands ​

CommandWhat 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 installSync 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 vendorCopy deps into ./vendor and rewrite to local paths.
pkg publishValidate, tag, push.
pkg tool install <pkg>Build and install a global executable (~/.local/bin).

init ​

sh
milo init
milo new <name>

Create milo.json here / scaffold a new project.

add ​

sh
milo pkg add <pkg>

Add a library dependency (milo.json + milo.lock).

FlagEffect
--devRecord it under devDeps.

remove ​

sh
milo pkg remove <pkg>

Drop a dependency and prune the lock.

install ​

sh
milo pkg install

Sync this project from milo.lock.

FlagEffect
--frozenFail if the lock is stale.

update ​

sh
milo pkg update [pkg]

Re-resolve dependency tags and rewrite the lock.

tree ​

sh
milo pkg tree
milo pkg why <pkg>

Dependency graph / who pulls a package in.

vendor ​

sh
milo pkg vendor

Copy deps into ./vendor and rewrite to local paths.

publish ​

sh
milo pkg publish

Validate, tag, push.

tool ​

sh
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.

OptionEffect
--releaseOptimize (-O3).
--debugNo optimization (-O0).
-gEmit 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).
--sanitizeLink with AddressSanitizer (requires clang).
--sanitize=threadLink with ThreadSanitizer instead (requires clang).
--static-depsStatic-link native deps (openssl/sqlite) for a portable binary.
--overflow-checksTrap on +/-/* overflow at any -O (on by default in every mode).
--no-overflow-checksWrap on +/-/* overflow at any -O (opt out of the default traps).
--contract-checksAssert loop invariants too at any -O (default: requires/ensures at every -O, loop invariants only at --debug).
--no-contract-checksDrop every contract assert at any -O.
--strip-panic-locationsBlank source paths out of runtime panic messages (-g still embeds them).
--noaliasEmit LLVM noalias on &mut parameters where no alias is reachable (the default).
--no-noaliasOmit LLVM noalias on &mut parameters (on by default; for ruling it out of a miscompile).
--hotBuild a hot-reload host: -O0, patchable functions, writes <out>.hot.json.
--fastQuick 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-allTreat 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).
--jsonMachine-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-holesList 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-entryOmit the C entry point, for a freestanding image with its own reset vector.
--emit-headerWith emit-obj, also write a C header for the exported symbols.
--versionPrint the compiler version and exit.
--helpPrint 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).