CLI Reference

Generated by make docs-cli from the dispatch table in cmd/ailang/commands.go. Do not edit this page; edit the Command row and regenerate. make check-cli-docs fails if the page and the table disagree.

Finding a command

ailang --help              # the visible top level, one screen
ailang <group> --help      # everything filed in a group (dev, ops, eval)
ailang help <command>      # one command's own help
ailang <command> --help    # the same thing, spelled the other way

--help exits 0 at every level and runs nothing. An unknown command prints one line and a suggestion on stderr and exits 1 — it does not dump the command list into your pipe.

Output conventions

Question	Flag	Notes
Machine-readable output	--json	The one output-format flag. ailang test --json, not --format json.
Which model	--model	ailang eval-suite --models is accepted as an alias of the same target.
Where output goes	--output	Six of the eight sites. ailang compile --out and ailang eval-publish --output-dir are not converged yet.
Gate a mutation	--dry-run	Audited at all 14 sites: the default acts, and --dry-run is the opt-out everywhere. No command inverts it.

Superseded spellings keep working — ailang test --format json still means --json — because the fleet and fifteen frozen teaching prompts call them. They are not the spelling to learn. Two commands keep a --format of their own for a reason that is not output format: ailang check --format agent selects a third rendering (and ailang ai-check is ailang check --verify --format agent), and ailang exec --stream-json is an NDJSON event stream, which is not what --json means there.

Two commands parse --format by hand rather than registering it, so they do not accept --json and were invisible to the flag audit that converged the rest: ailang eval-report --format=markdown|html|docusaurus|json|csv and ailang doctor managed_agents --format=json. Both need the = form. Converging them is a follow-up, not a documentation problem.

Groups are a drawer, not a rename

ailang messages list and ailang ops messages list are the same route. A group exists so ailang --help fits on one screen; every grouped command keeps its own top-level spelling, and no script, skill or launchd driver has to change.

Commands

The visible top level: what ailang --help lists.

Command	Also accepted	What it does
ailang check	ailang ai-check	Type-check a file or directory (--verify adds contract verification)
ailang docs	—	Show stdlib module documentation (--list to enumerate)
ailang eval	—	Benchmarks: run one, or a subcommand (suite, report, elo, ...)
ailang examples	—	Search and explore working code examples
ailang fmt	—	Format AILANG source (stdout / --write / --check)
ailang help	—	Show help for ailang, a group or a command
ailang iface	—	Print the normalized JSON interface of a module
ailang init	—	Scaffold a new AILANG package or web app
ailang lsp	—	Language Server Protocol server (for AI agents and IDEs)
ailang pkg	—	Package registry inspection and coordination
ailang prompt	—	Display the AILANG teaching prompt (for AI code generation)
ailang repl	—	Start the interactive REPL
ailang run	—	Run an AILANG program
ailang serve	ailang server	Start the Observatory dashboard server (default port 1957)
ailang test	—	Run tests (--package for package mode)
ailang verify	—	Verify contracts and proof obligations
ailang version	—	Show version, commit hash and build time

ailang dev — Language-development and diagnostic commands

Reachable as ailang dev <command> and, unchanged, as ailang <command>.

Command	Top-level spelling	What it does
ailang dev agent-prompt	ailang agent-prompt	Display the AILANG agent prompt
ailang dev ast-edit	ailang ast-edit	Structural edit of an AILANG declaration
ailang dev axioms	ailang axioms	Design axiom compliance scorecard
ailang dev builtins	ailang builtins	Inspect the builtin registry
ailang dev cache	ailang cache, ailang brain	Project brain / semantic cache operations
ailang dev compile	ailang compile	Compile AILANG to Go (emit-go)
ailang dev debug	ailang debug	Debug AST and type information
ailang dev devtools-prompt	ailang devtools-prompt	Display the AILANG dev tools reference (for AI agents)
ailang dev disasm	ailang disasm	Disassemble compiled AILANG
ailang dev doctor	ailang doctor	Environment diagnostics (builtins, memory, managed_agents, ...)
ailang dev editor	ailang editor	Install editor syntax highlighting (vscode, vim, neovim)
ailang dev export-training	ailang export-training	Export traces as AI training data
ailang dev generate-extension-registry	ailang generate-extension-registry	Emit the static extension dispatch file from [extensions]
ailang dev micro-rag	ailang micro-rag, ailang microrag, ailang urag	Micro-RAG index and retrieval operations
ailang dev pi	ailang pi	Manage pi extensions (install, uninstall, status)
ailang dev policy-check	ailang policy-check	Evaluate a policy program against its cases
ailang dev replay	ailang replay	Replay and verify against a recorded trace
ailang dev sandbox-check	ailang sandbox-check	Diagnose FS sandbox path resolution (AILANG_FS_SANDBOX)
ailang dev select-best	ailang select-best	Pick the best candidate from generated variants
ailang dev watch	ailang watch	Watch a file for changes and re-run it

ailang ops — Fleet operations: messages, coordinator, mission, chains, models

Reachable as ailang ops <command> and, unchanged, as ailang <command>.

Command	Top-level spelling	What it does
ailang ops access-control	ailang access-control	Access control management
ailang ops budget	ailang budget	Budget monitoring
ailang ops chains	ailang chains	Execution chains, traces, observatory and dashboard queries
ailang ops coordinator	ailang coordinator	Manage the autonomous agent daemon
ailang ops daemon	ailang daemon	Local ailang daemon: run, install, uninstall, status
ailang ops design-quorum	ailang design-quorum	N-reviewer design quorum, reject-by-default
ailang ops design-review	ailang design-review	AI review of a design document
ailang ops exec	ailang exec	Unified AI execution for programmatic use
ailang ops mcp	ailang mcp	Model Context Protocol server operations
ailang ops messages	ailang messages, ailang msg	Agent message plane: list, send, read, ack
ailang ops mission	ailang mission	Mission registry, iteration, role dispatch and reports
ailang ops models	ailang models	Model registry: role, source, publish
ailang ops serve-api	ailang serve-api	Serve AILANG exports as REST endpoints
ailang ops storage	ailang storage	Storage plane status (which backend each store resolved to)
ailang ops workspaces	ailang workspaces	Workspace management

ailang eval — Benchmarks and eval analysis

Reachable as ailang eval <command> and, unchanged, as ailang <command>.

Command	Top-level spelling	What it does
ailang eval analyze	ailang eval-analyze	Analyze eval results and generate design docs
ailang eval browser-profile	ailang browser-profile	Manage persistent authenticated browser identities
ailang eval censored-pairs	ailang eval-censored-pairs	Censored fmt pairs with treatment/order integrity gates
ailang eval compare	ailang eval-compare	Compare two eval runs
ailang eval elo	ailang eval-elo	Per-language (AILANG vs Python) ELO leaderboard and benchmark difficulty
ailang eval matrix	ailang eval-matrix	Performance matrix with statistics
ailang eval paired	ailang eval-paired	Paired A/B comparison + McNemar (not aggregate rates)
ailang eval publish	ailang eval-publish	Per-release Docusaurus publication of eval results
ailang eval report	ailang eval-report	Generate a comprehensive eval report
ailang eval run	ailang eval	Run one benchmark (the bare ailang eval form)
ailang eval suite	ailang eval-suite	Run the full benchmark suite (parallel)
ailang eval summary	ailang eval-summary	Summarize eval results
ailang eval sweet-spot	ailang eval-sweet-spot	Cost-vs-time-vs-success sweet-spot ranking
ailang eval trend	ailang eval-trend	Failure-feedback candidate triage across eval history

Compatibility spellings

Routes the binary still accepts but no longer lists. They exist so an existing caller keeps working; new code should use the canonical spelling.

Route	Use instead	What it does
ailang add	ailang pkg add	Add a dependency (--path, --git or --registry)
ailang bin	ailang pkg bin	List or uninstall the [bin] command shims (list, uninstall <name>)
ailang dashboard	ailang chains dashboard	Dashboard operations for task visualization
ailang eval-chains	ailang chains eval	Link eval runs to their execution chains
ailang install	ailang pkg install	Install a package (omit the version for latest); [bin] commands go on PATH
ailang internal-dump-iface, ailang dump-iface	—	Dump a package's canonical interface JSON (internal)
ailang lock	ailang pkg lock	Resolve dependencies and write the lockfile
ailang observatory	ailang chains observatory	Observatory analytics
ailang pkg-docs	ailang pkg docs	Display a package's AGENT.md (AI usage guide)
ailang publish	ailang pkg publish	Publish the current package to the registry
ailang search	ailang pkg search	Search the registry by keyword or tag
ailang trace	ailang chains trace	Distributed trace management
ailang tree	ailang pkg tree	Show the dependency tree
ailang unpublish	ailang pkg unpublish	Remove a package version from the registry

Documentation search

ailang docs search "query" searches the local design_docs/ or docs/ corpus first, and falls back to GitHub code search when run outside a source checkout. The fallback requires authentication — GITHUB_TOKEN or gh auth login; unauthenticated search is not attempted. --path <dir> forces a local corpus and --no-github (or AILANG_NO_GITHUB_SEARCH) disables the fallback. GitHub results are cached per query for one hour under ~/.ailang/cache/docsearch/github/; a cache entry holds results and metadata only, never tokens.

Startup contract

Language commands — the ones you run to work with AILANG rather than to operate the fleet — open no observatory database and run no git probe at startup. This is a contract with a test behind it (cmd/ailang/commands_probe_test.go counts the probes), not a presentation choice, and it holds for a command's group spelling too: ailang dev builtins is as quiet as ailang builtins.

The language commands are ast-edit, builtins, check, compile, debug, devtools-prompt, disasm, docs, examples, export-training, fmt, help, iface, init, lsp, prompt, repl, replay, run, select-best, test, verify, version, watch.