# CLI reference Use `wax help` for the human command index and `wax capabilities --json` for the installed toolchain’s command schemas and versions. Missing or incompatible components remain explicit unavailable entries; the command exits 1 when any component is unavailable. The JSON protocol is `wax.capabilities.v1`. Compiler, package and debugger options are owned by their focused schemas. The umbrella forwards their arguments. `wax debug` preserves the debugger’s JSON default; use `--text` for prose. LSP output is a JSON-RPC stream. ## Wax workflows ### wax build ```text wax build [compiler options] ``` Compile a project to a native binary ### wax check ```text wax check [compiler options] ``` Type-check a project without emitting a binary ### wax targets ```text wax targets [compiler options] ``` Inspect resolved wax.json build targets ### wax debug ```text wax debug [arguments] ``` Debug and time-travel a project (alias for waxdbg) ### wax lsp ```text wax lsp [arguments] ``` Run the Wax language server over stdio ### wax new ```text wax new [directory] [--name ] [--runtime oneshot|standalone|embedded] [--example warehouse] [--delivery native|wasm] [--bindings ] [--output ] [--yes] ``` Create a Wax project. Scripts must supply a directory and --runtime or --yes. ### wax run ```text wax run [compiler options] [--record path.wxs] [-- program arguments] ``` Run a host target; Native Release runs execute directly without a C compiler. ### wax vscode ```text wax vscode [--editor ] [--vsix ] ``` Install the Wax editor extension. ### wax upgrade ```text wax upgrade ``` Upgrade an installer-managed toolchain. ### wax uninstall ```text wax uninstall [--yes] ``` Remove an installer-managed toolchain. ### wax help ```text wax help [command] ``` Show command help. ### wax capabilities ```text wax capabilities [--json] ``` Report installed schemas and versions; exit 1 if any component is unavailable. ## Packages ### wax add ```text wax add [range] [--registry URL] [--cache PATH] [--json] ``` Add or replace a direct dependency and install the resulting graph. ### wax remove ```text wax remove [--registry URL] [--cache PATH] [--json] ``` Remove a direct dependency and install the resulting graph. ### wax install ```text wax install [--registry URL] [--cache PATH] [--offline] [--json] ``` Install the locked dependency graph. ### wax update ```text wax update [--registry URL] [--cache PATH] [--json] ``` Resolve and install a new dependency graph. ### wax list ```text wax list [--json] ``` List declared and locked dependencies. ### wax outdated ```text wax outdated [--json] [--registry URL] ``` Report newer direct-dependency versions. ### wax doctor ```text wax doctor [--online] [--auth] [--json] [--registry URL] ``` Check project, registry, and account health. ### wax pack ```text wax pack [--output PATH] [--json] ``` Create a package archive. ### wax publish ```text wax publish [--registry URL] [--json] ``` Publish an immutable package version. ### wax login ```text wax login [--registry URL] [--json] ``` Authorize this machine. ### wax whoami ```text wax whoami [--registry URL] [--json] ``` Show the current Wax account. ### wax logout ```text wax logout [--registry URL] [--json] ``` Revoke and remove saved credentials. ### wax licenses ```text wax licenses [--json] ``` Show licenses for bundled components. ## Compiler ### waxc ```text waxc [mode] [options] ``` Compile the nearest enclosing Wax project discovered from the current directory. ### waxc --help ```text waxc --help ``` Print the complete waxc command reference. ### waxc --version ```text 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 ` — primary output artifact path - `--build-profile ` — select a named wax.json build profile - `--target ` — 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 ` — select the artifact backend - `--emit-ir ` — dump textual WxIR - `--preset ` — select the program observability preset - `--build-tier ` — select final compile latency and runtime quality - `--release-trace ` — retain runtime call and loop tracing in Release output - `--c-compiler ` — use a qualified Clang or GCC driver for C builds and native linking - `--c-compiler-arg ` — append one fixed custom C driver argument - `--verify ` — select IR verifier cadence - `--profile[=]` — inject per-function profiler zones - `--profile-exclude=` — exclude matching functions from profiling - `--profile-list` — list selected function names without building - `--bindings ` — override bindings with a comma-separated language list, or none - `--bindings-dir ` — write generated bindings and shared runtime files to one directory - `--binding-output =` — override one selected binding's canonical output path - `--ios-out ` — emit a local iOS Swift package - `--ios-runtime-dir ` — directory containing iOS WxRuntime static libraries ## Language server ### stdio server ```text waxlsp [--wait-for-debugger] ``` Run the language server over stdio. ### --help ```text waxlsp --help ``` Print help. ### --version ```text waxlsp --version ``` Print the version and build commit. ## Debugger Global options: - `--session `: Select the debugger session directory. - `--backend `: 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 `: 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 `: how many levels of nested objects to render - `--around `: 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 `: the loopback port the page allows for the bridge - `--pair`: print the pairing document for the page's connection dialog - `--controller `: attach through an existing controller descriptor instead of starting a bridge - `--descriptor `: 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 `: run on this local backend instead of the session's - `--around `: source lines to include on each side of the stop ### waxdbg continue Resume forward execution until next pause or completion. - `--around `: source lines to include on each side of the stop ### waxdbg step Resume until the next statement, entering calls. - `--around `: 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 `: source lines to include on each side of the stop ### waxdbg out Resume until execution exits the current logical depth. - `--around `: source lines to include on each side of the stop ### waxdbg pause Request a cooperative pause while execution is running. - `--endpoint `: the live app's WAX_DEBUG_LISTEN socket - `--timeout `: how long to wait for the stop - `--around `: 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, :, with the path relative to the project - `--around `: source lines to include on each side of the stop ### waxdbg break add Set a source breakpoint. - Operand `location` (required): a source position, :, with the path relative to the project - `--if `: arm only when the expression holds ### waxdbg break clear Clear one source breakpoint and any stale condition. - Operand `location` (optional): a source position, :, 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, @. or static. ### 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, @. or static. ### 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/` relative to the debugger page. - Operand `output` (required): the .wxs file to write - `--frames `: how many frames to record - `--inputs `: typed channel initial values and per-frame inputs - `--keyframe-interval `: take a keyframe every K frames - `--include-keyframes`: store keyframes in the recording - `--no-compress`: write the recording uncompressed - `--profile`: write .profile.json from the same frames - `--profile-include `: profile only the functions matching this pattern - `--profile-exclude `: 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 `: 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 `: the frame to replay the edited build through ### waxdbg source materialize Mirror the attached target source bundle to a local directory. - `--output `: where to write the sources ### waxdbg agent bootstrap Create a local agent workspace for an attached browser target. - `--output `: where to write the briefing - `--around `: 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 `: how the client is named in the audit log - `--grant ` (repeatable): grant an effect for the session; repeatable - `--grant-ttl-seconds `: how long a grant lasts - `--command-timeout-ms `: 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 `: the frame to land on - `--break-on-frame ` (repeatable): seed the match queue with this frame; repeatable - `--around `: 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 `: 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 `: 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 `: 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 `: 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 `: 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 `: 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 `: one frame - `--range `: 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 `: the frame to inspect - `--range `: sweep an inclusive frame range, A: or :B leaving that end open (JSON only) - `--object <@ID>`: narrow to one object - `--depth `: how many levels of nested objects to render - `--fields `: 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 `: 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 ` (repeatable): a query source file; repeatable - `--query-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 ` (repeatable): a query source file; repeatable - `--query-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 `: 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 `: the frame to query - `--name ` (repeatable): the query root to run - `--file ` (repeatable): a query source file; repeatable - `--query-dir ` (repeatable): a directory of query sources; repeatable - `--no-query-library`: leave out the bound project's query library - `--args `: query arguments as inline JSON - `--args-file `: query arguments read from a JSON file - `--range `: an inclusive frame range; A: or :B leaves that end open - `--edges `: report where a column crosses - `--reduce `: reduce a column over the range - `--ranges `: report the frame ranges where a column holds - `--where `: report the frames where a column holds - `--workers `: how many workers to scan with - `--ndjson`: print one JSON object per line - `--output `: 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 `: the investigation to run - `--member `: the member to run - `--case `: the case to run - `--file ` (repeatable): a query source file; repeatable - `--query-dir ` (repeatable): a directory of query sources; repeatable - `--no-query-library`: leave out the bound project's query library - `--args `: query arguments as inline JSON - `--args-file `: query arguments read from a JSON file - `--workers `: how many workers to replay with - `--bare`: print the value alone - `--output `: 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 `: the frame whose heap to walk - `--sort `: 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 `: an inclusive frame range; A: or :B leaves that end open - `--depth `: 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 `: 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 `: 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 `: 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, @. ### waxdbg recording diff Read frame-to-frame diff artifact. - Operand `recording` (required): the .wxs recording to read - `--range `: the two frames to compare, inclusive - `--object <@ID>` (repeatable): narrow to this object; repeatable - `--depth `: 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 `: a boolean Wax expression over the frame - `--name `: a catalogued query root - `--query `: the root inside a single --file - `--file ` (repeatable): a query source file; repeatable - `--query-dir ` (repeatable): a directory of query sources; repeatable - `--no-query-library`: leave out the bound project's query library - `--args `: query arguments as inline JSON - `--args-file `: query arguments read from a JSON file - `--retain-mutations`: keep mutations between frames - `--range `: 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 `: stop after N matches; coverage reports whether the range was exhausted - `--around `: 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 `: the frame to evaluate at - `--type `: the expression's type: i32, u32, i64, u64, f32, f64, bool, string or object - `--file `: an authored query source instead of an inline expression - `--query `: the query root to select when --file declares several - `--args `: query arguments as inline JSON - `--args-file `: query arguments read from a JSON file - `--depth `: 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.