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.
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.
emit-ast <file>	Emit the parsed AST as JSON.
emit-hir <file>	Emit the typed HIR as JSON.
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 std/smt, the milo-native prover.
safety <file> --safety=<level>	Check safety profile compliance.
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.
api <terms>	Search std signatures by name/doc.
doc <file|dir>	Reference markdown from doc-comments.

run

milo run <file> [args]

Compile and run (no artifacts left behind).

build

milo build <file> [-o out]

Compile to executable.

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.

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.

emit-ast

milo emit-ast <file>

Emit the parsed AST as JSON.

Flag	Effect
--all	Include imported modules.
--spans	Keep source spans.

emit-hir

milo emit-hir <file>

Emit the typed HIR as JSON.

Flag	Effect
--all	The full module, imports included.
--spans	Keep source spans.

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 std/smt, the milo-native prover.

Flag	Effect
--solver=z3	Use z3 instead (adds non-linear arithmetic).
--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 --list

Check safety profile compliance.

• milo safety --list: List available safety profiles.

Flag	Effect
--json	Machine-readable violations.

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 lsp

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

skill

milo skill

Print language guide for LLMs.

help

milo help

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

lang

milo lang

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

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.

Package commands

Command	What it does
init | new <name>	Create milo.json here / scaffold a new project.
add <pkg>	Add a library dependency (milo.json + milo.lock).
remove <pkg>	Drop a dependency and prune the lock.
install	Sync this project from milo.lock.
update [pkg]	Re-resolve tags and rewrite the lock.
tree | why <pkg>	Dependency graph / who pulls a package in.
vendor	Copy deps into ./vendor and rewrite to local paths.
publish	Validate, tag, push.
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 add <pkg>

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

Flag	Effect
--dev	Record it under devDeps.

remove

milo remove <pkg>

Drop a dependency and prune the lock.

install

milo install

Sync this project from milo.lock.

Flag	Effect
--frozen	Fail if the lock is stale.

update

milo update [pkg]

Re-resolve tags and rewrite the lock.

tree

milo tree
milo why <pkg>

Dependency graph / who pulls a package in.

vendor

milo vendor

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

publish

milo publish

Validate, tag, push.

tool

milo tool install <pkg>
milo tool uninstall <name>
milo tool list [--repair]
milo tool run <pkg> [args]

Build and install a global executable (~/.local/bin).

• milo tool uninstall <name>: Remove an installed executable.
• milo tool list [--repair]: List installed executables (--repair: rebuild the index).
• milo 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).
--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 requires/ensures/invariant at any -O (default: only --debug).
--no-contract-checks	Drop those asserts at any -O (e.g. fast -O0 builds).
--strip-panic-locations	Blank source paths out of runtime panic messages (-g still embeds them).
--fast	Quick edit-loop build: -O0, wrapping (~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, 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.
--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 lex <file> (compiler-debug output, not a user-facing command).