CLI reference

Wax workflows

wax build

wax build [compiler options]

Compile a project to a native binary

wax check

wax check [compiler options]

Type-check a project without emitting a binary

wax targets

wax targets [compiler options]

Inspect resolved wax.json build targets

wax debug

wax debug [arguments]

Debug and time-travel a project (alias for waxdbg)

wax lsp

wax lsp [arguments]

Run the Wax language server over stdio

wax new

wax new [directory] [--name <name>] [--runtime oneshot|standalone|embedded] [--example warehouse] [--delivery native|wasm] [--bindings <languages>] [--output <directory>] [--yes]

Create a Wax project. Scripts must supply a directory and --runtime or --yes.

wax run

wax run [compiler options] [--record path.wxs] [-- program arguments]

Run a host target; Native Release runs execute directly without a C compiler.

wax vscode

wax vscode [--editor <name>] [--vsix <path>]

Install the Wax editor extension.

wax upgrade

wax upgrade

Upgrade an installer-managed toolchain.

wax uninstall

wax uninstall [--yes]

Remove an installer-managed toolchain.

wax help

wax help [command]

Show command help.

wax capabilities

wax capabilities [--json]

Report installed schemas and versions; exit 1 if any component is unavailable.

Packages

wax add

wax add <alias> <package> [range] [--registry URL] [--cache PATH] [--json]

Add or replace a direct dependency and install the resulting graph.

wax remove

wax remove <alias> [--registry URL] [--cache PATH] [--json]

Remove a direct dependency and install the resulting graph.

wax install

wax install [--registry URL] [--cache PATH] [--offline] [--json]

Install the locked dependency graph.

wax update

wax update [--registry URL] [--cache PATH] [--json]

Resolve and install a new dependency graph.

wax list

wax list [--json]

List declared and locked dependencies.

wax outdated

wax outdated [--json] [--registry URL]

Report newer direct-dependency versions.

wax doctor

wax doctor [--online] [--auth] [--json] [--registry URL]

Check project, registry, and account health.

wax pack

wax pack [--output PATH] [--json]

Create a package archive.

wax publish

wax publish [--registry URL] [--json]

Publish an immutable package version.

wax login

wax login [--registry URL] [--json]

Authorize this machine.

wax whoami

wax whoami [--registry URL] [--json]

Show the current Wax account.

wax logout

wax logout [--registry URL] [--json]

Revoke and remove saved credentials.

wax licenses

wax licenses [--json]

Show licenses for bundled components.

Compiler

waxc

waxc [mode] [options]

Compile the nearest enclosing Wax project discovered from the current directory.

waxc --help

waxc --help

Print the complete waxc command reference.

waxc --version

waxc --version

Print the waxc version and build commit.

Compiler options:

• --oneshot — override the manifest runtime with a one-shot executable
• --standalone — override the manifest runtime with a frame-loop executable
• --embed — override the manifest runtime with an embedded library
• --check — type-check without producing an artifact
• --output <path> — primary output artifact path
• --build-profile <name> — select a named wax.json build profile
• --target <name> — select a named wax.json build target
• --timings — print per-phase timing
• --json — emit one versioned JSON document
• --version — print the waxc version and exit
• --help, -h — print this help and exit
• --backend <auto|c|native|wasm> — select the artifact backend
• --emit-ir <path> — dump textual WxIR
• --preset <debug|release> — select the program observability preset
• --build-tier <instant|balanced|optimized> — select final compile latency and runtime quality
• --release-trace <on|off> — retain runtime call and loop tracing in Release output
• --c-compiler <path> — use a qualified Clang or GCC driver for C builds and native linking
• --c-compiler-arg <argument> — append one fixed custom C driver argument
• --verify <off|end|each> — select IR verifier cadence
• --profile[=<regex>] — inject per-function profiler zones
• --profile-exclude=<regex> — exclude matching functions from profiling
• --profile-list — list selected function names without building
• --bindings <list> — override bindings with a comma-separated language list, or none
• --bindings-dir <directory> — write generated bindings and shared runtime files to one directory
• --binding-output <language>=<path> — override one selected binding's canonical output path
• --ios-out <directory> — emit a local iOS Swift package
• --ios-runtime-dir <directory> — directory containing iOS WxRuntime static libraries

Language server

stdio server

waxlsp [--wait-for-debugger]

Run the language server over stdio.

--help

waxlsp --help

Print help.

--version

waxlsp --version

Print the version and build commit.

Debugger

Global options:

• --session <dir>: Select the debugger session directory.
• --backend <c|native>: Select the local Instant backend.

Commands default to JSON. --text selects prose; --json selects JSON explicitly. Command help documents semantic constraints.

waxdbg status

Read current execution state and source location.

waxdbg help

Describe waxdbg commands and target support.

• Operand command (required): the command to describe, as typed; run 'waxdbg --help' for the overview or 'waxdbg capabilities' for the whole catalog
• --verbose: include the registry record behind the command

waxdbg capabilities

List waxdbg commands supported by the current target surface.

• --supported: list only the commands the current target supports

waxdbg context

Re-read the current stop without moving it: the same document every stop prints.

• --frame <N>: the stack frame to read locals from (0 is the innermost)
• --object <@ID> (repeatable): an object to render into the stop, by stable id; repeatable
• --depth <N>: how many levels of nested objects to render
• --around <N>: source lines to include on each side of the stop

waxdbg init

Bind a debugger session directory to a Wax project.

waxdbg attach

Attach a debugger session directory to a target.

• Operand url (required): the http:// or https:// page hosting the Wasm target
• --port <N>: the loopback port the page allows for the bridge
• --pair: print the pairing document for the page's connection dialog
• --controller <path>: attach through an existing controller descriptor instead of starting a bridge
• --descriptor <path>: alias of --controller

waxdbg detach

Detach the current debugger target from a session directory.

waxdbg gui

Open or stop the native-backed debugger desktop window.

• Operand target (optional): a .wxs recording to open, or stop to stop the running GUI
• --foreground: keep the GUI in the foreground
• --no-open: start the GUI server without the desktop window, printing its URL instead

waxdbg cache clear

Reset debugger scratch state while preserving the project binding.

• --all: also clear the user-wide replay keyframe cache

waxdbg config get

Read a debugger session setting.

• Operand key (required): the setting to read

waxdbg config set

Update a debugger session setting.

• Operand key (required): the setting to write
• Operand value (required): its new value

waxdbg run

Start execution until completion or first pause.

• --backend <c|native>: run on this local backend instead of the session's
• --around <N>: source lines to include on each side of the stop

waxdbg continue

Resume forward execution until next pause or completion.

• --around <N>: source lines to include on each side of the stop

waxdbg step

Resume until the next statement, entering calls.

• --around <N>: source lines to include on each side of the stop

waxdbg next

Resume until the next statement at the same or shallower logical depth.

• --around <N>: source lines to include on each side of the stop

waxdbg out

Resume until execution exits the current logical depth.

• --around <N>: source lines to include on each side of the stop

waxdbg pause

Request a cooperative pause while execution is running.

• --endpoint <socket-path>: the live app's WAX_DEBUG_LISTEN socket
• --timeout <seconds>: how long to wait for the stop
• --around <N>: source lines to include on each side of the stop

waxdbg run-to

Run until a specific source location is reached.

• Operand location (required): a source position, <file>:<line>, with the path relative to the project
• --around <N>: source lines to include on each side of the stop

waxdbg break add

Set a source breakpoint.

• Operand location (required): a source position, <file>:<line>, with the path relative to the project
• --if <expression>: arm only when the expression holds

waxdbg break clear

Clear one source breakpoint and any stale condition.

• Operand location (optional): a source position, <file>:<line>, with the path relative to the project
• --all: clear every breakpoint instead of one

waxdbg break list

List configured session breakpoints.

waxdbg break breakable

List source lines that can accept a breakpoint.

• Operand file (optional): narrow to one source file

waxdbg watchpoint add

Configure break-on-write for one or more target fields.

• Operand target (required): a field to watch, @<sid>.<field> or static.<field>

waxdbg watchpoint list

List configured break-on-write targets.

waxdbg watchpoint clear

Clear one or all break-on-write targets.

• Operand target (optional): the field to stop watching
• --all: stop watching every field instead of one

waxdbg mutation add

Configure log-on-write for one or more target fields.

• Operand target (required): a field to log writes of, @<sid>.<field> or static.<field>

waxdbg mutation list

List configured log-on-write targets.

waxdbg mutation clear

Clear one or all log-on-write targets.

• Operand target (optional): the field to stop logging
• --all: stop logging every field instead of one

waxdbg mutation log

Read persisted or live mutation log entries.

waxdbg recording create

Create a self-contained recording from a live target, optionally staging typed per-frame channel inputs, and select it as the session's active analysis recording. The native GUI answers with recordingFile and byteLength rather than the bytes; the page reads them from session-file/<recordingFile> relative to the debugger page.

• Operand output (required): the .wxs file to write
• --frames <N>: how many frames to record
• --inputs <file>: typed channel initial values and per-frame inputs
• --keyframe-interval <K>: take a keyframe every K frames
• --include-keyframes: store keyframes in the recording
• --no-compress: write the recording uncompressed
• --profile: write <output>.profile.json from the same frames
• --profile-include <regex>: profile only the functions matching this pattern
• --profile-exclude <regex>: leave the functions matching this pattern out of the profile

waxdbg recording input-schema

Compile the bound project and describe the typed channel-input envelope accepted by recording creation.

waxdbg recording output-schema

Compile the bound project and describe the typed app-to-host channel output schema.

waxdbg recording outputs

Read named API-channel outputs at a completed recording frame.

• Operand recording (required): the .wxs recording to read
• --frame <N>: the completed frame whose output values to read

waxdbg recording select

Select the session's active analysis recording without creating a replay target or moving execution.

• Operand recording (required): the .wxs recording to make the active analysis recording

waxdbg recording continue-edited

Compile the bound project, start it with a fresh heap, and feed it a recording's inputs from frame zero to the requested frame.

• Operand recording (required): the .wxs recording to read
• --frame <N>: the frame to replay the edited build through

waxdbg source materialize

Mirror the attached target source bundle to a local directory.

• --output <dir>: where to write the sources

waxdbg agent bootstrap

Create a local agent workspace for an attached browser target.

• --output <dir>: where to write the briefing
• --around <N>: source lines on each side of the stop in the embedded stop document

waxdbg agent serve

Serve the local bring-your-own-agent MCP endpoint over stdio.

• --agent-name <name>: how the client is named in the audit log
• --grant <effect> (repeatable): grant an effect for the session; repeatable
• --grant-ttl-seconds <N>: how long a grant lasts
• --command-timeout-ms <N>: how long one command may run

waxdbg seek

Bind a recording to the session and move the replay cursor to an absolute frame boundary.

• Operand recording (optional): the .wxs recording to bind; omitted keeps the bound one
• --frame <N>: the frame to land on
• --break-on-frame <N> (repeatable): seed the match queue with this frame; repeatable
• --around <N>: source lines to include on each side of the stop

waxdbg step-back

Step back one statement at the current call depth -- the inverse of next, so it does not descend into a call the forward step passed over.

• --around <N>: source lines to include on each side of the stop

waxdbg step-back-into

Step back one statement in execution order -- the inverse of step, so it descends into the call the forward step passed over.

• --around <N>: source lines to include on each side of the stop

waxdbg continue-back

Run backwards to the previous breakpoint hit -- the inverse of continue. Breakpoint hits only: a watchpoint stop between them is not a candidate. Searching a match queue backwards is replay.prevMatch.

• --around <N>: source lines to include on each side of the stop

waxdbg next-match

Move to the next frame in the session match queue seeded by scrub.

• --around <N>: source lines to include on each side of the stop

waxdbg prev-match

Move to the previous frame in the session match queue seeded by scrub.

• --around <N>: source lines to include on each side of the stop

waxdbg recording repack

Rewrite a recording with fewer keyframes without replaying the application.

• Operand input (required): the .wxs recording to rewrite
• Operand output (required): a new .wxs path; existing files are refused
• --keep-keyframes <N>: maximum keyframes to retain; one keeps the initial replay anchor

waxdbg recording info

Read recording metadata without replaying program state.

• Operand recording (required): the .wxs recording to read

waxdbg recording frames

Read per-frame metadata over a selected frame range.

• Operand recording (required): the .wxs recording to read
• --frame <N>: one frame
• --range <A:B>: an inclusive frame range; A: or :B leaves that end open

waxdbg recording inspect

Render heap state at a recording frame boundary.

• Operand recording (required): the .wxs recording to read
• --frame <N>: the frame to inspect
• --range <A:B>: sweep an inclusive frame range, A: or :B leaving that end open (JSON only)
• --object <@ID>: narrow to one object
• --depth <N>: how many levels of nested objects to render
• --fields <a,b,c>: the fields to include in a range sweep
• --show-offsets: include raw heap byte offsets

waxdbg recording types

Read debugger type metadata as a versioned document; an unmatched name returns an empty types array.

• Operand recording (required): the .wxs recording to read
• --name <FQN>: one type, by fully qualified name

waxdbg recording queries

Build and list the query roots of a recording's merged query source set, using the session's active recording when the CLI path is omitted. Native CLI precedence is workspace library, embedded recording snapshot, repeatable --query-dir, then repeatable --file; --no-query-library removes only the workspace layer. Browser and direct-JS callers, which read no filesystem, supply the merged set as sources buffers instead.

• Operand recording (optional): the .wxs recording to read; omitted uses the session's active analysis recording
• --file <query.wax> (repeatable): a query source file; repeatable
• --query-dir <dir> (repeatable): a directory of query sources; repeatable
• --no-query-library: leave out the bound project's query library
• --verbose: include each query root's members

waxdbg investigation list

Build and list investigations in the merged workspace, embedded-recording, and explicit source set, using the session's active recording when the CLI path is omitted, including callable public members, closed cases, documentation, argument schemas, and result schemas.

• Operand recording (optional): the .wxs recording to read; omitted uses the session's active analysis recording
• --file <query.wax> (repeatable): a query source file; repeatable
• --query-dir <dir> (repeatable): a directory of query sources; repeatable
• --no-query-library: leave out the bound project's query library
• --verbose: include each investigation's members and cases

waxdbg investigation open

Open the Waxdbg investigations workspace for a recording, optionally focused on one investigation.

• Operand recording (required): the .wxs recording to open
• --name <FQN>: the investigation to open
• --foreground: keep the GUI in the foreground
• --no-open: start the GUI server without the desktop window, printing its URL instead

waxdbg recording query

Evaluate ordered typed query roots at a frame or range, compiling the additive source set once and sharing replay. Omit --name only for a sole root. --columns selects tables and projections.

• Operand recording (optional): the .wxs recording to read; omitted uses the session's active analysis recording
• --frame <N>: the frame to query
• --name <FQN> (repeatable): the query root to run
• --file <query.wax> (repeatable): a query source file; repeatable
• --query-dir <dir> (repeatable): a directory of query sources; repeatable
• --no-query-library: leave out the bound project's query library
• --args <json>: query arguments as inline JSON
• --args-file <path>: query arguments read from a JSON file
• --range <A:B>: an inclusive frame range; A: or :B leaves that end open
• --edges <column:rise|fall>: report where a column crosses
• --reduce <column:min|max|count|sum>: reduce a column over the range
• --ranges <column>: report the frame ranges where a column holds
• --where <column>: report the frames where a column holds
• --workers <N>: how many workers to scan with
• --ndjson: print one JSON object per line
• --output <file>: write the output to a file instead of stdout
• --columns: flatten rows into columns; implied by column projections
• --retain-mutations: retain query mutations across frames; requires one worker

waxdbg investigation run

Invoke one selected investigation member or closed case from the merged workspace, embedded-recording, and explicit source set, using the session's active recording when the CLI path is omitted and replaying its query scans in cloned workers. --name identifies the investigation; --member and --case are mutually exclusive.

• Operand recording (optional): the .wxs recording to read; omitted uses the session's active analysis recording
• --name <FQN>: the investigation to run
• --member <name>: the member to run
• --case <name>: the case to run
• --file <query.wax> (repeatable): a query source file; repeatable
• --query-dir <dir> (repeatable): a directory of query sources; repeatable
• --no-query-library: leave out the bound project's query library
• --args <json>: query arguments as inline JSON
• --args-file <path>: query arguments read from a JSON file
• --workers <N>: how many workers to replay with
• --bare: print the value alone
• --output <file>: write the output to a file instead of stdout

waxdbg recording api

Read host-to-Wax API method metadata embedded in a recording.

• Operand recording (required): the .wxs recording to read

waxdbg recording hosts

Read Wax-to-host function metadata embedded in a recording.

• Operand recording (required): the .wxs recording to read

waxdbg recording histogram

Read per-type heap count and byte histogram at a recording frame boundary.

• Operand recording (required): the .wxs recording to read
• --frame <N>: the frame whose heap to walk
• --sort <count|size|name>: the histogram order

waxdbg recording timeline

Read per-frame object timeline artifact.

• Operand recording (required): the .wxs recording to read
• --object <@ID> (repeatable): an object to follow; repeatable
• --range <A:B>: an inclusive frame range; A: or :B leaves that end open
• --depth <N>: how many levels of nested objects to render

waxdbg recording allocations

Read allocation/deallocation artifact over a frame range.

• Operand recording (required): the .wxs recording to read
• --range <A:B>: an inclusive frame range; A: or :B leaves that end open

waxdbg recording calls

Read Wax-to-host call artifact for a frame.

• Operand recording (required): the .wxs recording to read
• --frame <N>: the frame whose host calls to list

waxdbg recording channels

Read recorded host-channel inputs for a frame.

• Operand recording (required): the .wxs recording to read
• --frame <N>: the frame whose channel values to list

waxdbg recording mutations

Offline replay scan for mutation targets; distinct from mutationLog configuration.

• Operand recording (required): the .wxs recording to read
• Operand target (required): a field to follow, @<sid>.<field>

waxdbg recording diff

Read frame-to-frame diff artifact.

• Operand recording (required): the .wxs recording to read
• --range <A:B>: the two frames to compare, inclusive
• --object <@ID> (repeatable): narrow to this object; repeatable
• --depth <N>: how many levels of nested objects to render
• --show-offsets: include raw heap byte offsets (JSON only)

waxdbg recording find

Find frames matching an inline --where expression or one query root selected from the merged workspace, embedded-recording, and explicit source set, using the session's active recording when the CLI path is omitted. The controller resolves that set and transmits it; the agent never reads a controller-local path.

• Operand recording (optional): the .wxs recording to read; omitted uses the session's active analysis recording
• --where <expression>: a boolean Wax expression over the frame
• --name <FQN>: a catalogued query root
• --query <root>: the root inside a single --file
• --file <query.wax> (repeatable): a query source file; repeatable
• --query-dir <dir> (repeatable): a directory of query sources; repeatable
• --no-query-library: leave out the bound project's query library
• --args <json>: query arguments as inline JSON
• --args-file <path>: query arguments read from a JSON file
• --retain-mutations: keep mutations between frames
• --range <A:B>: an inclusive frame range; A: or :B leaves that end open
• --all: search the full range without a match limit; mutually exclusive with --limit
• --limit <N>: stop after N matches; coverage reports whether the range was exhausted
• --around <A:B>: frames of context before and after each match
• --invert: report the frames that do not match
• --fail-on-match: exit nonzero when anything matches
• --fail-on-no-match: exit nonzero when nothing matches
• --count: return the match count and search coverage
• --summary: print a summary of the matches
• --ranges: print the matching frame ranges
• --commands: print debugger commands that reach each match
• --timeline <@ID,@ID>: objects to include in the emitted timeline commands

waxdbg eval

Pure Wax/debug-expression evaluation over recorded debug data; never arbitrary JavaScript.

• Operand recording (required): the .wxs recording to evaluate against
• Operand expression (optional): the Wax expression to evaluate, with --type
• --frame <N>: the frame to evaluate at
• --type <T>: the expression's type: i32, u32, i64, u64, f32, f64, bool, string or object
• --file <query.wax>: an authored query source instead of an inline expression
• --query <name>: the query root to select when --file declares several
• --args <json>: query arguments as inline JSON
• --args-file <path>: query arguments read from a JSON file
• --depth <N>: how many levels of nested objects to render

waxdbg edit apply

Recompile the project's sources -- from disk, with any transmitted changes laid over them -- against the running build and swap the result into the live target at a frame boundary, keeping its heap. Breakpoints and conditions carry across by file and line. A browser target has no live heap: its session re-executes the program from its input tape for every command, so the edit is that tape replayed through the rebuilt program, landing at the start of the frame after the one the head was stopped in.