# Command line reference `wai` is WAI's command line. This page lists every operation of the toolchain, generated from its operation catalogue, [/ops.json](/ops.json) (format `wai.ops/1`), as the open-standards repository holds it at commit `f6bfd71ca9e5`. `wai ops list`, `wai ops search ""` and `wai ops show ` read, offline, the catalogue the binary you run carries. Each operation is named `noun.verb`, and each command also answers to `wai `. Each is stable (changed only with a deprecation window) or preview (published and working; its shape may still change), and names the toolchain version that first carries it: a release carries the operations up to its own version, and a build from source at the commit above carries every one ([the quickstart](/docs/quickstart/) installs either). ## Agent rules Every command keeps them. With `--json`, standard output holds one envelope (`envelope/1`) and logs stay on standard error. | Exit | Meaning | |---|---| | 0 | Done; every check held. | | 1 | Ran, and a check failed. | | 2 | Usage error or invalid input. | | 3 | Authentication or permission. | | 4 | Confirmation required; nothing changed. | | 5 | Not found (file, target, room, operation). | | 6 | Target unavailable; safe to retry. | | 7 | Internal error. | | Flag | What it does | |---|---| | `--json` | One JSON envelope on stdout: {"wai": "envelope/1", "op", "ok", "data" \| "error"}. | | `--dry-run` | Write nothing and send nothing; say what would be done (an operation that only reads ignores it). | | `--yes` | Confirm a change that waits for confirmation; off a terminal, without it, exit 4. Also `--confirm`, deprecated since 0.3.0 (use `--yes`). | | `--no-input` | Never ask: a change that waits for confirmation exits 4 unless --yes is given. | ## Commands Each command, by toolset: what it does, its synopsis and its arguments. ### Core (toolset `core`) #### `wai hello` WAI's four steps (name, dispatch, rebuild, receipt) on a picture made here, its receipt checked offline. `toolchain.test` · stable · since 0.3.0 · runs on this machine, touching nothing else · writes files on this machine · takes `--dry-run` · waits for `--yes` before it replaces a file the command line did not name · writes a signed record a `verify` operation checks · needs the build feature `quickstart` · also `wai toolchain test` ```text wai hello [] WAI's four steps (name, dispatch, rebuild, receipt) on a sample, written to (wai-hello) ``` - ``, path: Where the object and its receipts are written (wai-hello). #### `wai create` A new project from one of the examples, written into a new or empty directory; --list names the templates. `project.create` · stable · since 0.3.0 · runs on this machine, touching nothing else · writes files on this machine · takes `--dry-run` · waits for `--yes` before it replaces a file the command line did not name · also `wai project create` ```text wai create --template | create --list a new project from one of the examples ``` - ``, path: A directory that does not exist or is empty. - `--template`, string: The template, one of `wai create --list`. - `--list`, boolean: List the templates instead. #### `wai lock` wai.lock written beside wai.json: everything whose bytes change a result pinned by digest, the same bytes on any host; --check refuses a stale or edited lock. `project.lock` · preview · since 0.5.0 · runs on this machine, touching nothing else · writes files on this machine · takes `--dry-run` · also `wai project lock` · the MCP tool `project_lock` ```text wai lock [] [--check] [--root ] [--packer BIN] write wai.lock; --check holds it to what it pins, exit 1 when it is stale or was edited ``` - ``, path: The project's directory (.). - `--check`, boolean: Write nothing: hold the file to what it pins. - `--root`, path: The wai/ directory of a checkout of the standard, for the corpora conform.suites names (found from the current directory otherwise). - `--packer`, path: wai-pack, for the policy package.policy names ($WAI_PACK_BIN, beside wai, or on PATH otherwise). #### `wai check` A project validated without building it: wai.json, each file it states, its app, and wai.lock against what it pins, every finding reported; what could not run says not checked. `project.check` · preview · since 0.5.0 · runs on this machine, touching nothing else · reads only · also `wai project check` · the MCP tool `project_check` ```text wai check [] [--root ] [--packer BIN] exit 1 when a check failed, 5 when none failed and one or more could not run ``` - ``, path: The project's directory (.). - `--root`, path: The wai/ directory of a checkout of the standard, for the corpora conform.suites names (found from the current directory otherwise). - `--packer`, path: wai-pack, for the policy package.policy names ($WAI_PACK_BIN, beside wai, or on PATH otherwise). #### `wai build` dist/ written for a project whose checks hold: the same bytes from the same project and lock, with a build record naming the digests of wai.json and wai.lock. `project.build` · preview · since 0.5.0 · runs on this machine, touching nothing else · writes files on this machine · takes `--dry-run` · waits for `--yes` before it replaces a file the command line did not name · also `wai project build` · the MCP tool `project_build` ```text wai build [] [--key ] [--packer BIN] [--root ] write dist/; refused, nothing written, when a check fails or the lock is stale ``` - ``, path: The project's directory (.). - `--key`, path: The seed file (64 hexadecimal digits) that signs a package's receipt, for a project with package. - `--packer`, path: wai-pack, for a project with package ($WAI_PACK_BIN, beside wai, or on PATH otherwise). - `--root`, path: The wai/ directory of a checkout of the standard, for the corpora conform.suites names (found from the current directory otherwise). #### `wai verify` Every receipt index (*.wai.receipts) under each path, its group receipts and claims checked offline, and every conformance result, fleet report bundle and envelope there. `receipt.verify` · stable · since 0.3.0 · runs on this machine, touching nothing else · reads only · needs the build feature `quickstart` · also `wai receipt verify` · the MCP tool `receipt_verify` ```text wai verify ... [--conformant [--root ]] the receipts (receipt indexes *.wai.receipts), conformance results (*.wai-conform.json), fleet report bundles (*.wai-fleet.json) and envelopes' pins (*.wai) under each path, checked offline; --conformant admits a result only for a run that passed against this checkout's corpus, and gives each area the results' suites are in a verdict ``` - ``, list of string, required: Files or directories holding receipt indexes, conformance results, fleet report bundles or envelopes. - `--conformant`, boolean: Admit each conformance result only when its run passed, against the corpus of a checkout. - `--root`, path: With --conformant, the wai/ directory of the checkout whose corpus a result names. #### `wai inspect` What an envelope holds and whether this build decodes it: media, intent, pin, capability, fallback, the dispatch verdict and the conformance checks. `envelope.inspect` · stable · since 0.3.0 · runs on this machine, touching nothing else · reads only · also `wai envelope inspect` · the MCP tool `envelope_inspect` ```text wai inspect what a WAI1 or WAI2 envelope holds, and the verdict of SPEC §4's dispatch here ``` - ``, path, required: A .wai envelope. #### `wai wrap` Carry a registered capability's bytes in an envelope, byte for byte, under SPEC's intent, role and candidate rules. `envelope.wrap` · stable · since 0.3.0 · runs on this machine, touching nothing else · writes files on this machine · takes `--dry-run` · waits for `--yes` before it replaces a file the command line did not name · also `wai envelope wrap` · the MCP tool `envelope_wrap` ```text wai wrap [-o out.wai] [--fallback ] [--intent ] [--companion ]... WAI2: companions bound to the payload ``` - ``, string, required: A registered capability (`wai capabilities`). - ``, path, required: The bytes to carry. - `-o` (`out`), path: The envelope (out.wai). - `--fallback`, string: A WAI1 fallback capability. - `--intent`, string: The envelope's intent (replicate where SPEC §7 allows it). - `--companion`, list of string: A companion capability and its payload, bound to the payload. #### `wai unwrap` An envelope's capability and its checks, and with -o its payload or one component, exactly as wrapped. `envelope.unwrap` · stable · since 0.3.0 · runs on this machine, touching nothing else · writes files on this machine · takes `--dry-run` · waits for `--yes` before it replaces a file the command line did not name · also `wai envelope unwrap` ```text wai unwrap [-o payload] [--component ] extract any registered capability's bytes ``` - ``, path, required: A .wai envelope. - `-o` (`out`), path: Where the payload is written. - `--component`, integer: A WAI2 component's index. #### `wai encode` Encode a file with a codec this build holds, in an envelope; AVC and HEVC through the device's own encoders, with a signed record. `media.encode` · stable · since 0.3.0 · runs on this machine, touching nothing else · writes files on this machine · takes `--dry-run` · waits for `--yes` before it replaces a file the command line did not name · writes a signed record a `verify` operation checks · needs one of the build features `floor`, `codecs`, `platform_encode` · also `wai media encode` ```text wai encode [-o out.wai] [-q quality] codecs: png jpeg avif jxl jxl-lossless opus flac av1 av1-lossless zstd xz a build with `floor` alone encodes png and zstd; the others need `codecs` image codecs: .rgb (with .meta holding 'H W') or a PNG/JPEG file; audio: .f32 (raw mono float32) with .meta holding the sample rate; video: packed RGB frames with .meta 'N H W fps_num fps_den'; text codecs: any file wai encode avc|hevc [-o out.wai] [--encoder auto|platform|va|gpu-driver|software] [--library ] [--device ] [--hardware yes|no] [--kbps ] [--size WxH] [--idr-every | --idr-plan ] [--es ] [--record --key ] [--meter [--rounds ]] (a build with `platform_encode`) ``` - ``, string, required: png, jpeg, avif, jxl, jxl-lossless, opus, flac, av1, av1-lossless, zstd, xz; or avc, hevc. - ``, path, required: The file to encode. - `-o` (`out`), path: The envelope (out.wai). - `-q` (`quality`), integer: Quality, 1 to 100 (75). #### `wai decode` Decode an envelope through SPEC §4's dispatch to raw samples, with a .meta file beside them. `media.decode` · stable · since 0.3.0 · runs on this machine, touching nothing else · writes files on this machine · takes `--dry-run` · waits for `--yes` before it replaces a file the command line did not name · needs one of the build features `floor`, `codecs` · also `wai media decode` ```text wai decode -o a build with `floor` decodes png, flac and zstd; `codecs` the rest ``` - ``, path, required: A .wai envelope. - `-o` (`out`), path, required: The decoded samples. #### `wai generate` Make a wai.generate.spectral picture natively and print its SHA-256, or write its instruction object. `media.generate` · stable · since 0.3.0 · runs on this machine, touching nothing else · writes files on this machine · takes `--dry-run` · waits for `--yes` before it replaces a file the command line did not name · needs the build feature `generate` · also `wai media generate` ```text wai generate --model (--prompt --seed --steps | --instr ) --size WxH -o make a wai.generate.spectral picture (RGB8) and print its SHA-256; --sizes WxH,... --write-instr writes the instruction object of form v0 (SPEC §5) ``` - `--model`, path, required: The model file. - `--prompt`, string: The prompt. - `--seed`, integer: The seed. - `--steps`, integer: The steps. - `--instr`, path: An instruction object of form v0. - `--size`, string: WxH. - `-o` (`out`), path: The picture, RGB8. #### `wai identify` What a file is, from its bytes alone: the formats they fit with the bytes that say so, its tracks, its protection, and measures where no format is recognised. `media.inspect` · stable · since 0.3.0 · runs on this machine, touching nothing else · reads only · needs the build feature `identify` · also `wai media inspect` · the MCP tool `media_inspect` ```text wai identify [--json] any file, not only an envelope (extensions/media-identify.md); unknown stays unknown ``` - ``, path, required: Any file. #### `wai upscale run` Upscale a PNG exactly, by an integer network under a pinned prior, with a signed record a verifier recomputes. `media.upscale` · stable · since 0.3.0 · runs on this machine, touching nothing else · writes files on this machine · takes `--dry-run` · waits for `--yes` before it replaces a file the command line did not name · writes a signed record a `verify` operation checks · needs the build feature `exact_upscale` · also `wai media upscale` ```text wai upscale run --prior [--derivation sr2|sr4] -o [--record --envelope --key ] [--issued-at ] [--json] an 8-bit RGB PNG; --record signs what exact-upscale §7 recomputes from --envelope and the prior ``` - ``, path, required: An 8-bit RGB PNG. - `--prior`, path, required: The WSR1 prior. - `--derivation`, string: sr2 (the default) or sr4. - `-o` (`out`), path, required: The picture, a PNG. - `--record`, path: The signed upscale record. - `--envelope`, path: The WAI1 of the input, which the record names. - `--key`, string: The record's signing key: its name in the keystore (wai key list), 64 hexadecimal digits, or a file holding them. #### `wai upscale verify` An upscale record recomputed from its input and its prior, and the picture held to it. `upscale.verify` · stable · since 0.3.0 · runs on this machine, touching nothing else · reads only · needs the build feature `exact_upscale` ```text wai upscale verify --envelope --prior [--picture ] the record's outcome as JSON (extensions/exact-upscale.md §7, under require-proof); exit 1 when it is refused ``` - ``, path, required: The upscale record. - `--envelope`, path, required: The WAI1 of the input, which the record names. - `--prior`, path, required: The WSR1 prior the record names. - `--picture`, path: The picture: its samples are held to the record's output. #### `wai tonemap run` Render a still's gain map exactly at the headrooms named, with a signed record a verifier recomputes. `media.tonemap` · stable · since 0.3.0 · runs on this machine, touching nothing else · writes files on this machine · takes `--dry-run` · waits for `--yes` before it replaces a file the command line did not name · writes a signed record a `verify` operation checks · needs the build feature `exact_tonemap` · also `wai media tonemap` ```text wai tonemap run --headrooms --out [--input-class ] [--record --key ] [--issued-at ] [--json] a WAI2 of a PNG base and its gain map; a headroom is in 1/10000 of a stop; each rendition is RGB16 ``` - ``, path, required: A WAI2 of a PNG base and its gain map. - `--headrooms`, string, required: The headrooms, in 1/10000 of a stop, joined by commas. - `--out`, path, required: The directory the renditions are written in. - `--input-class` (`input_class`), string: The input's class (captured). - `--record`, path: The signed rendition record. - `--key`, string: The record's signing key: its name in the keystore (wai key list), 64 hexadecimal digits, or a file holding them. #### `wai tonemap verify` A rendition record recomputed from its envelope, and the renditions held to it. `tonemap.verify` · stable · since 0.3.0 · runs on this machine, touching nothing else · reads only · needs the build feature `exact_tonemap` ```text wai tonemap verify --envelope [--renditions ] the record's outcome as JSON (extensions/exact-tonemap.md §8, under require-proof); exit 1 when it is refused ``` - ``, path, required: The rendition record. - `--envelope`, path, required: The WAI2 the record names. - `--renditions`, path: The directory `wai tonemap run` wrote: each rendition is held to its picture. #### `wai score build` A WSCR score from integer note fields. `score.build` · stable · since 0.3.0 · runs on this machine, touching nothing else · writes files on this machine · takes `--dry-run` · waits for `--yes` before it replaces a file the command line did not name · needs the build feature `score` ```text wai score build -o a WSCR from integer note fields ``` - ``, path, required: The note fields, JSON. - `-o` (`out`), path, required: The score. #### `wai score render` A score's reference mixdown and its digests (pcm_sha256, mixdown_blake3, score_hash). `score.decode` · stable · since 0.3.0 · runs on this machine, touching nothing else · writes files on this machine · takes `--dry-run` · waits for `--yes` before it replaces a file the command line did not name · needs the build feature `score` · also `wai score decode` ```text wai score render [--pcm ] the reference mixdown and its digests ``` - ``, path, required: A WSCR score. - `--pcm`, path: Where the mixdown is written. #### `wai encoders` What each encoder interface offers on this device, for AVC and HEVC. `encoder.list` · preview · since 0.3.0 · runs on this machine, touching nothing else · reads only · needs the build feature `platform_encode` · also `wai encoder list` ```text wai encoders [--library ] what each encoder interface offers here ``` - `--library`, path: A software encoder library. #### `wai encode-record verify` A signed encode record checked, against the stream and its source where given. `encoder.verify` · preview · since 0.3.0 · runs on this machine, touching nothing else · reads only · needs the build feature `platform_encode` · also `wai encoder verify` ```text wai encode-record verify [--stream ] [--source ] ``` - ``, path, required: The signed record. - `--stream`, path: The elementary stream it names. - `--source`, path: The source it names. #### `wai package build` A package packed by the reference packager wai-pack from a policy, a source per component and a supplied floor, with its signed package receipt. `package.build` · preview · since 0.3.0 · runs on this machine, touching nothing else · writes files on this machine · takes `--dry-run` · waits for `--yes` before it replaces a file the command line did not name · writes a signed record a `verify` operation checks ```text wai package build --policy --out --key [--source =]... [--floor ] [--signer-id ] [--meter none|model:] [--packer ] [wai-pack pack's other flags] the reference packager's pack (extensions/packaging.md): the policy's components packed into , new or empty, with the package receipt (package.receipt.json); the packer is --packer, $WAI_PACK_BIN, wai-pack beside wai, or wai-pack on PATH ``` - `--policy`, path, required: The packaging policy (extensions/packaging.md §3). - `--out`, path, required: A new or empty directory, written with the package. - `--key`, path, required: The packager's signing key: a 32-byte seed, in hexadecimal. - `--source`, list of string: A component's source, =; each component's own by default. - `--floor`, path: A supplied floor's directory (floor/ beside the policy by default). - `--signer-id` (`signer_id`), string: The receipt's signer id (the key's did:key by default). - `--meter`, string: none, or model:: the meter of the receipt's figure. - `--packer`, path: The packer's binary (wai-pack). #### `wai package verify` A package verified by the reference packager wai-pack: every reason it is refused, or its counts and pack digest. `package.verify` · preview · since 0.3.0 · runs on this machine, touching nothing else · reads only ```text wai package verify [--parent ] [--packer ] the reference packager's verify (extensions/packaging.md §9): the package's receipt, stage indexes, objects and floor; with --parent, a re-pack against the package its receipt names; exit 1 when refused ``` - ``, path, required: The package's directory. - `--parent`, path: The package a re-pack's receipt names. - `--packer`, path: The packer's binary (wai-pack). #### `wai capabilities` Every registered capability with its fidelity, licence class, replicate class and role, and whether this build decodes it. `registry.list` · stable · since 0.3.0 · runs on this machine, touching nothing else · reads only · also `wai registry list` · the MCP tool `registry_list` ```text wai capabilities the registered capabilities, their tier, licence, replicate class and role ``` #### `wai prior-set` The listing of a parameter set (wai.prior.set) on stdout, and its pin on stderr. `prior.list` · stable · since 0.3.0 · runs on this machine, touching nothing else · reads only · also `wai prior list` ```text wai prior-set print the listing of a parameter set (wai.prior.set) and its pin ``` - ``, path, required: The parameter set's directory. #### `wai stage refine` A refinement layer over a base and the layers below it, toward a target. `stage.encode` · preview · since 0.3.0 · runs on this machine, touching nothing else · writes files on this machine · takes `--dry-run` · waits for `--yes` before it replaces a file the command line did not name · needs the build features `staged`, `video_int`, `audio_int`, `splat_int` · also `wai stage encode` ```text wai stage refine --base [--on ]... --toward --q N [--predictor identity|up2|rate:NUM/DEN] [--span F:C] [--out-dims D0,D1,D2] [--max-symbols N] [--table-per-unit] -o L.wai ``` - `--base`, path, required: The base envelope. - `--toward`, path, required: The samples the layer refines toward (--target, deprecated, is the same). - `--q`, integer, required: The quantiser. - `-o` (`out`), path, required: The layer. #### `wai stage apply` Envelopes taken in order: each layer offered, each base decoded and refined, with each report and the units. `stage.decode` · preview · since 0.3.0 · runs on this machine, touching nothing else · reads only · needs the build features `staged`, `video_int`, `audio_int`, `splat_int` · also `wai stage decode` ```text wai stage apply ... each layer offered, a base decoded (SPEC §4) and refined; the reports and units, or a JSON trace ``` - ``, list of string, required: The base, then its layers. #### `wai stage base` A wai.video.int_motion base of N frames of RGB8 (WIV1, keyframe 0, zero motion). `stage.build` · preview · since 0.3.0 · runs on this machine, touching nothing else · writes files on this machine · takes `--dry-run` · waits for `--yes` before it replaces a file the command line did not name · needs the build features `staged`, `video_int`, `audio_int`, `splat_int` · also `wai stage build` ```text wai stage base --frames --dims N,H,W --q Q -o base.wai ``` - `--frames`, path, required: The frames, packed RGB8. - `--dims`, string, required: N,H,W. - `--q`, integer, required: The quantiser. - `-o` (`out`), path, required: The base envelope. #### `wai stage inspect` A refinement layer's refines, its WIR1 header and its declared cost. `stage.inspect` · preview · since 0.3.0 · runs on this machine, touching nothing else · reads only · needs the build features `staged`, `video_int`, `audio_int`, `splat_int` ```text wai stage inspect ``` - ``, path, required: A layer envelope. #### `wai stage pack` WAI1 envelopes packed into one WAI2, their manifests verbatim. `stage.wrap` · preview · since 0.3.0 · runs on this machine, touching nothing else · writes files on this machine · takes `--dry-run` · waits for `--yes` before it replaces a file the command line did not name · needs the build features `staged`, `video_int`, `audio_int`, `splat_int` · also `wai stage wrap` ```text wai stage pack ... -o x.wai ``` - ``, list of string, required: The base, then its layers. - `-o` (`out`), path, required: The WAI2 envelope. #### `wai stage explode` One component of a WAI2 envelope as its WAI1 envelope. `stage.unwrap` · preview · since 0.3.0 · runs on this machine, touching nothing else · writes files on this machine · takes `--dry-run` · waits for `--yes` before it replaces a file the command line did not name · needs the build features `staged`, `video_int`, `audio_int`, `splat_int` · also `wai stage unwrap` ```text wai stage explode [-o out.wai] ``` - ``, path, required: A WAI2 envelope. - ``, integer, required: The component's index. - `-o` (`out`), path: The WAI1 envelope. #### `wai http publish` Envelopes named by their content hash, each with its head proof and entity tag, ready for an origin. `http.export` · preview · since 0.3.0 · runs on this machine, touching nothing else · writes files on this machine · takes `--dry-run` · waits for `--yes` before it replaces a file the command line did not name · needs the build feature `http` · also `wai http export` ```text wai http publish ... --out ``` - ``, list of string, required: The envelopes. - `--out`, path, required: The directory. #### `wai http codecs` The codecs parameter a sequence of envelopes advertises: its union and its floor. `http.inspect` · preview · since 0.3.0 · runs on this machine, touching nothing else · reads only · needs the build feature `http` · also `wai http inspect` ```text wai http codecs ... ``` - ``, list of string, required: The envelopes. #### `wai http origin` An origin on loopback serving a published directory with http-delivery's headers, ranges and If-Range. `http.start` · preview · since 0.3.0 · runs on this machine, touching nothing else · runs something and writes only its own state · takes `--dry-run` · waits for `--yes` before it replaces a file the command line did not name · needs the build feature `http` · also `wai http start` ```text wai http origin --root [--port P] [--delay-range FIRST-LAST:MS] ``` - `--root`, path, required: The published directory. - `--port`, integer: The port on 127.0.0.1. #### `wai http hls` An HLS rendition of published objects. `hls.build` · preview · since 0.3.0 · runs on this machine, touching nothing else · writes files on this machine · takes `--dry-run` · waits for `--yes` before it replaces a file the command line did not name · needs the build feature `http` · also `wai hls build` ```text wai http hls --objects --out [--master NAME] ``` - `--objects`, path, required: The objects, JSON. - `--out`, path, required: The directory. #### `wai http mpd` A DASH manifest of published objects. `dash.build` · preview · since 0.3.0 · runs on this machine, touching nothing else · writes files on this machine · takes `--dry-run` · waits for `--yes` before it replaces a file the command line did not name · needs the build feature `http` · also `wai dash build` ```text wai http mpd --objects --out [--period-id ID] [--set-id N] ``` - `--objects`, path, required: The objects, JSON. - `--out`, path, required: The manifest. #### `wai http seal-playlist` A media playlist sealed with a signed manifest receipt. `playlist.lock` · preview · since 0.3.0 · runs on this machine, touching nothing else · writes files on this machine · takes `--dry-run` · waits for `--yes` before it replaces a file the command line did not name · writes a signed record a `verify` operation checks · needs the build features `http`, `video_manifest` · also `wai playlist lock` ```text wai http seal-playlist --key [--signer-id ID] [--content-id ID] [--parent ] [--out ] ``` - ``, path, required: The playlist. - `--key`, string, required: The signing key: its name in the keystore (wai key list), 64 hexadecimal digits, or a file holding them. #### `wai http check-playlist` A media playlist checked against its manifest receipt. `playlist.verify` · preview · since 0.3.0 · runs on this machine, touching nothing else · reads only · needs the build features `http`, `video_manifest` · also `wai playlist verify` ```text wai http check-playlist --receipt [--parent ] [--classical ] ``` - ``, path, required: The playlist. - `--receipt`, path, required: Its manifest receipt. #### `wai http bench` An object fetched by the byte-range procedure, repeatedly, and the record of each run. `http.load` · preview · since 0.3.0 · runs on this machine, against a service it names · writes files on this machine · takes `--dry-run` · waits for `--yes` before it replaces a file the command line did not name · needs the build feature `http` · also `wai http load` ```text wai http bench --url URL --runs N --advertise CAP [--advertise CAP]... --out F ``` - `--url`, string, required: The object's URL. - `--runs`, integer, required: How many runs. - `--advertise`, list of string, required: A capability this sink advertises. - `--out`, path, required: The record. #### `wai http receipts` An object's receipt index fetched over HTTP and checked, its signers confirmed under the origin's key log where named. `receipt.fetch` · preview · since 0.3.0 · runs on this machine, against a service it names · reads only · needs the build features `http`, `receipt_claims` · also `wai receipt fetch` ```text wai http receipts --url URL [--advertise CAP]... [--held fetch|none] [--join] [--max-walk N] [--fetch-budget N] [--deadline-ms MS] [--key-origin https://HOST[:PORT] [--pin-key-log FILE | --test-plaintext-connect HOST:PORT]] ``` - `--url`, string, required: The object's URL. #### `wai breaking` What the working tree breaks against a git ref, by category (wire, record, api); a break passes once the CHANGELOG names it. `compat.check` · stable · since 0.3.0 · runs on this machine, touching nothing else · reads only · also `wai compat check` ```text wai breaking --against [--category wire|record|api] [--only ,...] [--skip ,...] [--root ] [--target-dir ] [--all] exit 1 on a break the CHANGELOG does not acknowledge ``` - `--against`, string, required: The git ref to compare with. - `--category`, string: wire, record or api: the categories checked, cumulative (api). - `--only`, string: Only these surfaces, comma-separated. - `--skip`, string: Not these surfaces, comma-separated. - `--root`, path: The repository's root (.). - `--target-dir` (`target_dir`), path: Where the Rust API's description is built. - `--all`, boolean: List every finding, compatible ones too. #### `wai conform` WAI's conformance corpus run against another implementation, through a command or an HTTP adapter, or every corpus's independent verifier; each result a signed record wai verify checks. `conformance.run` · stable · since 0.3.0 · runs on this machine, touching nothing else · writes files on this machine · takes `--dry-run` · waits for `--yes` before it replaces a file that exists · writes a signed record a `verify` operation checks · needs the build feature `quickstart` · also `wai conformance run` · the MCP tool `conformance_run` ```text wai conform --suite --impl [--independent] [--key ] [--out ] [--root ] [--timeout ] [--name ] [--version ] [--python ] [--all] [--level required|all] [--format text|json|junit|html] [--yes] `wai conformance list` names the kinds and suites; --independent runs the corpus's independent verifier beside the implementation, and both must conform; a case is required unless its corpus marks it informative, and --level all counts every case wai conform --independent [--suite [,...]] [--out ] [--key ] [--root ] [--timeout ] [--python ] [--format text|json|junit|html] [--yes] every corpus's independent verifier (or those named), a record each in ; a record that exists is replaced only with --yes (--confirm, deprecated, is the same) ``` - ``, string: The kind of implementation (wai conformance list): a decoder, a verifier, an origin, a cache, a packager, a sink; none with --independent alone. - `--suite`, string: The suite (wai conformance list); with --independent alone, areas and independent verifiers, comma-separated. - `--impl`, string: The implementation: a command with {case}/{in}/{out}/{corpus}/{model} placeholders (a cache's: {port} and {origin}), or a URL; required with a kind. - `--independent`, boolean: Run the corpus's independent verifier beside the implementation, held to the same cases; without a kind, every independent verifier. - `--key`, path: The seed the records are signed with. - `--out`, path: The record (.wai-conform.json); with --independent alone, a directory for a record a corpus. - `--root`, path: The wai/ directory whose corpora are run. - `--timeout`, integer: Seconds a case may take (60), or an independent verifier its whole corpus (1800). - `--name`, string: The implementation's name, for the record. - `--version`, string: The implementation's version, for the record. - `--python`, string: The Python the independent verifiers run with (python3). - `--format`, string: What is printed: text, json (the envelope, as --json), junit (JUnit XML) or html, the last two from the records. - `--all`, boolean: List every case, passed ones too. - `--level`, string: required (the default: a case the corpus marks informative is reported, not counted) or all (every case counted); for a suite whose corpus marks a case informative. #### `wai conformance list` The kinds and suites wai conform runs, each suite's corpus and its cases, and every corpus's independent verifier. `conformance.list` · stable · since 0.3.0 · runs on this machine, touching nothing else · reads only · needs the build feature `quickstart` · the MCP tool `conformance_list` ```text wai conformance list [--root ] the kinds and suites, and the independent verifiers (also wai conform --list) ``` - `--root`, path: The wai/ directory whose corpora are listed. #### `wai enrolment create` A node's enrolment signed with the organisation key, written to a file and, with --target, given to a fleet service. `enrolment.create` · preview · since 0.3.0 · runs on this machine, against a service it names · changes a target that is not this machine · takes `--dry-run` · waits for `--yes` before it changes the target it names or replaces a file that exists · writes a signed record a `verify` operation checks · needs the build feature `fleet` ```text wai enrolment create --role --key [--label L] [--from µs] [--until µs] [--out F] [--target ] [--yes] a node's enrolment (WFE1), signed with the organisation key, written to F (.wfe without --target) and, with --target, given to the fleet service it names (never to the target in use unless named); changing the service or replacing a file waits for --yes (--confirm, deprecated, is the same) ``` - ``, string, required: The node's Ed25519 public key, 64 hexadecimal digits. - `--role`, string, required: relay, compositor, ingest, room, ledger or audit. - `--key`, string, required: The organisation key: its name in the keystore (wai key list), or its file: 32 bytes, or 64 hexadecimal digits. - `--label`, string: The node's label, at most 64 bytes. - `--from`, integer: The start of the span it holds, microseconds since 1970 (0). - `--until`, integer: The end of that span, microseconds since 1970 (none). - `--out`, path: The enrolment's file (.wfe when no --target is given). - `--target`, string: The service it acts on: a target's name (wai target list) or a service's http:// or https:// address. #### `wai enrolment list` The nodes a fleet service holds enrolled, each with its role, label and how many records it gave. `enrolment.list` · preview · since 0.3.0 · runs on this machine, against a service it names · reads only ```text wai enrolment list [--target ] the nodes the fleet service holds enrolled (the target in use when none is named) ``` - `--target`, string: The service it acts on: a target's name (wai target list) or a service's http:// or https:// address. #### `wai report create` The fleet report of a period, signed by a fleet service over the enrolments and records it holds. `report.create` · preview · since 0.3.0 · runs on this machine, against a service it names · changes a target that is not this machine · takes `--dry-run` · waits for `--yes` every time it changes something · writes a signed record a `verify` operation checks ```text wai report create [--target ] --start µs --end µs [--yes] the fleet report of [start, end), signed by the fleet service (the target in use when none is named); it changes the service, so it waits for --yes (--confirm, deprecated, is the same) ``` - `--target`, string: The service it acts on: a target's name (wai target list) or a service's http:// or https:// address. - `--start`, integer, required: The period's start, microseconds since 1970. - `--end`, integer, required: The period's end, after its start. #### `wai report export` A fleet report's bundle fetched from a fleet service, its report recomputed here, then written to a file. `report.export` · preview · since 0.3.0 · runs on this machine, against a service it names · writes files on this machine · takes `--dry-run` · waits for `--yes` before it replaces a file that exists · writes a signed record a `verify` operation checks · needs the build feature `fleet` ```text wai report export [--target ] [--out F] [--yes] the report's bundle from the fleet service (the target in use when none is named), recomputed by this build and written to F (.wai-fleet.json) for `wai verify`; replacing a file waits for --yes (--confirm, deprecated, is the same) ``` - ``, string, required: The report's digest, 64 hexadecimal digits. - `--target`, string: The service it acts on: a target's name (wai target list) or a service's http:// or https:// address. - `--out`, path: The bundle's file (.wai-fleet.json). #### `wai route verify` A route record checked offline against its request, price book and routing policy, and against its hops' OER/2 receipts where given. `route.verify` · preview · since 0.3.0 · runs on this machine, touching nothing else · reads only · needs the build feature `route_record` ```text wai route verify a verification document (extensions/route-record.md §7.1): the record's outcome (§7.3) as JSON, recomputed from the request, the price book and the policy; exit 1 when it is refused ``` - ``, path, required: The verification document: the request, price book, policy and record, and the hops' receipts. #### `wai channel import` A linear channel's feeds (an XMLTV schedule, Media RSS catalogues or the JSON form, and a Media Playlist's SCTE-35 date ranges) imported into its signed receipt, its signed lineup and its breaks' cues. `channel.import` · preview · since 0.3.0 · runs on this machine, touching nothing else · writes files on this machine · takes `--dry-run` · waits for `--yes` before it replaces a file that exists · writes a signed record a `verify` operation checks · needs the build feature `channel_lineup` ```text wai channel import --channel ID (--xmltv F [--mrss F]... | --mrss F... | --feed F) [--playlist F] --key K [--mrss-owner O]... [--owner O] [--signer-id S] [--id-system N] [--xmltv-channel X] [--start-ms T] [--artwork DIR] [--window-start T --window-end T] [--parent HEX] [--out-dir D] [--yes] the receipt (channel.json), the lineup (lineup.wlu) and the cues (cues.json), written to D (.); a refusal's code is its reason; replacing a file waits for --yes (--confirm, deprecated, is the same) ``` - `--channel`, string, required: The channel id. - `--xmltv`, path: An XMLTV document: the schedule. - `--mrss`, list of string: A Media RSS document: a catalogue. Repeated. - `--mrss-owner` (`mrss_owner`), list of string: The rights holder of each --mrss document's items, in their order: none, or one each. - `--feed`, path: The JSON form of a schedule, its catalogue and its breaks. - `--playlist`, path: The channel's HLS Media Playlist, whose SCTE-35 date ranges are its breaks. - `--key`, string, required: The operator's key: its name in the keystore (wai key list), or its file: 32 bytes, or 64 hexadecimal digits. - `--owner`, string: The rights holder of every asset no other input gives one. - `--signer-id` (`signer_id`), string: The receipt's signer id (the operator key's did:key). - `--id-system` (`id_system`), string: The XMLTV episode-num system that names a programme's asset (wai-asset-id). - `--xmltv-channel` (`xmltv_channel`), string: The XMLTV channel id whose programmes are read (the channel id). - `--start-ms` (`start_ms`), integer: Where a schedule of Media RSS items alone begins, milliseconds since 1970. - `--artwork`, path: The directory holding the artwork files the feeds' icons and thumbnails name. - `--window-start` (`window_start`), integer: The receipt's window's start (the schedule's first start). - `--window-end` (`window_end`), integer: The receipt's window's end (the schedule's last end). - `--parent`, string: The receipt hash of the window before this one, 64 hexadecimal digits. - `--out-dir` (`out_dir`), path: Where channel.json, lineup.wlu and cues.json are written (.). #### `wai channel guide` A channel's guide, an XMLTV document or a now/next document, rendered from its receipt and its lineup and naming both. `channel.guide` · preview · since 0.3.0 · runs on this machine, touching nothing else · writes files on this machine · takes `--dry-run` · waits for `--yes` before it replaces a file that exists · needs the build feature `channel_lineup` ```text wai channel guide --receipt R --lineup L [--from T --to T | --now-next --at T] [--out F] [--yes] the XMLTV guide of a range (the whole schedule), or the now/next document of an instant, written to F (guide.xml, now-next.json); replacing a file waits for --yes (--confirm, deprecated, is the same) ``` - `--receipt`, path, required: The channel receipt, in its JSON carriage. - `--lineup`, path, required: The lineup's file. - `--from`, integer: The range's start, milliseconds since 1970 (the schedule's first start). - `--to`, integer: The range's end (the schedule's last end). - `--now-next` (`now_next`), boolean: The now/next document of --at instead. - `--at`, integer: The instant of a now/next document, milliseconds since 1970. - `--out`, path: The guide's file (guide.xml, or now-next.json). #### `wai channel verify` A channel's receipt, its lineup and a guide verified together: the guide recomputed from the two and compared, each programme with whether it aired. `channel.verify` · preview · since 0.3.0 · runs on this machine, touching nothing else · reads only · needs the build feature `channel_lineup` ```text wai channel verify --receipt R --lineup L [--guide G] the receipt, the lineup and the guide checked together; exit 1 with the reason when one does not verify ``` - `--receipt`, path, required: The channel receipt, in its JSON carriage. - `--lineup`, path, required: The lineup's file. - `--guide`, path: An XMLTV guide or a now/next document. #### `wai mcp` WAI's operations as tools for a coding agent: a Model Context Protocol server on standard input and output, in toolsets. `mcp.start` · preview · since 0.3.0 · runs on this machine, against a service it names · runs something and writes only its own state · takes `--dry-run` · waits for `--yes` before it replaces a file the command line did not name · needs the build feature `mcp` · also `wai mcp start` ```text wai mcp [--toolset core,dev,app] [--read-only] [--project DIR] [--spec-root DIR] [--room-bin BIN] [--target [--allow-write]] serves until standard input closes; --dry-run names the tools it would serve and serves nothing. With --target, the operations of the service's API are tools too, each sent to its route on that target alone: those that read it, and those that change it where the server may (a target on this machine, or another with --allow-write; never with --read-only or to a read-only target) ``` - `--toolset`, string: The toolsets to offer, comma-separated (core when none is named). - `--read-only` (`read_only`), boolean: Offer only the tools that read or run a verifier. - `--project`, path: The directory the server may write in (the current one). - `--spec-root` (`spec_root`), path: The wai/ directory whose text and corpora the tools read. - `--room-bin` (`room_bin`), path: The room service the development room runs. - `--target`, string: The service it acts on: a target's name (wai target list) or a service's http:// or https:// address. - `--allow-write` (`allow_write`), boolean: Offer the tools that change the target where it is on another machine. #### `wai setup-agent` A project made ready for coding agents: AGENTS.md, an import of it in a CLAUDE.md already there, and wai mcp registered in its MCP configuration. `agent.setup` · preview · since 0.3.0 · runs on this machine, touching nothing else · writes files on this machine · takes `--dry-run` · waits for `--yes` before it replaces a file that exists · also `wai agent setup` ```text wai setup-agent [--dir D] [--all] [--only FILE,...] [--toolset core,dev,app] [--command PROGRAM] a file that exists changes only once confirmed (--yes, or yes at a terminal); --dry-run shows each diff ``` - `--dir`, path: The project directory (the current one). - `--all`, boolean: Write every agent's configuration file, not only those whose directory is there. - `--only`, string: Only these files, comma-separated. - `--toolset`, string: The toolsets the registered server offers. - `--command`, string: The program the registration runs (wai). #### `wai registry show` One capability's registry entry, whether this build decodes it, its role, and the specification lines that name it. `registry.show` · stable · since 0.3.0 · runs on this machine, touching nothing else · reads only · needs the build feature `mcp` · the MCP tool `registry_show` ```text wai registry show [--spec-root ] one capability's registry entry, whether this build decodes it, its role, and the specification lines that name it, where the specification's text is here (--spec-root, $WAI_SPEC_ROOT, or the tree this binary was built from) ``` - ``, string, required: A capability string, e.g. wai.image.avif. - `--spec-root` (`spec_root`), path: The wai/ directory whose text is read, on the command line (wai mcp has a --spec-root of its own). #### `wai docs search` Lines of the specification and its extensions holding every word of a query, each with its file, line and section. `docs.search` · stable · since 0.3.0 · runs on this machine, touching nothing else · reads only · needs the build feature `mcp` · the MCP tool `docs_search` ```text wai docs search ... [--limit N] [--spec-root ] the lines of the specification and its extensions that hold every word, with each one's file, line and section, offline; the text is --spec-root's, $WAI_SPEC_ROOT's, or the tree this binary was built from ``` - ``, string, required: Words that must all appear on a line. - `--limit`, integer: At most this many hits (20). - `--spec-root` (`spec_root`), path: The wai/ directory whose text is searched, on the command line (wai mcp has a --spec-root of its own). #### `wai service show` The service's health. `service.show` · preview · since 0.3.0 · runs on a service, through its HTTP route · reads only · `GET /` on `wai-room` ```text wai service show [--target ] [--query =]... GET / on the room service ``` #### `wai service check` The service's health. `service.check` · preview · since 0.3.0 · runs on a service, through its HTTP route · reads only · `GET /health` on `wai-room` ```text wai service check [--target ] [--query =]... GET /health on the room service ``` #### `wai room show` The current room. `room.show` · preview · since 0.3.0 · runs on a service, through its HTTP route · reads only · `GET /room` on `wai-room` ```text wai room show [--target ] [--query =]... GET /room on the room service ``` #### `wai admission show` The room's admission receipt so far. `admission.show` · preview · since 0.3.0 · runs on a service, through its HTTP route · reads only · `GET /age/receipt` on `wai-room` ```text wai admission show [--target ] [--query =]... GET /age/receipt on the room service ``` #### `wai mls tail` The room's log of MLS messages. `mls.tail` · preview · since 0.3.0 · runs on a service, through its HTTP route · reads only · `GET /mls` on `wai-room` ```text wai mls tail [--target ] [--query =]... GET /mls on the room service ``` #### `wai mls import` A KeyPackage for a granted principal's Add. `mls.import` · preview · since 0.3.0 · runs on a service, through its HTTP route · changes a target that is not this machine · takes `--dry-run` · waits for `--yes` every time it changes something · `POST /mls/key-package` on `wai-room` ```text wai mls import [--target ] [--body |@] [--yes] POST /mls/key-package on the room service ``` #### `wai mls update` A GroupInfo, or a commit and its Welcome. `mls.update` · preview · since 0.3.0 · runs on a service, through its HTTP route · changes a target that is not this machine · takes `--dry-run` · waits for `--yes` every time it changes something · `POST /mls/post` on `wai-room` ```text wai mls update [--target ] [--body |@] [--yes] POST /mls/post on the room service ``` #### `wai performance list` The clock's log of objects. `performance.list` · preview · since 0.3.0 · runs on a service, through its HTTP route · reads only · `GET /co/objects` on `wai-room` ```text wai performance list [--target ] [--query =]... GET /co/objects on the room service ``` #### `wai performance show` The room's co-performance as the clock holds it. `performance.show` · preview · since 0.3.0 · runs on a service, through its HTTP route · reads only · `GET /co/state` on `wai-room` ```text wai performance show [--target ] [--query =]... GET /co/state on the room service ``` #### `wai schedule create` A turn schedule the clock signs. `schedule.create` · preview · since 0.3.0 · runs on a service, through its HTTP route · changes a target that is not this machine · takes `--dry-run` · waits for `--yes` every time it changes something · `POST /co/schedule` on `wai-room` ```text wai schedule create [--target ] [--body |@] [--yes] POST /co/schedule on the room service ``` #### `wai handover create` A handover the clock signs. `handover.create` · preview · since 0.3.0 · runs on a service, through its HTTP route · changes a target that is not this machine · takes `--dry-run` · waits for `--yes` every time it changes something · `POST /co/handover` on `wai-room` ```text wai handover create [--target ] [--body |@] [--yes] POST /co/handover on the room service ``` #### `wai window create` A selection window the clock signs. `window.create` · preview · since 0.3.0 · runs on a service, through its HTTP route · changes a target that is not this machine · takes `--dry-run` · waits for `--yes` every time it changes something · `POST /co/window` on `wai-room` ```text wai window create [--target ] [--body |@] [--yes] POST /co/window on the room service ``` #### `wai fidelity create` A fidelity statement now. `fidelity.create` · preview · since 0.3.0 · runs on a service, through its HTTP route · changes a target that is not this machine · takes `--dry-run` · waits for `--yes` every time it changes something · `POST /co/fidelity` on `wai-room` ```text wai fidelity create [--target ] [--body |@] [--yes] POST /co/fidelity on the room service ``` #### `wai time show` The service's clock. `time.show` · preview · since 0.3.0 · runs on a service, through its HTTP route · reads only · `GET /watch/time` on `wai-room` ```text wai time show [--target ] [--query =]... GET /watch/time on the room service ``` #### `wai source fetch` The watch room's source, whole. `source.fetch` · preview · since 0.3.0 · runs on a service, through its HTTP route · reads only · `GET /watch/source` on `wai-room` ```text wai source fetch [--target ] [--query =]... GET /watch/source on the room service ``` #### `wai watch setup` A challenge for a join's proof. `watch.setup` · preview · since 0.3.0 · runs on a service, through its HTTP route · changes a target that is not this machine · takes `--dry-run` · waits for `--yes` every time it changes something · `GET /watch/challenge` on `wai-room` ```text wai watch setup [--target ] [--query =]... [--yes] GET /watch/challenge on the room service ``` #### `wai watch tail` The watch room's log. `watch.tail` · preview · since 0.3.0 · runs on a service, through its HTTP route · reads only · `GET /watch` on `wai-room` ```text wai watch tail [--target ] [--query =]... GET /watch on the room service ``` #### `wai watch show` The room as a co-watch verifier is given it. `watch.show` · preview · since 0.3.0 · runs on a service, through its HTTP route · reads only · `GET /watch/room` on `wai-room` ```text wai watch show [--target ] [--query =]... GET /watch/room on the room service ``` #### `wai watch join` A viewer enters by a proof of its key. `watch.join` · preview · since 0.3.0 · runs on a service, through its HTTP route · changes a target that is not this machine · takes `--dry-run` · waits for `--yes` every time it changes something · `POST /watch/join` on `wai-room` ```text wai watch join [--target ] [--body |@] [--yes] POST /watch/join on the room service ``` #### `wai watch update` A viewer's events, checked and carried in order. `watch.update` · preview · since 0.3.0 · runs on a service, through its HTTP route · changes a target that is not this machine · takes `--dry-run` · waits for `--yes` every time it changes something · `POST /watch/post` on `wai-room` ```text wai watch update [--target ] [--body |@] [--yes] POST /watch/post on the room service ``` #### `wai control grant` The host hands control over. `control.grant` · preview · since 0.3.0 · runs on a service, through its HTTP route · changes a target that is not this machine · takes `--dry-run` · waits for `--yes` every time it changes something · `POST /remote/control` on `wai-room` ```text wai control grant [--target ] [--body |@] [--yes] POST /remote/control on the room service ``` #### `wai remote show` The session as the clock holds it. `remote.show` · preview · since 0.3.0 · runs on a service, through its HTTP route · reads only · `GET /remote/room` on `wai-room` ```text wai remote show [--target ] [--query =]... GET /remote/room on the room service ``` #### `wai remote verify` That session verified. `remote.verify` · preview · since 0.3.0 · runs on a service, through its HTTP route · reads only · `GET /remote/state` on `wai-room` ```text wai remote verify [--target ] [--query =]... GET /remote/state on the room service ``` #### `wai conversation show` The conversation. `conversation.show` · preview · since 0.3.0 · runs on a service, through its HTTP route · reads only · `GET /msg` on `wai-room` ```text wai conversation show [--target ] [--query =]... GET /msg on the room service ``` #### `wai conversation setup` A challenge for a proof. `conversation.setup` · preview · since 0.3.0 · runs on a service, through its HTTP route · changes a target that is not this machine · takes `--dry-run` · waits for `--yes` every time it changes something · `GET /msg/challenge` on `wai-room` ```text wai conversation setup [--target ] [--query =]... [--yes] GET /msg/challenge on the room service ``` #### `wai conversation join` A key that proves itself is admitted. `conversation.join` · preview · since 0.3.0 · runs on a service, through its HTTP route · changes a target that is not this machine · takes `--dry-run` · waits for `--yes` every time it changes something · `POST /msg/join` on `wai-room` ```text wai conversation join [--target ] [--body |@] [--yes] POST /msg/join on the room service ``` #### `wai conversation tail` The log as it is owed to the caller. `conversation.tail` · preview · since 0.3.0 · runs on a service, through its HTTP route · reads only · `GET /msg/log` on `wai-room` ```text wai conversation tail [--target ] [--query =]... GET /msg/log on the room service ``` #### `wai conversation import` A member's KeyPackage. `conversation.import` · preview · since 0.3.0 · runs on a service, through its HTTP route · changes a target that is not this machine · takes `--dry-run` · waits for `--yes` every time it changes something · `POST /msg/key-package` on `wai-room` ```text wai conversation import [--target ] [--body |@] [--yes] POST /msg/key-package on the room service ``` #### `wai conversation update` A GroupInfo, or a commit and its Welcome. `conversation.update` · preview · since 0.3.0 · runs on a service, through its HTTP route · changes a target that is not this machine · takes `--dry-run` · waits for `--yes` every time it changes something · `POST /msg/mls` on `wai-room` ```text wai conversation update [--target ] [--body |@] [--yes] POST /msg/mls on the room service ``` #### `wai message create` A message. `message.create` · preview · since 0.3.0 · runs on a service, through its HTTP route · changes a target that is not this machine · takes `--dry-run` · waits for `--yes` every time it changes something · `POST /msg/post` on `wai-room` ```text wai message create [--target ] [--body |@] [--yes] POST /msg/post on the room service ``` #### `wai acknowledgement create` An acknowledgement. `acknowledgement.create` · preview · since 0.3.0 · runs on a service, through its HTTP route · changes a target that is not this machine · takes `--dry-run` · waits for `--yes` every time it changes something · `POST /msg/ack` on `wai-room` ```text wai acknowledgement create [--target ] [--body |@] [--yes] POST /msg/ack on the room service ``` #### `wai conversation leave` The caller leaves. `conversation.leave` · preview · since 0.3.0 · runs on a service, through its HTTP route · changes a target that is not this machine · takes `--dry-run` · waits for `--yes` every time it changes something · `POST /msg/leave` on `wai-room` ```text wai conversation leave [--target ] [--body |@] [--yes] POST /msg/leave on the room service ``` #### `wai member delete` The owner removes a member. `member.delete` · preview · since 0.3.0 · runs on a service, through its HTTP route · changes a target that is not this machine · takes `--dry-run` · waits for `--yes` every time it changes something · `POST /msg/remove` on `wai-room` ```text wai member delete [--target ] [--body |@] [--yes] POST /msg/remove on the room service ``` #### `wai call setup` A challenge for a proof. `call.setup` · preview · since 0.3.0 · runs on a service, through its HTTP route · changes a target that is not this machine · takes `--dry-run` · waits for `--yes` every time it changes something · `GET /call/challenge` on `wai-room` ```text wai call setup [--target ] [--query =]... [--yes] GET /call/challenge on the room service ``` #### `wai call create` Place a call. `call.create` · preview · since 0.3.0 · runs on a service, through its HTTP route · changes a target that is not this machine · takes `--dry-run` · waits for `--yes` every time it changes something · `POST /call/place` on `wai-room` ```text wai call create [--target ] [--body |@] [--yes] POST /call/place on the room service ``` #### `wai call invite` Ring invitees. `call.invite` · preview · since 0.3.0 · runs on a service, through its HTTP route · changes a target that is not this machine · takes `--dry-run` · waits for `--yes` every time it changes something · `POST /call/ring` on `wai-room` ```text wai call invite [--target ] [--body |@] [--yes] POST /call/ring on the room service ``` #### `wai inbox show` The caller's inbox. `inbox.show` · preview · since 0.3.0 · runs on a service, through its HTTP route · reads only · `GET /inbox` on `wai-room` ```text wai inbox show [--target ] [--query =]... GET /inbox on the room service ``` #### `wai answer create` Accept, decline or cancel. `answer.create` · preview · since 0.3.0 · runs on a service, through its HTTP route · changes a target that is not this machine · takes `--dry-run` · waits for `--yes` every time it changes something · `POST /call/answer` on `wai-room` ```text wai answer create [--target ] [--body |@] [--yes] POST /call/answer on the room service ``` #### `wai call show` The current call. `call.show` · preview · since 0.3.0 · runs on a service, through its HTTP route · reads only · `GET /call` on `wai-room` ```text wai call show [--target ] [--query =]... GET /call on the room service ``` #### `wai contract create` A channel's share contract from its terms, signed with the operator key; each owner countersigns it. `contract.create` · preview · since 0.3.0 · runs on this machine, touching nothing else · writes files on this machine · takes `--dry-run` · waits for `--yes` before it replaces a file that exists · writes a signed record a `verify` operation checks · needs the build feature `revenue_share` ```text wai contract create --key [--out F] [--yes] the share contract (WRC1) of the terms, signed with the operator key, every countersignature still to come, written to F (.wrc); each owner adds its own with `wai contract accept`; replacing a file waits for --yes (--confirm, deprecated, is the same) ``` - ``, path, required: The terms: start, end, currency, channel, channel_signer, rule, between, carriers, owners, splits and assets. - `--key`, string, required: The operator key: its name in the keystore (wai key list), or its file: 32 bytes, or 64 hexadecimal digits. - `--out`, path: The contract's file (.wrc). #### `wai contract accept` An owner's countersignature added to a share contract, after its rules and the operator's signature are checked. `contract.update` · preview · since 0.3.0 · runs on this machine, touching nothing else · writes files on this machine · takes `--dry-run` · waits for `--yes` before it replaces a file that exists · writes a signed record a `verify` operation checks · needs the build feature `revenue_share` · also `wai contract update` ```text wai contract accept --key [--out F] [--yes] the owner's countersignature added to the contract, written to F (the contract's own file when F is not given); replacing a file waits for --yes (--confirm, deprecated, is the same) ``` - ``, path, required: The contract's file (WRC1). - `--key`, string, required: The owner key: its name in the keystore (wai key list), or its file: 32 bytes, or 64 hexadecimal digits. - `--out`, path: Where the countersigned contract goes (the contract's own file). #### `wai statement create` A party's revenue-share statement for a period, recomputed from the ledger's invoices and the channel's program-as-run, signed with the operator key. `statement.create` · preview · since 0.3.0 · runs on this machine, touching nothing else · writes files on this machine · takes `--dry-run` · waits for `--yes` before it replaces a file that exists · writes a signed record a `verify` operation checks · needs the build feature `revenue_share` ```text wai statement create --party --start µs --end µs --key [--out F] [--yes] the statement (WRS1) of the party for [start, end), computed from a verification document without its statement (the contract, other contracts, runs and ledger documents), signed with the operator key and written with its document to F (.wai-share.json) for `wai statement verify`; replacing a file waits for --yes ``` - ``, path, required: A verification document without its statement: contract, contracts, runs and ledgers. - `--party`, string, required: The party's key, 64 hexadecimal digits: the operator or an owner. - `--start`, integer, required: The period's start, microseconds since 1970. - `--end`, integer, required: The period's end, after its start. - `--key`, string, required: The operator key: its name in the keystore (wai key list), or its file: 32 bytes, or 64 hexadecimal digits. - `--out`, path: The verification document's file (.wai-share.json). #### `wai statement verify` A revenue-share statement's verification document checked: every line recomputed from the public records, or the reason it is refused. `statement.verify` · preview · since 0.3.0 · runs on this machine, touching nothing else · reads only · needs the build feature `revenue_share` ```text wai statement verify the outcome of a statement's verification document: each line, each split's division and each impression's attribution, recomputed; exit 1 with the reason on a refusal ``` - ``, path, required: The verification document: contract, contracts, statement, runs and ledgers. #### `wai opportunity create` A party's opportunity report for a period: the ad breaks a channel's signed cues and program-as-run prove in the programmes it shares in, signed with the issuer key. `opportunity.create` · preview · since 0.3.0 · runs on this machine, touching nothing else · writes files on this machine · takes `--dry-run` · waits for `--yes` before it replaces a file that exists · writes a signed record a `verify` operation checks · needs the build feature `opportunity_report` ```text wai opportunity create --party --start µs --end µs --key [--out F] [--yes] the report (WOR1) of the party for [start, end), computed from a verification document without its report (the contract, other contracts, runs and rooms), signed with the issuer key and written with its document to F (.wai-opportunity.json) for `wai opportunity verify`; replacing a file waits for --yes ``` - ``, path, required: A verification document without its report: contract, contracts, runs and rooms. - `--party`, string, required: The party's key, 64 hexadecimal digits: the operator or an owner. - `--start`, integer, required: The period's start, microseconds since 1970. - `--end`, integer, required: The period's end, after its start. - `--key`, string, required: The issuer key: its name in the keystore (wai key list), or its file: 32 bytes, or 64 hexadecimal digits. - `--out`, path: The verification document's file (.wai-opportunity.json). #### `wai opportunity verify` An opportunity report's or a statement check's verification document checked: every break, line and flag recomputed from the records, or the reason it is refused. `opportunity.verify` · preview · since 0.3.0 · runs on this machine, touching nothing else · reads only · needs the build feature `opportunity_report` ```text wai opportunity verify the outcome of a report's or a check's verification document: each break attributed, each line and flag recomputed; exit 1 with the reason on a refusal ``` - ``, path, required: The verification document: a report's (contract, contracts, report, runs, rooms) or a check's (report, reported, statement, check). #### `wai statement check` A platform's reported statement checked against an opportunity report and, when given, the operator's signed statement, signed with the issuer key. `statement.check` · preview · since 0.3.0 · runs on this machine, touching nothing else · writes files on this machine · takes `--dry-run` · waits for `--yes` before it replaces a file that exists · writes a signed record a `verify` operation checks · needs the build feature `opportunity_report` ```text wai statement check [--statement ] [--floor ppm] [--ceiling ppm] --key [--out F] [--yes] the check (WCK1) of a reported statement (JSON, or CSV for a file named .csv) beside a report's verification document and a signed statement's, at the bounds given (500000 and 2000000 when not), signed with the issuer key and written with its document to F (.wai-check.json); replacing a file waits for --yes ``` - ``, path, required: A report's verification document, with its report. - ``, path, required: The reported statement: JSON, or CSV for a file named .csv. - `--statement`, path: A signed revenue-share statement's verification document of the same party and period. - `--floor`, integer: The lower bound, in millionths of the period's rate (500000). - `--ceiling`, integer: The upper bound, in millionths of the period's rate (2000000). - `--key`, string, required: The issuer key: its name in the keystore (wai key list), or its file: 32 bytes, or 64 hexadecimal digits. - `--out`, path: The verification document's file (.wai-check.json). #### `wai key create` A new Ed25519 signing key kept under a name, for one role, its secret in macOS's keychain or in a seed file; every signing operation's --key takes the name. `key.create` · preview · since 0.5.0 · runs on this machine, touching nothing else · writes files on this machine · takes `--dry-run` · needs the build feature `quickstart` ```text wai key create --for [--store keychain|file] [--keystore DIR] a new signing key named (1 to 48 of a-z, 0-9, - and _), for one role: origin, signer, room, audit, ledger, release, remote-host, quantum or dev. Its secret is kept in the login keychain (--store keychain, the default on macOS) or in a file of the keystore (--store file, the default elsewhere: mode 0600 on Unix; on Windows an access list for this account alone, inheritance off), and is never printed; a seed file another account may read is refused. The keystore is DIR, $WAI_KEYSTORE, or ~/.config/wai/keys (%APPDATA%\wai\keys on Windows). --key signs with it ``` - ``, string, required: The key's name: 1 to 48 of a-z, 0-9, - and _, beginning with a letter or a digit. - `--for` (`role`), string, required: The key's role: origin, signer, room, audit, ledger, release, remote-host, quantum or dev. - `--store`, string: Where the secret is kept: keychain (the default on macOS) or file (the default elsewhere: mode 0600 on Unix; on Windows, an access list for this account alone). - `--keystore`, path: The keystore's directory ($WAI_KEYSTORE, or ~/.config/wai/keys). #### `wai key list` Every key of the keystore: its name, role, key id, public key, status and where its secret is kept. `key.list` · preview · since 0.5.0 · runs on this machine, touching nothing else · reads only · needs the build feature `quickstart` ```text wai key list [--for ] [--keystore DIR] every key of the keystore, its newest version, and where its secret is kept ``` - `--for` (`role`), string: Only the keys of this role. - `--keystore`, path: The keystore's directory ($WAI_KEYSTORE, or ~/.config/wai/keys). #### `wai key show` One key: its public key and did:key, its role, every version with its status as a key log states it, and the version --key signs with. `key.show` · preview · since 0.5.0 · runs on this machine, touching nothing else · reads only · needs the build feature `quickstart` ```text wai key show [--keystore DIR] one key's versions, each active, retired (until) or revoked (compromised since), as jwp-receipts §7.2's key log states them, and the one --key signs with ``` - ``, string, required: The key's name. - `--keystore`, path: The keystore's directory ($WAI_KEYSTORE, or ~/.config/wai/keys). #### `wai key rotate` A key's successor made under the same name and a new key id, the old version retired now and its secret destroyed. `key.rotate` · preview · since 0.5.0 · runs on this machine, touching nothing else · removes or replaces what cannot be recovered · takes `--dry-run` · waits for `--yes` every time it changes something · needs the build feature `quickstart` ```text wai key rotate [--store keychain|file] [--keystore DIR] [--yes] a successor under a new key id (.), which --key signs with from now; the old version is retired now and its secret destroyed (jwp-receipts §7.6), so it waits for --yes ``` - ``, string, required: The key's name. - `--store`, string: Where the successor's secret is kept (where the old one's was). - `--keystore`, path: The keystore's directory ($WAI_KEYSTORE, or ~/.config/wai/keys). #### `wai key revoke` A key's version revoked as compromised from a time, its secret destroyed, so --key signs nothing with it. `key.revoke` · preview · since 0.5.0 · runs on this machine, touching nothing else · removes or replaces what cannot be recovered · takes `--dry-run` · waits for `--yes` every time it changes something · needs the build feature `quickstart` ```text wai key revoke [--id ] [--compromised-since ] [--keystore DIR] [--yes] the key's newest version (or --id's) revoked, compromised since the time given (now; YYYY-MM-DDTHH:MM:SSZ), and its secret destroyed (jwp-receipts §7.6); it waits for --yes ``` - ``, string, required: The key's name. - `--id`, string: The version to revoke, by its key id (the newest). - `--compromised-since` (`compromised_since`), string: From when another party may have held it: a date-time in UTC, YYYY-MM-DDTHH:MM:SSZ (now). - `--keystore`, path: The keystore's directory ($WAI_KEYSTORE, or ~/.config/wai/keys). #### `wai key import` A key file's seed kept under a name, as wai key create keeps a new one; a published test seed is refused unless named one. `key.import` · preview · since 0.5.0 · runs on this machine, touching nothing else · writes files on this machine · takes `--dry-run` · needs the build feature `quickstart` ```text wai key import --for --from [--store keychain|file] [--published-test-seed] [--keystore DIR] the seed of a key file (64 hexadecimal digits or the 32 bytes, as every --key file holds) kept as wai key create keeps one; a seed of one byte repeated 32 times, the form of every seed WAI publishes, is refused unless --published-test-seed names it a test key ``` - ``, string, required: The key's name. - `--for` (`role`), string, required: The key's role: origin, signer, room, audit, ledger, release, remote-host, quantum or dev. - `--from`, path, required: The key file: 64 hexadecimal digits, or the 32 bytes. - `--store`, string: Where the secret is kept: keychain (the default on macOS) or file. - `--published-test-seed` (`published_test_seed`), boolean: Keep a published test seed, marked as one. - `--keystore`, path: The keystore's directory ($WAI_KEYSTORE, or ~/.config/wai/keys). #### `wai key export` A key's public half, never its secret: in hexadecimal, as a did:key, as key-log entries, or as the line wai-keys lists it by. `key.export` · preview · since 0.5.0 · runs on this machine, touching nothing else · writes files on this machine · takes `--dry-run` · waits for `--yes` before it replaces a file that exists · needs the build feature `quickstart` ```text wai key export [--format hex|did-key|entry|wai-keys] [--may-sign ,...] [--out F] [--keystore DIR] the public half alone: hex (the default), did-key, entry (each version as a key-log entry, jwp-receipts §7.2) or wai-keys (the newest as wai-keys init --key and append --add take it); entry and wai-keys name the authorities an origin gives it (--may-sign); to stdout, or to F (replacing a file waits for --yes) ``` - ``, string, required: The key's name. - `--format`, string: hex (the default), did-key, entry or wai-keys. - `--may-sign` (`may_sign`), string: With entry and wai-keys: the authorities an origin gives the key (jwp-receipts §7.5), comma-separated. - `--out`, path: Write it to this file. - `--keystore`, path: The keystore's directory ($WAI_KEYSTORE, or ~/.config/wai/keys). #### `wai auth login` The key a service takes, read from standard input and kept for its origin in the keychain or a file only its owner reads. `credential.create` · preview · since 0.5.0 · runs on this machine, touching nothing else · writes files on this machine · takes `--dry-run` · waits for `--yes` before it replaces a file that exists · also `wai credential create` ```text wai auth login --url [--store keychain|file] [--yes] the key for the service at URL, read from standard input (one line; never from the command line), kept for its origin: in the login keychain on macOS, else in a file of the configuration directory that only its owner reads; WAI_TOKEN, when set, is sent ahead of every kept key. A key goes over https://, or over http:// to this machine alone. Replacing an origin's key waits for --yes ``` - `--url`, string, required: The service's http:// or https:// address; the key is kept for its origin. - `--store`, string: keychain (the default on macOS) or file (the default elsewhere). #### `wai auth status` The origins a key is kept for and where each is kept, never a key, and whether WAI_TOKEN is set. `credential.list` · preview · since 0.5.0 · runs on this machine, touching nothing else · reads only · also `wai credential list` ```text wai auth status each origin a key is kept for (wai auth login) and where it is kept, and whether WAI_TOKEN is set; no key is printed ``` #### `wai auth logout` The key kept for a service's origin removed from the keychain or its file. `credential.delete` · preview · since 0.5.0 · runs on this machine, touching nothing else · removes or replaces what cannot be recovered · takes `--dry-run` · waits for `--yes` every time it changes something · also `wai credential delete` ```text wai auth logout --url [--yes] the key kept for URL's origin removed, from the keychain or its file; it waits for --yes ``` - `--url`, string, required: The service's address; the key kept for its origin is removed. #### `wai target add` A target: a name for a service's address, kept in the project's wai.json or in the person's own list, and never with a key. `target.create` · preview · since 0.5.0 · runs on this machine, touching nothing else · writes files on this machine · takes `--dry-run` · waits for `--yes` before it replaces a file that exists · also `wai target create` ```text wai target add --url [--read-only] [--user] [--yes] kept in ./wai.json where there is one, else (or with --user) in the person's own list; --read-only refuses every operation that would change the service; a target is never kept with a key (wai auth login keeps it). Replacing a target of that name waits for --yes ``` - ``, string, required: The target's name: lowercase letters, digits and hyphens, beginning with a letter (local is the development room's). - `--url`, string, required: The service's http:// or https:// address, with no user, query or fragment. - `--read-only` (`read_only`), boolean: Refuse every operation that would change the service. - `--user`, boolean: Keep it in the person's own list, not the project's wai.json. #### `wai target use` The target an operation that needs a service acts on when --target names none. `target.update` · preview · since 0.5.0 · runs on this machine, touching nothing else · writes files on this machine · takes `--dry-run` · also `wai target update` ```text wai target use | --none the target taken where --target names none, kept in the person's own list; --none takes none ``` - ``, string: A target's name (wai target list). - `--none`, boolean: Take no target where none is named. #### `wai target list` Every target, its address, whether it is read-only, where it is kept and whether a key is kept for it; and the one in use. `target.list` · preview · since 0.5.0 · runs on this machine, touching nothing else · reads only ```text wai target list the project's targets (./wai.json) and the person's own, and the one in use ``` #### `wai target remove` A target removed from the project's wai.json or the person's own list. `target.delete` · preview · since 0.5.0 · runs on this machine, touching nothing else · removes or replaces what cannot be recovered · takes `--dry-run` · waits for `--yes` every time it changes something · also `wai target delete` ```text wai target remove [--user] [--yes] from ./wai.json where it is kept there, else (or with --user) from the person's own list; it waits for --yes ``` - ``, string, required: The target's name. - `--user`, boolean: Remove it from the person's own list. #### `wai ops list` Every operation of this catalogue: its id, command line, effect and whether this build holds it. `ops.list` · stable · since 0.3.0 · runs on this machine, touching nothing else · reads only ```text wai ops list every operation, its id and command line ``` #### `wai ops search` The operations that match a task, ranked, offline: up to five. `ops.search` · stable · since 0.3.0 · runs on this machine, touching nothing else · reads only ```text wai ops search "" up to five operations that match, ranked, offline ``` - ``, string, required: What you want to do, in words. #### `wai ops show` One operation's entry: its input and output schemas, effect, placement and command line. `ops.show` · stable · since 0.3.0 · runs on this machine, touching nothing else · reads only · also `wai ops schema` ```text wai ops show one operation's entry, as JSON (also wai ops schema) ``` - ``, string, required: An operation id, noun.verb. #### `wai ops export` The catalogue as JSON (wai.ops/1), what other tools and CI read; --check compares a file with it. `ops.export` · stable · since 0.3.0 · runs on this machine, touching nothing else · writes files on this machine · takes `--dry-run` · waits for `--yes` before it replaces a file the command line did not name ```text wai ops export [--out FILE | --check FILE] the catalogue as JSON, to stdout, to FILE, or compared with FILE ``` - `--out`, path: Write the export here. - `--check`, path: Compare this file with the export; exit 1 when they differ. #### `wai --version` This wai's version, the digests of its catalogue and its registry, the release of the standard it implements, and the build features it holds. `toolchain.show` · preview · since 0.5.0 · runs on this machine, touching nothing else · reads only · also `wai version` · also `wai toolchain show` ```text wai --version [--json] this binary's version, the SHA-256 of its catalogue (wai/catalogue/ops.json) and of its registry (wai/registry/capabilities.json), the release of the standard it implements with the envelope formats it reads, and the build features it holds (also wai version; wai/VERSIONING.md says what each promises) ``` #### `wai doctor` Whether this machine can run the toolchain: this wai and PATH, the relay and room service, the local stack's ports, browsers, and where keys are kept. `toolchain.doctor` · preview · since 0.5.0 · runs on this machine, touching nothing else · reads only · also `wai toolchain doctor` · the MCP tool `toolchain_doctor` ```text wai doctor [--keystore DIR] [--json] one check to a line: pass, FAIL with its fix, or not checked with the reason. Exit 1 when one failed; result says passed, failed, or passed-with-not-checked. No secret is read and no prompt raised (wai/quickstart/README.md) ``` - `--keystore`, path: The keystore to look at (default: where wai key keeps keys). ### Development (toolset `dev`) #### `wai dev` A relay, a room service and the room page on one origin on this machine, for development; --check starts, checks every piece and stops. `dev.start` · stable · since 0.3.0 · runs on this machine, touching nothing else · runs something and writes only its own state · takes `--dry-run` · waits for `--yes` before it replaces a file the command line did not name · also `wai dev start` · the MCP tool `dev_start` ```text wai dev [--port P] [--dir D] [--site DIR] [--watch FILE [--watch-ms MS]] [--call] [--remote] [--show [--audience N]] [--messaging] [--e2ee] [--publishers N] [--check] [--for S] [--web DIR] [--relay BIN] [--room BIN] --port P the origin's port on 127.0.0.1 (8080; 0 picks a free one) --dir D keys, configuration and logs (.wai/dev) --site DIR your page: DIR is served at /, the room client beside it at /room/ --publishers N places in the room (4) --watch FILE a watch room: everyone in it watches FILE together (.wav, .webm, .mp4, .ogg, .mp3); --watch-ms MS its duration, read from a WAV file's header --call the room is a call: /room/call.html places one, rings, answers --remote the room is one host's shared screen; prints the host's invitation --show the room is a show: hosts on camera, an audience that votes in polls the room's clock opens and signs (co-performance); --audience N each viewer's inputs to a poll (1) --messaging a conversation beside the room, at /msg-api/: /room/messages.html --e2ee every room end-to-end encrypted --check start, check every piece through the origin, report, stop --for S stop after S seconds --web DIR the room client's files (beside this binary: ../share/wai/web; $WAI_WEB) --relay BIN wai-relay (beside this binary, then $PATH; $WAI_RELAY_BIN) --room BIN wai-room (beside this binary, then $PATH; $WAI_ROOM_BIN) WAI Studio is served at /_wai/ when its files are found ($WAI_STUDIO, or share/wai/studio beside this binary). A wai.json in the current directory (`wai create` writes one) gives the defaults; a flag wins over it. Ctrl-C stops everything. With --json and without --check, the first line is {"ready": true, ...}. ``` - `--port`, integer: The origin's port on 127.0.0.1 (8080; 0 picks a free one). - `--dir`, path: Keys, configuration and logs (.wai/dev). - `--site`, path: A directory served at /. - `--watch`, path: A file everyone in a watch room watches together. - `--watch-ms` (`watch_ms`), integer: The watch file's duration in milliseconds. - `--call`, boolean: The room is a call. - `--remote`, boolean: The room is one host's shared screen. - `--show`, boolean: The room is a show: hosts on camera, an audience that votes in polls. - `--audience`, integer: With --show, each viewer's inputs to a poll (1). - `--messaging`, boolean: A conversation beside the room. - `--e2ee`, boolean: Every room end-to-end encrypted. - `--publishers`, integer: Places in the room (4). - `--check`, boolean: Start, check every piece, report and stop. - `--for` (`for_s`), integer: Stop after this many seconds. - `--web`, path: The room client's files. - `--relay`, path: The relay's binary. - `--room`, path: The room service's binary. #### `wai room grant` A grant for a key. `room.grant` · preview · since 0.3.0 · runs on a service, through its HTTP route · changes a target that is not this machine · takes `--dry-run` · waits for `--yes` every time it changes something · the MCP tool `room_grant` · `POST /grant` on `wai-room` ```text wai room grant [--target ] [--body |@] [--yes] POST /grant on the room service ``` ### Apps (toolset `app`) #### `wai app guide` The line language and every WAI widget, as a model writing a WAI app is told them. `app.guide` · preview · since 0.3.0 · runs on this machine, touching nothing else · reads only · needs the build feature `app` · the MCP tool `app_guide` ```text wai app guide what a model writing an app made with Create is told ``` #### `wai app check` An app program checked against the WAI registry and WAI's rules, every error with its line and reason code; in a project, its room and runtime too. `app.check` · preview · since 0.3.0 · runs on this machine, touching nothing else · reads only · needs the build feature `app` · the MCP tool `app_check` ```text wai app check [ | ] exit 1 when something does not hold, each failure named ``` - ``, path: A project directory or a program (.). #### `wai app export` An app made with Create written as a project: the program, wai.json naming its room, the page and its runtime, a README, AGENTS.md and the licence. `app.export` · preview · since 0.3.0 · runs on this machine, touching nothing else · writes files on this machine · takes `--dry-run` · waits for `--yes` before it replaces a file the command line did not name · needs the build feature `app` · the MCP tool `app_export` ```text wai app export [--runtime DIR] the same as wai create --from ``` - ``, path, required: The program made with Create. - ``, path, required: A directory that does not exist or is empty. - `--runtime`, path: A Create runtime ($WAI_APP_RUNTIME, or share/wai/app beside wai). ### Maintainers (toolset `maintainer`) #### `wai registry export` Write, or with --check compare, the registry's machine-readable export and the generated table of REGISTRY.md. `registry.export` · stable · since 0.3.0 · runs on this machine, touching nothing else · writes files on this machine · takes `--dry-run` · waits for `--yes` before it replaces a file the command line did not name ```text wai registry export [--root ] [--check] write (or compare) registry/capabilities.json, its schema, vocab/v2.* and the generated table of REGISTRY.md ``` - `--root`, path: The wai/ directory. - `--check`, boolean: Compare, write nothing. #### `wai http vectors` The HTTP conformance corpus: generated, verified, or its differential and fuzz cases written. `corpus.generate` · preview · since 0.3.0 · runs on this machine, touching nothing else · writes files on this machine · takes `--dry-run` · waits for `--yes` before it replaces a file the command line did not name · needs the build feature `http` · also `wai corpus generate` ```text wai http vectors gen|verify wai http vectors diff|fuzz --seed S --count N --out F ``` - ``, string, required: gen, verify, diff or fuzz. - ``, path, required: The corpus directory. ## Through the MCP server alone `wai mcp` serves these as tools, beside every command above whose entry names a tool. ### `app_stream` A program streamed into the person's open Create page through the bridge wai mcp runs on loopback. `app.stream` · preview · since 0.3.0 · runs on this machine, touching nothing else · runs something and writes only its own state · needs the build feature `app` · the MCP tool `app_stream` - `program`, string, required: The program's text. - `chunk`, integer: Characters a chunk (24). - `pace_ms`, integer: Milliseconds between chunks (30). ### `dev_stop` The development relay and room service a wai mcp server started, stopped. `dev.stop` · stable · since 0.3.0 · runs on this machine, touching nothing else · runs something and writes only its own state · the MCP tool `dev_stop` ### `room_join` A test principal enters the development room with its grant, publishes its tracks, and is seen joined by the room's clock. `room.join` · stable · since 0.3.0 · runs on this machine, against a service it names · changes a target that is not this machine · the MCP tool `room_join` - `target`, string: local: the development room on this machine. - `principal`, string, required: A test principal granted the publisher role. - `objects`, integer: Objects on each track (1). ### `room_leave` A test principal's session in the development room closed, and its leave seen by the room's clock. `room.leave` · stable · since 0.3.0 · runs on this machine, against a service it names · changes a target that is not this machine · the MCP tool `room_leave` - `target`, string: local: the development room on this machine. - `principal`, string, required: The test principal's name. ### `session_show` The development room's session as a verifier is given it: descriptor, grants, key-log head and the clock's event chain. `session.show` · stable · since 0.3.0 · runs on this machine, against a service it names · reads only · the MCP tool `session_show` - `target`, string: local: the development room on this machine. ## On the room service The room service (`wai-room`) answers these over HTTP. [The room service and the relay](/docs/api/) describes each route, and the service's OpenAPI description names each by its operation. | Route | Operation | What it does | |---|---|---| | `GET /` | `service.show`, preview | The service's health. | | `GET /health` | `service.check`, preview | The service's health. | | `GET /room` | `room.show`, preview | The current room. | | `POST /grant` | `room.grant`, preview; the MCP tool `room_grant` | A grant for a key. | | `GET /age/receipt` | `admission.show`, preview | The room's admission receipt so far. | | `GET /mls` | `mls.tail`, preview | The room's log of MLS messages. | | `POST /mls/key-package` | `mls.import`, preview | A KeyPackage for a granted principal's Add. | | `POST /mls/post` | `mls.update`, preview | A GroupInfo, or a commit and its Welcome. | | `GET /co/objects` | `performance.list`, preview | The clock's log of objects. | | `GET /co/state` | `performance.show`, preview | The room's co-performance as the clock holds it. | | `POST /co/schedule` | `schedule.create`, preview | A turn schedule the clock signs. | | `POST /co/handover` | `handover.create`, preview | A handover the clock signs. | | `POST /co/window` | `window.create`, preview | A selection window the clock signs. | | `POST /co/fidelity` | `fidelity.create`, preview | A fidelity statement now. | | `GET /watch/time` | `time.show`, preview | The service's clock. | | `GET /watch/source` | `source.fetch`, preview | The watch room's source, whole. | | `GET /watch/challenge` | `watch.setup`, preview | A challenge for a join's proof. | | `GET /watch` | `watch.tail`, preview | The watch room's log. | | `GET /watch/room` | `watch.show`, preview | The room as a co-watch verifier is given it. | | `POST /watch/join` | `watch.join`, preview | A viewer enters by a proof of its key. | | `POST /watch/post` | `watch.update`, preview | A viewer's events, checked and carried in order. | | `POST /remote/control` | `control.grant`, preview | The host hands control over. | | `GET /remote/room` | `remote.show`, preview | The session as the clock holds it. | | `GET /remote/state` | `remote.verify`, preview | That session verified. | | `GET /msg` | `conversation.show`, preview | The conversation. | | `GET /msg/challenge` | `conversation.setup`, preview | A challenge for a proof. | | `POST /msg/join` | `conversation.join`, preview | A key that proves itself is admitted. | | `GET /msg/log` | `conversation.tail`, preview | The log as it is owed to the caller. | | `POST /msg/key-package` | `conversation.import`, preview | A member's KeyPackage. | | `POST /msg/mls` | `conversation.update`, preview | A GroupInfo, or a commit and its Welcome. | | `POST /msg/post` | `message.create`, preview | A message. | | `POST /msg/ack` | `acknowledgement.create`, preview | An acknowledgement. | | `POST /msg/leave` | `conversation.leave`, preview | The caller leaves. | | `POST /msg/remove` | `member.delete`, preview | The owner removes a member. | | `GET /call/challenge` | `call.setup`, preview | A challenge for a proof. | | `POST /call/place` | `call.create`, preview | Place a call. | | `POST /call/ring` | `call.invite`, preview | Ring invitees. | | `GET /inbox` | `inbox.show`, preview | The caller's inbox. | | `POST /call/answer` | `answer.create`, preview | Accept, decline or cancel. | | `GET /call` | `call.show`, preview | The current call. |