CLI

The CLI binaries are named reggie and regulus. When running from a checkout, prefix commands with Cargo:

cargo run -q -p compiler_cli -- build

Installed binaries can be run directly. The docs use reggie, but regulus is also available as an alias:

reggie build
regulus build

Global options

Pass --no-color before or after a subcommand to disable ANSI color in human-readable output:

reggie --no-color build examples/scalar_project
reggie build examples/scalar_project --no-color

Regulus also disables ANSI color when the NO_COLOR environment variable is set^no-color

Build a project

Use build for Gleam projects with a gleam.toml file.

reggie build
reggie build examples/scalar_project
reggie build examples/scalar_project/gleam.toml

With no project argument, the current directory is used. A directory argument builds that project root. A gleam.toml argument builds the project that owns that manifest.

Project builds write build/<package>.wasm by default. Use --output to choose an exact final path or --out-dir to write compiler-named artifacts into a directory.

Example:

reggie --no-color build examples/scalar_project --out-dir build/docs

Resolving dependencies
wasm build/docs/scalar_project.wasm (63 bytes)

See Project compilation and dependencies for dependency loading, linked output, and current project limits.

Compile one file

Use compile for a single .gleam file. This path is useful for small tests, fixtures, and compiler debugging.

reggie compile path/to/module.gleam

By default, single-file compilation writes a .wasm file next to the input. --output and --out-dir work the same way as project builds.

Single-file compilation exists for fixtures, small examples, and compiler debugging. Project compilation should use build so module discovery, dependencies, and linked output all follow the project model.

Run one file

Use run to compile a single .gleam file and execute one exported function with Wasmtime.

reggie run path/to/module.gleam
reggie run path/to/module.gleam --function answer
reggie run path/to/module.gleam --function add 1 2

run defaults to the main export. The exec command is an alias:

reggie exec path/to/module.gleam

Example:

reggie run examples/scalar_project/src/main.gleam --function add_one 41

42

Scalar arguments use the low-level Wasm ABI. Int values are passed as i64, Float values as f64, and Bool values as i32. Return values are rendered for scalars and supported managed values such as strings, tuples, lists, records, Result, and Option. Programs can also print strings through gleam/io.print and gleam/io.println when targeting Wasmtime.

Targets

Both build and compile accept --target:

reggie build examples/scalar_project --target browser
reggie build examples/scalar_project --target bundler
reggie compile path/to/module.gleam --target wasmtime

Supported target values are wasmtime, browser, bundler, nodejs, and wasi. Project builds use the target from gleam.toml when --target is not provided.

browser, bundler, and nodejs emit deterministic .mjs adapters next to the .wasm artifact when Wasm output is requested. The adapters load the Wasm module, check imports, convert scalar and string calls, and read supported structured export results.

Example:

reggie --no-color build examples/scalar_project --target nodejs --out-dir build/node

Resolving dependencies
wasm build/node/scalar_project.wasm (2651 bytes)
js build/node/scalar_project.mjs

Target-specific externals are checked before Wasm assembly. If a source file imports a browser or Node.js host module while compiling for Wasmtime, the CLI reports the target mismatch with a source label and recovery note.

Artifacts

--emit selects emitted artifact kinds:

reggie build examples/scalar_project --emit wasm,wat
reggie build examples/scalar_project --emit wat,ast,resolved,typed,ir
reggie build examples/scalar_project --emit runtime,abi

Supported emit values are:

Value	Output
wasm	Final WebAssembly binary.
wat	WebAssembly text for the linked module.
ast	Per-module AST debug dumps.
resolved	Per-module resolved AST debug dumps.
typed	Per-module typed-module debug dumps.
ir	Linked IR debug dump.
runtime	Runtime layout and object tag summary.
abi	Import/export ABI boundary summary.

wasm is the default. wat writes next to the Wasm output, or into --out-dir when that option is used. Debug emit values write deterministic files beside the selected output path unless --dump-dir is set.

Example:

reggie --no-color build examples/scalar_project --out-dir build/debug --emit wasm,wat

Resolving dependencies
wasm build/debug/scalar_project.wasm (63 bytes)
wat build/debug/scalar_project.wat

Use --dump-dir to write all compiler debug dumps into a separate directory:

reggie build examples/multi_module_project --dump-dir build/dumps

Single-file dumps include AST, resolved AST, typed output, IR, WAT, runtime layout, and ABI output. Project dumps include per-module AST, resolved AST, typed output, linked IR, WAT, runtime layout, and ABI output.

If compilation fails, Regulus does not write the final Wasm artifact. Debug artifacts are only written when the requested compiler phase completes.

The backend emits final Wasm bytes from its structured module. WAT is rendered from that module for debugging and snapshots; it is not the source of truth for the final .wasm artifact.

Diagnostics and exit codes

Successful commands exit with status code 0. Compilation diagnostics and project loading errors exit with a non-zero status code. Command misuse, such as an unknown flag or invalid subcommand, is reported by the CLI argument parser and also exits non-zero.

Human diagnostics include file paths, source snippets when a span is available, labels, and notes. Project diagnostics are grouped in a stable order across modules.

Missing project manifests are reported with the path Regulus tried to load:

reggie --no-color build /tmp/not-a-regulus-project

error could not load project /tmp/not-a-regulus-project
diagnostic ProjectError: project manifest not found at /tmp/not-a-regulus-project/gleam.toml
  note: pass a project directory or a path to gleam.toml

Duplicate modules include both conflicting source paths:

reggie --no-color build examples/diagnostics/duplicate_modules

error could not load project examples/diagnostics/duplicate_modules
diagnostic ProjectError: duplicate module `app` in examples/diagnostics/duplicate_modules/src/app.gleam and examples/diagnostics/duplicate_modules/test/app.gleam
  note: each module name must be unique across src and test

Inspect one source file

Use debug when changing parser or AST support for one .gleam file. The dbg command is an alias.

reggie debug ts path/to/module.gleam
reggie debug spans path/to/module.gleam
reggie debug ast path/to/module.gleam
reggie debug json path/to/module.gleam --ast --spans

The debug views are:

View	Output
ts	Tree-sitter concrete syntax tree S-expression.
spans	Tree-sitter nodes with spans, positions, and fields.
ast	Regulus AST built from the tree-sitter tree.
json	Selected debug views as JSON.

spans is for tree-sitter nodes. json --spans includes tree-sitter span details. If no json view flags are passed, json defaults to tree-sitter output.

By default, debug/dbg require a source file and at least one view flag.

List project modules

Use list to inspect discovered modules without building artifacts.

reggie --no-color list examples/multi_module_project

project multi_module_project 1.0.0 (2 modules)
module main -> examples/multi_module_project/src/main.gleam
module math -> examples/multi_module_project/src/math.gleam

Current limitations

Project compilation is still growing. Broad Hex dependency language coverage and additional host APIs are documented in the development and reference docs as they stabilize.