WACS.Cli 1.3.0

WACS

The unified WebAssembly toolchain for .NET. One CLI — wacs — covers running, compiling, inspecting, and generating bindings for WebAssembly modules and components, backed by the WACS interpreter, the WACS.Transpiler.Lib AOT engine, and the WACS.ComponentModel.Bindgen.Lib binding generator.

Note: This tool supersedes wasm-transpile (WACS.Transpiler). The legacy package is deprecated; install WACS.Cli instead. The package id is WACS.Cli (the bare WACS id is the runtime library, Wacs.Core); the tool command users type is wacs.

Installation

dotnet tool install -g WACS.Cli
wacs --help

Verb structure

wacs uses a verb-based subcommand layout (matches wasmtime / wasmer industry precedent — keeps "run" flags from cluttering the "compile" surface):

Direct-run shortcut

If the first argument is a .wasm / .wat file path that exists, wacs defaults to the run verb:

wacs my.wasm                            # → wacs run my.wasm
wacs build app.wasm -o app.dll          # explicit verb
wacs inspect app.wasm --stats           # explicit verb

Verb keywords (run / build / inspect / help / --help / -h / version / --version) bypass the shortcut. Anything else that isn't a verb keyword and doesn't look like a wasm path is treated as a verb name (so a typo gives a parse error rather than running the wrong file).

Engine choice

--engine interpreter (default for run) parses + executes via the WACS interpreter — the AOT-safe path with full instrumentation hooks (gas counter, dotTrace bracket, per-instruction logging, stats).

--engine transpiler JITs the module to .NET IL via Reflection.Emit, then runs through CLR-native dispatch with imports proxied back to the interpreter (mixed-mode). Roughly 64× the interpreter's throughput on compute-bound workloads (CoreMark on M3 Max: 17 552 iter/s vs 274 for the polymorphic interpreter — see the root README for the full table).

build always uses the transpiler — its job is to produce a .dll.

run and build both auto-detect component vs core wasm via the layer header byte; component-mode routing happens transparently when you pass .component.wasm input.

wacs run — execution

wacs run [files]... [options]              [-- argv...]

Examples

Run with _start (WASI command):

wacs run app.wasm -e PATH=/usr/bin -d ./data
# WASI Preview 1: env vars, preopened directory, _start dispatch

Invoke a specific export with arguments:

wacs run module.wasm --call add -- 7 35
# → Result:[i32=42]

Trailing args after -- are forwarded to the chosen export (parsed as the function's wasm parameter types) or to WASI argv when running _start.

Run a component with WASI Preview 2 (direct-linked):

wacs run app.component.wasm --wasip2
# auto-routes to transpiler engine + WasiPreview2Bundle when
# --wasip2 / --host-package is set (those flags only make sense
# with the bundle path)

Multi-module composition via ModuleLinker:

wacs run a.wasm b.wasm --call quadruple -- 7
# → 28   (B's quadruple → A's double, twice, via shared runtime)

Each input registers under its filename basename so cross-module imports resolve through the runtime's binding table. The chosen export runs on the last input.

Through the AOT transpiler (mixed-mode):

wacs run app.wasm --engine transpiler --wasi
# transpiles in-process via Reflection.Emit, then runs through
# CLR-native dispatch with WASI imports proxied back to the
# interpreter

Profile a hot path:

wacs run app.wasm --profile
# JetBrains dotTrace measure-profiler bracket; snapshot lands
# in the OS-default profiler temp dir

Instrumented runs (interpreter only):

wacs run app.wasm --gas-limit 1000000 --log-gas
# trap if total instructions exceed 1M; print final count

wacs run app.wasm --log-execution Calls --calculate-lines
# log every call instruction with its source line number

wacs run app.wasm --stats Function
# per-function instruction counts after the run

Custom host bindings:

wacs run app.wasm --bind ./MyGameHost.dll
# load + activate every IBindable in MyGameHost.dll, wire into runtime

run flag reference

wacs build — transpile to .dll

wacs build [files]... -o <output> [options]

Examples

Single-file core wasm:

wacs build app.wasm -o app.dll

Multi-file linker composition:

wacs build a.wasm b.wasm -o b.dll
# → wrote a.dll, b.dll  (siblings land at <basename>.dll alongside)

Component with WASI Preview 2 + runnable Main:

wacs build app.component.wasm --wasip2 --emit-main \
    --entry-point greet -o app.dll
# Component-mode: --wasip2 resolves WASI imports to inline IL
# (no delegate hop). --emit-main bakes Program.Main(string[])
# into the output that constructs the bundle, instantiates the
# module, and invokes greet.

Tune the output:

wacs build app.wasm -o app.dll \
    --simd intrinsics \
    --data-storage static \
    --namespace MyApp.Wasm
# SIMD via Vector128<T> hardware intrinsics; data segments as
# static byte[] fields; root namespace MyApp.Wasm

build flag reference

wacs aot — wasm → NativeAOT native binary

wacs aot <input.wasm> [-o <output>] [options] [-- argv...]

End-to-end: transpile the input wasm to a stable-named .dll, scaffold a throwaway consumer csproj that statically references it plus the WACS runtime support assemblies, and run dotnet publish -p:PublishAot=true -r <rid>. The resulting native binary is copied to the output path; the temp build dir is removed unless --keep-temp.

Cold-start equivalent of transpiler-aot-linked from docs/COLDSTART.md: new Module() → typed direct call into the wasm function. No JIT, no Reflection.Emit, no Assembly.Load, no MethodInfo.Invoke at run time.

Examples

Compute-only module to native binary:

wacs aot fib.wasm -o fib
./fib                 # native exe — no .NET runtime required

WASI Preview 1 (the wasi-libc / wasi-sdk world):

wacs aot coremark.wasm --wasi -o coremark
./coremark 1 1 1 1    # trailing argv forwarded to the guest

--wasi references WACS.WASI.Preview1 from the scaffolded consumer; the source generator in WACS.HostBindings.SourceGen emits an IImports adapter that wires the wasm's wasi_snapshot_preview1.* imports straight to the [WacsImport]-annotated statics. No reflection, no DispatchProxy, fully NativeAOT-trim-safe.

Component with WASI Preview 2:

wacs aot app.component.wasm --wasip2 --entry-point greet -o app
./app

The component's wasi:* imports are direct-linked at transpile time against the typed C# host interfaces in WACS.WASI.Preview2; the consumer constructs the WasiPreview2Bundle via Microsoft.Extensions.DependencyInjection before invoking the named export.

Pick the AotLinked emission target (smaller binary):

wacs aot fib.wasm --aot-linked -o fib
# Skips the codec wrapper. Default emission keeps it; AotLinked
# inlines memory/data/globals/tables straight into the Module ctor
# and lets the trimmer dead-strip the codec machinery.

aot flag reference

Trailing positional args after the input file are forwarded to the guest as argv when --wasi is set.

wacs inspect — diagnostics

wacs inspect <file> [options]

Parse-only. No instantiation, no execution, no transpilation.

Examples

Stats summary (default behavior with no flags):

$ wacs inspect module.wasm
file        module.wasm
kind        core wasm module
types       3
functions   12 (4 imported)
exports     5
memories    1
tables      1
globals     0
data        2 segment(s), 1024 bytes total
elements    1 segment(s)

Component stats:

$ wacs inspect app.component.wasm
file              app.component.wasm
kind              wasm component
core modules      3 (768 bytes total)
nested components 0
types             7
canons            4
exports           1
custom sections   1
raw sections      26

List exports / imports:

wacs inspect module.wasm --exports
wacs inspect module.wasm --imports

Dump WAT (round-trips back through the text parser):

wacs inspect module.wasm --dump-wat                 # to stdout
wacs inspect module.wasm --dump-wat --output-dir .  # writes module.wat

inspect flag reference

wacs bindgen — WIT ↔ C# bindings

wacs bindgen <input> -o <output-dir> [options]

Two directions on one verb, auto-detected by input shape:

• Forward — a .wit file or a directory tree of WIT files (recurses into deps/) → [WitSource]-tagged C# interfaces. Use this when authoring components: pre-generate the host binding surface for offline AOT targets that can't use the runtime transpiler.
• Reverse — a transpiled .dll carrying embedded component-type metadata → regenerated WIT + C# bindings. Use this when the original .wit is gone but the shipped .dll is still on hand.

Examples

Forward, single WIT file:

wacs bindgen ./wit/hello.wit -o ./Generated/

Forward, WIT directory tree (with deps/):

wacs bindgen ./wit -o ./Generated/
# Recurses into deps/ subdirectories. Headerless files attribute
# to the parent package per the wit-bindgen-csharp convention.

Reverse, regenerate from a transpiled .dll:

wacs bindgen ./app.dll -o ./regenerated/
# Extracts the embedded component-type metadata, decodes it to
# WIT, and regenerates the [WitSource]-tagged C# binding surface.
# Errors with exit code 3 if the .dll has no embedded WIT.

Reverse with raw bytes preserved:

wacs bindgen ./app.dll -o ./regen --write-wit
# Also writes <basename>.componenttype.bin alongside the .cs files
# (useful for `wasm-tools component wit` round-trip inspection).

bindgen flag reference

Migration from wasm-transpile

The legacy wasm-transpile (WACS.Transpiler) CLI keeps working unchanged — it ships a stderr deprecation banner pointing at wacs but every flag still functions. Concrete migrations:

The standalone WACS.ComponentModel.Bindgen package (wit-bindgen-wacs CLI) was rolled into the bindgen verb here before its first NuGet release; users only ever see wacs bindgen. The WACS.ComponentModel.Bindgen.Lib package (programmatic surface) is unaffected — source generators and build-time integrations should keep referencing it directly.

The -i short flag is retired (Console used it for --invoke, Transpiler for --input — incompatible). Inputs are positional in wacs; the --call long flag replaces --invoke.

License

WACS is distributed under the Apache 2.0 License.