Wado CLI

The wado CLI

wado <command> --help is the source of truth for flags and is thorough — it states the allocator modes and their per-world defaults, the optimization levels, every dump phase, and every query kind. Run it rather than guessing.

Inside the wado repository, wado means cargo run --bin wado --.

Commands

Usage: wado <command> [options]

Commands:
  init [options]                      Create a new wado.toml manifest
  update [options]                    Resolve dependencies and write wado.lock
  fetch [options]                     Download the project's registry dependencies
  clean [options]                     Evict derived cache state (git worktrees)
  build [options]                     Build the project's worlds from wado.toml
  compile [options] <file.wado>       Compile a single Wado source file
  check [options] [file.wado | dir]   Verify a source file and its Kiln generators
  run [options] [file.wado]           Compile and run a Wado CLI program
  serve [options] [file.wado]         Compile and serve a Wado HTTP service
  test [options] [files or dirs...]   Run tests in Wado source files
  format [options] <file.wado>...     Format a Wado source file
  doc [options] <file.wado>...        Generate documentation from source files
  dump [options] <file.wado>...       Dump compiler internal state
  wit [options] [file.wado | dir]     Emit the WIT contract for a Wado program
  syntax [options]                    Generate syntax definition files
  lsp [options]                       Start the language server (LSP over stdio)
  query <kind> [options] <file.wado>  Query language service information
  publish [options]                   Check whether the package can be published
  help [command]                      Show a command's help, builtin or external

Global options:
  --help     Show this help message
  --list     List every command, builtin and external
  --version  Show version information

build works from a wado.toml and writes build/<world>.wasm. compile takes exactly one source file; dump, doc, and format take several. check, run, serve, and wit fall back to the manifest when given no path.

External Commands

A name the list above does not hold is looked up as wado-<name> on PATH, so wado run-webgpu app.wado runs wado-run-webgpu app.wado. The child receives the rest of the command line unparsed and owns the exit status, and $WADO names the wado that invoked it. wado --list names every one it finds.

Only PATH is searched, and never an entry that is empty or relative. A builtin always wins, so a wado-run on PATH is never run; --list marks it.

Target World

A Wado program targets a Wasm world: the CLI command (wasi:cli/command, the default), the HTTP service (wasi:http/service, run via wado serve), or the synthetic test world (selected with --world test, used by E2E tests). Several defaults — including the allocator — depend on the target world.

--world <name> overrides it on compile, check, dump, and wit (check defaults to the library world instead — see Check). --world test exports the entry module's test blocks and drops everything else. run, serve, and test pick their world automatically. build --world <fq> is a different flag: it selects which of wado.toml's declared worlds to build.

wado compile --world test file.wado  # compile against the test world
wado check --world test file.wado    # type-check against the test world

Allocators

Three allocators are available via --allocator <mode>:

• bump (default for CLI): bump pointer; never frees. Fast, minimal code.
• freelist (default for the HTTP world): reclaims freed memory via a free list. For long-running processes.
• debug (default for the test world): never reuses freed memory; poisons freed memory with 0xFF. For use-after-free detection.

wado compile --allocator bump file.wado      # bump allocator
wado compile --allocator freelist file.wado  # free-list allocator
wado compile --allocator debug file.wado     # debug allocator

wado compile selects the debug allocator automatically when targeting the test world; E2E tests rely on this.

Compile

wado compile -o file.wasm file.wado    # generate Wasm
wado compile -o file.wat file.wado     # generate WAT
wado compile --wat-to-stdout file.wado # output WAT to stdout

Optimization levels: -O0 (none), -O1 (development), -O2 (production, default), -O3 (aggressive), -Os (-O2 + strip symbols).

To inspect invalid Wasm when debugging codegen bugs, skip validation:

# Output raw Wasm bytes even if invalid
wado compile --no-validate --wat-to-stdout file.wado

wado check verifies Wado sources without emitting Wasm. It runs their Kiln generators and resolves dependencies exactly as compile / run do, writing what the generators produce and fetching what the cache lacks.

With no file it checks every world wado.toml declares, exactly the targets wado build builds. Naming a directory checks that directory's project the same way, so a workspace member needs no cd. It runs at O0 since it throws the component away, so it reports everything a build would and skips the optimization loop, which is most of a large build's time.

Naming a file checks that file alone, against the world whose [world] entry names it and otherwise the library world, which requires no entry point. So a library module checks as itself; --world <name> opts into a world's contract.

Run

wado run file.wado  # run a CLI program with wasmtime

A program reaches only the directories granted to it: the current one, or exactly the --dir grants once any is given. Paths open relative to a grant, so an absolute path never opens — reach a file outside the tree by granting its directory and naming it relative to that.

wado run --dir /tmp/scratch prog.wado Foo.g4  # Foo.g4 resolves inside /tmp/scratch

Test

wado test discovers and runs test blocks (compiled against the test world, see Target World above).

wado test                           # discover and run every .wado test in the project
wado test file.wado                 # run tests in one file
wado test --filter '**/json*.wado'  # run tests in files matching a wildcard
wado test --profile guest file.wado # guest profile over that file's tests
wado test --coverage=lcov,json      # also report what ran, into build/coverage/

--coverage prints a per-file summary after the run. coverage.json names, for each region, the tests that ran it. wado dump --coverage-plan file.wado shows the regions a file is measured by.

--profile takes one file, runs it serially, and leaves a test that hangs unbounded — it samples on the epoch deadline the per-test timeout is counted in. See the wado-performance skill for reading the profile it writes.

A failure or resolved #[TODO] prints its own one-line notice immediately, otherwise a digest (N/Total files · tests, failed, todo, skip · ETA) prints every 5s, ending in a compile:/load:/skip:/test: summary. tailing the last line or two is enough to read the current state of a long run.

Serve

Use wado serve to run a Wado HTTP service (wasi:http/service world):

wado serve file.wado                        # serve on 0.0.0.0:8080 (default)
wado serve --addr 127.0.0.1:3000 file.wado  # serve on a custom address

Fuel

--report-fuel meters the guest in wasmtime fuel, about one unit per Wasm instruction, and reports what it spent. It counts instructions, not time, so pure computation in one build spends the same fuel on every machine. A different -O level or compiler change is a different build and spends differently. Host calls and GC spend none, but a guest waiting on I/O can loop more or less, depending on how the host answers.

wado run --report-fuel prog.wado    # stderr: fuel 477
wado test --report-fuel f.wado      # ok      f.wado :: name (2ms, fuel 890)
wado serve --report-fuel svc.wado   # stderr per request: fuel 1234 GET /path

A test's reading includes its instantiation. A serve reading leaves out the query, which can carry credentials. A request that traps its worker is reported with (trapped). A guest task can outlive its response, and wasmtime can neither cancel it nor say when it ends. What it spends before the next request arrives gets a second line marked (after response); what it spends later is charged to that next request. A serve worker's requests would share one meter, so --report-fuel forces --workers 1 --max-concurrency 1. Metering costs a few percent on the benchmarks, but wasmtime's documentation cites up to 2-3x for some workloads.

Dump

Use wado dump to inspect compiler internal state for debugging. See wado dump --help for the full help.

wado dump file.wado                  # show final WIR (default)
wado dump --nir file.wado            # show final NIR (after optimization)
wado dump --nir -O0 file.wado        # show NIR without optimization
wado dump --ast file.wado            # show parsed AST
wado dump --modules file.wado        # show loaded modules
wado dump --symbols file.wado        # show symbol table
wado dump --types file.wado          # show type table
wado dump --tir-resolved file.wado       # show TIR after type resolution
wado dump --tir-monomorphized file.wado  # show TIR after monomorphization
wado dump --nir-lowered file.wado        # show NIR right after lowering (before optimize)
wado dump --assert-plan file.wado        # show which operands each `assert` captures