#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.