#CLI

The rig command discovers a source project's dependencies, executes its higher stages, and builds or runs the resulting Component. The same source can be used by the command line and playground; execution authority comes from the host.

#Run and Build

Run a WASI 0.3 command and pass arguments to it:

rig run main.rig -- first second

The command must export wasi:cli/run@0.3.0. An arbitrary exported function is a library API, not a command entry point. Output and exit status come from the program's WASI interactions and command result.

Build without invoking the command:

rig build main.rig
rig build main.rig --output out/application.wasm

The default output replaces the entry file's extension with .wasm. Build still executes compile-time code; it skips the runtime invocation, not staging.

Local run and ordinary build compose resolved Component dependencies. rig build main.rig --external-deps instead preserves package imports for a separate composition or hosting environment. This is a build-artifact choice, not an alternate run mode.

--locked prevents fetching and checks the selected dependency closure against rig.lock. Use rig deps fetch main.rig to prepare dependencies before a locked build or run.

#Direct Scripts

An explicit path can be invoked without the run subcommand:

rig ./script.rig first --verbose

Everything after the path belongs to the script. Use explicit rig run when passing compiler options. Subcommands take precedence over bare names, so ./run selects a script whose name would otherwise be a command.

On Unix, a script may begin with #!/usr/bin/env rig:

chmod +x script.rig
./script.rig first --verbose

These forms use the same WASI command contract. The script does not need a .rig suffix. Formatting preserves its shebang and executable permissions.

When argument inheritance is enabled, the guest receives the entry path as argument zero followed by the script arguments. A profile with explicit process.args supplies that entire list instead. Source imports and project configuration follow the entry path; execution does not change the caller's working directory.

#Inspect Staging

rig reduce main.rig --stage 0
rig reduce main.rig --stage 1 --output stage-1.rig

Reduction runs higher-stage work and renders an inspection view at the selected frontier. The output is not recompilable residual source, even if saved with a .rig extension. Each invocation performs its own compile-time effects.

#Format, Document, and Test

rig fmt main.rig
rig fmt main.rig --check
rig doc main.rig
rig test main.rig
rig test main.rig --stage 1

fmt edits the selected file; --check reports whether it needs formatting without changing it. Formatting is syntax-only and does not run staged code.

doc evaluates public project documentation. test runs project tests at all tested stages, or at the selected stage. Both accept a file, a directory containing main.rig, or no path for the current directory. Test execution uses compile capabilities even for Stage 0 tests. See Documentation and Tests for registration and assertion semantics.

#Dependencies

rig deps show main.rig
rig deps fetch main.rig

show reports dependency and lock status. fetch resolves missing packages and merges the reachable graph into rig.lock.

Publishing uses a configured registry and its credentials:

rig deps publish-source pkg:example/math@1.0.0 ./math
rig deps publish-component pkg:example/math@1.0.0 ./math/lib.rig

These are alternative representations of a package, not two required publication steps. Projects and Packages describes their different APIs and resolution behavior.

#Execution and Compilation Options

build, run, and reduce accept --timings to report phase durations and --compile-cache to reuse engine compilation work. The cache does not memoize staged effects or share an initialized program instance between requests. doc and test also accept --compile-cache.

build --optimize and run --optimize explicitly invoke Binaryen's wasm-opt from PATH. The compiler requires version 131 or newer. A missing or failing optimizer is an error, not a silent fallback. Commands without this option do not need Binaryen.

Use rig --help or rig <command> --help for accepted arguments. Capabilities describes project execution policy; there are no per-capability CLI flags.

#Diagnostics

Diagnostics identify the source location and relevant expected and found types or stages. For example, initializing an Int binding with true is a type error, not an implicit Boolean-to-integer conversion. A failed build produces no substitute Component.

Nonzero command exit is distinct from a compiler diagnostic or execution trap. The playground shows diagnostics against the source snapshot used by the action, while command output remains ordinary text.