WACS.Cli 1.7.4

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

Mount a host directory into a wasip2 component:

wacs run app.component.wasm --wasip2 -d ./models::/models
# `host::guest` mount-pair syntax — the host side is `./models`,
# the guest sees `/models`. Bare `-d models` mounts at `/models`
# (Preview1's rooting convention so the same flag form works on
# both engines). Both sides reach the guest through the
# transpiler's direct-link emit for
# wasi:filesystem/preopens.get-directories — no shim needed.

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).
#
# Command components don't need --call — `wacs run --wasip2` looks
# for the canonical wasi:cli/run@<version>#run export and dispatches
# it automatically. Falls back to _start, then to a helpful error
# listing the available exports. Pass --call <export> (or
# --invoke <export>) to override.

Run a component that imports wasi:nn (ONNX inference):

wacs run my.component.wasm --wasip2 --wasi-nn -d ./models
# --wasi-nn loads Wacs.WASI.NN.OnnxRuntime (bundled with the CLI)
# and wires its IBindable adapter into the runtime. For other
# wasi-nn backends (ML.NET, LlamaSharp), pass the package name
# through --bind directly.

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 + format conversion

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

For components, --imports enumerates each top-level instance import with its package + version — useful for predicting which host packages to wire before running:

$ wacs inspect my.component.wasm --imports
=== component-level imports ===
  Instance  wasi:nn/inference@0.2.0-rc-2024-10-28
  Instance  wasi:nn/graph@0.2.0-rc-2024-10-28
  Instance  wasi:cli/stdout@0.2.9
  Instance  wasi:cli/exit@0.2.9
  …

A component with wasi:nn/* imports needs --wasi-nn (or --bind Wacs.WASI.NN.<backend> for non-ONNX backends). wasi:cli/* needs --wasip2. Version mismatches (e.g. component compiled against wasi:cli/stdout@0.2.9 but Wacs.WASI.Preview2 ships 0.2.0) surface as direct-link resolution failures at instantiation.

WAT ↔ wasm round-trip:

# binary → text
wacs inspect module.wasm --dump-wat                 # WAT to stdout
wacs inspect module.wasm --dump-wat --output-dir .  # writes module.wat

# text → binary
wacs inspect module.wat  --dump-wasm                # raw bytes to stdout (pipe target)
wacs inspect module.wat  --dump-wasm --output-dir . # writes module.wasm

Round-trips preserve function $names via the standard name custom section and preserve WAT comments / (@…) annotations via a wacs.trivia custom section (WACS-specific, ignored by other engines). A WAT → wasm → WAT cycle recovers identifiers and trivia; the canonical re-render is line-stable but doesn't preserve original whitespace exactly.

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

wacs wast2json — spec-test bundle

wacs wast2json <input.wast> -o <output-dir> [options]

Convert a .wast spec-test script into the canonical wast2json bundle: a .json file listing commands plus one side-car .wasm per referenced module. Mirrors wabt's wast2json shape, so the resulting directory is consumable by any spec-test runner that reads the format (WACS's own Spec.Test runner included).

# Smallest spec testcase:
$ wacs wast2json Spec.Test/spec/test/core/forward.wast -o out/
wrote out/forward.json (5 commands, 1 side-car modules)

$ ls out/
forward.0.wasm  forward.json

# Larger fixture exercising assert_invalid / assert_trap:
$ wacs wast2json Spec.Test/spec/test/core/i32.wast -o out/
wrote out/i32.json (460 commands, 86 side-car modules)

wast2json flag reference

Output shape (excerpt)

{
  "source_filename": "forward.wast",
  "commands": [
    { "type": "module", "line": 1, "filename": "forward.0.wasm" },
    {
      "type": "assert_return",
      "line": 17,
      "action": {
        "type": "invoke",
        "field": "even",
        "args": [{ "type": "i32", "value": "13" }]
      },
      "expected": [{ "type": "i32", "value": "0" }]
    }
  ]
}

Floats are emitted as their unsigned IEEE-754 bit pattern in decimal (e.g. 1.0 → "value": "1065353216") so NaN payloads round-trip exactly. nan:canonical / nan:arithmetic ride along as string sentinels in expected-value position.

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.