Tooling | Atoll Book

The atoll command line — building, running, testing, and benchmarking Atoll code.

The atoll binary is the single entry point for working with Atoll source. The Language guide uses three of its subcommands constantly.

Command	What it does
`atoll check <input>`	Parse, resolve, and type/effect check. Reports diagnostics; emits nothing.
`atoll build <input>`	Everything `check` does, then lower to WebAssembly and write a unit artifact.
`atoll run <input>`	Build, then execute through the runtime.
`atoll test <input>`	Discover and run `@test` functions. See Testing.
`atoll bench <input>`	Discover and run `@bench` functions with timing statistics.
`atoll lint <input>`	`check`, but exits non-zero on warnings too. For CI gates.
`atoll new <name>`	Scaffold a new project.
`atoll fmt <input>`	Format source.
`atoll repl`	Interactive session.
`atoll add` / `deps` / `lock`	Dependency management against `atoll.toml`.
`atoll migrate`	Database schema migration against a live datasource.

The input to check, build, run, and test may be a single .at file or a directory. A directory is walked recursively and compiled as one project, using an atoll.toml at or above it when present.

Check is not the whole story

atoll check stops after semantic analysis. That is fast and gives the best diagnostics, but it does not prove a program can be compiled: a prelude method can type-check and still have no lowering path, which only atoll build discovers.

error[ATOLL2004]: builtin method `chunked` has no lowering path — declared in
the prelude but never implemented (no body, host import, or intrinsic), so this
call cannot be compiled to wasm

When you are checking whether something really works, build it.

Only code reachable from an entry point (fn main or fn entry_*) is lowered, so a file of uncalled declarations builds trivially. Exercise what you want verified from an entry point.

Optimization levels

build, run, test, and bench accept -O:

Level	Meaning
`-O0`	Lowering core only — fast compiles, debuggable output
`-O1`	Balanced: full pipeline, small budgets
`-O2`	Full optimization (the default)

Diagnostics and tracing

atoll trace captures stage-tagged events from the compilation pipeline, and atoll dump --stage <ast|hir|mir|wasmir> prints one stage’s IR text. Both are compiler-development tools rather than everyday commands; see Diagnostics for reading ordinary compiler output.