--- title: CLI description: vgpu CLI commands, arguments, flags, and exit codes. --- # CLI The vgpu CLI provides command-line tooling for working with vgpu. Use it to validate WGSL shaders, query the vgpu documentation, inspect canonical example source, serve those same docs and examples over MCP, diagnose your local GPU environment, and set up the native runtime for Node.js workflows. ## Installation and usage The CLI ships with the `vgpu` package, so no separate installation is required. Run any command with `npx vgpu`: ```bash npx vgpu [args] [flags] npx vgpu --help npx vgpu --version ``` The `examples` commands never execute fetched code. ## Command inventory | Command | Dispatcher description | | --------------------------- | -------------------------------------------------------------- | | `check` | Validate and reflect a WGSL file as JSON | | `docs` | Explore bundled VGPU documentation | | `examples` | Inspect canonical gallery source (never executes code) | | `mcp` | Serve documentation and examples as MCP tools over stdio | | `snapshot` | Compare the representative GPU pixel snapshot | | `install-dawn` | Download and verify the portable Node Dawn prebuild | | `install-software-renderer` | Download and verify the portable CPU renderer | | `doctor` | Verify this machine can render headless (JSON verdict + fixes) | ## check The `vgpu check` command validates a WGSL file without running it. On success it prints the shader's reflection data as JSON; on failure it reports the validation errors and exits non-zero. Use it to catch shader problems early, in your editor, pre-commit hooks, or CI. ```text Usage: vgpu check [--require-validation] ``` | Flag | Argument | | ---------------------- | -------- | | `--require-validation` | none | Device-backed WGSL validation runs in `resolveShader`'s default `"auto"` mode: when this machine has a WebGPU device, invalid WGSL fails the command; when it does not, `check` warns once on stderr and still reports reflection. Pass `--require-validation` (or set `VGPU_VALIDATE=require`) to fail instead of degrading — useful in CI, where a missing device would otherwise silently reduce `check` to a parse-and-reflect pass. The JSON payload includes a `validation` object (`{ mode, attempted, ok, skipped? }`) describing exactly what ran, and error payloads carry `fix`/`where` when the underlying error provides them. A failing device check never costs you the rest of the document: when validation rejects the shader (or, under `--require-validation`, when no device could be acquired), `check` still prints the full payload — `diagnostics`, `reflection` and `wgsl` — and reports the failure as `validation.error` (`{ code, message, fix?, where?, ... }`) with `ok: false`, exiting 1. So the JSON contract is the same whether or not the machine running `check` has a WebGPU device; only `validation` differs. Resolution failures (a missing import, a module that declares bindings, an invalid `VGPU_VALIDATE`) remain hard errors: they print a single error object on stderr with no payload. ```bash npx vgpu check ./shaders/main.wgsl npx vgpu check ./shaders/main.wgsl --require-validation VGPU_VALIDATE=require npx vgpu check ./shaders/main.wgsl ``` ## docs The `vgpu docs` commands let you explore the vgpu documentation from the terminal. The full corpus — API reference and guides — ships inside the package, so every query runs locally and works offline. Use `ls` to browse the documentation tree, `cat` to print a page or symbol, `grep` to search across content, and `find` to look up the page to read next by name, keyword, or phrase. ```text Usage: vgpu docs [args] [flags] Start here: vgpu docs cat getting-started.md (the guide for using the latest API correctly) Commands: ls [path] List packages or docs under a virtual path cat Print docs by virtual path or unique symbol grep [-i] [--package ] Search docs content; case-sensitive unless -i is used find Find symbols and docs paths by substring path Resolve a symbol or virtual path for shell usage symbols List indexed symbols help Show this help Examples: vgpu docs cat getting-started.md vgpu docs ls /guides vgpu docs ls vgpu docs cat /@vgpu/core/Buffer.docs.md vgpu docs grep -i --package @vgpu/wgsl minify vgpu docs path Buffer ``` ### docs cat ```bash npx vgpu docs cat npx vgpu docs cat /@vgpu/core/Buffer.docs.md ``` ### docs find ```bash npx vgpu docs find npx vgpu docs find buffer npx vgpu docs find "wgsl loader" ``` Every whitespace-separated word in the query must match, so multi-word phrases narrow the result instead of returning nothing. `find` looks at symbol names, doc paths, page titles, and the search keywords a page declares; only when that finds nothing does it fall back to searching page bodies, which is what makes prose (`"typescript wgsl import"`) and error codes (`VGPU-WGSL-PKG-NOTFOUND`) resolve to a page. Use `grep` when you want every content match with its line, and `find` when you want the page to read next. Results are ranked best-match-first and capped at 20; a truncated response ends with a line telling you how many matches were hidden so you can add a word. ### docs grep ```bash npx vgpu docs grep [-i] [--package ] npx vgpu docs grep -i --package @vgpu/wgsl minify ``` | Flag | Argument | | ----------- | -------- | | `-i` | none | | `--package` | `` | ### docs help ```bash npx vgpu docs help npx vgpu docs --help ``` ### docs ls ```bash npx vgpu docs ls [path] npx vgpu docs ls /guides ``` ### docs path ```bash npx vgpu docs path npx vgpu docs path Buffer ``` ### docs symbols ```bash npx vgpu docs symbols ``` ## doctor The `vgpu doctor` command verifies that the current machine can render headless with vgpu. It runs its checks end to end — including a real render unless you pass `--no-render` — and prints a JSON verdict with suggested fixes. The command exits `0` when the environment is healthy and non-zero when it is not. ```text Usage: vgpu doctor [--no-render] [--pretty] Diagnose whether this machine can render headless with vgpu/node. JSON is written by default. ``` | Flag | Argument | | ------------- | -------- | | `--no-render` | none | | `--pretty` | none | ```bash npx vgpu doctor npx vgpu doctor --no-render npx vgpu doctor --pretty ``` ## examples The `vgpu examples` commands let you search and inspect the source code of the vgpu example gallery without cloning the repository. Use `search` to find examples, `show` to list an example's files and metadata, `cat` to print a single file, and `pull` to copy an example's complete source into a local directory. ```text vgpu examples — inspect canonical gallery source (never executes code) Official origin: https://vgpu.sh Usage: vgpu examples search [--any] [--limit ] [--revision ] [--offline] [--pretty] vgpu examples show [--revision ] [--offline] [--pretty] vgpu examples cat [--revision ] [--offline] [--json] vgpu examples pull --out [--revision ] [--offline] [--force] [--pretty] vgpu examples cache path vgpu examples cache clear Canonical agent invocation: npx vgpu examples ... ``` ### examples search ```bash npx vgpu examples search npx vgpu examples search "raymarching hdr" --any --limit 10 --pretty ``` | Flag | Argument or range | | ------------ | --------------------------------------------- | | `--any` | none | | `--limit` | integer `` from `1` to `100`; default `20` | | `--revision` | lowercase `` | | `--offline` | none | | `--pretty` | none | ### examples show ```bash npx vgpu examples show npx vgpu examples show raymarched-fractal --pretty ``` | Flag | Argument | | ------------ | -------------------- | | `--revision` | lowercase `` | | `--offline` | none | | `--pretty` | none | ### examples cat ```bash npx vgpu examples cat npx vgpu examples cat raymarched-fractal renderer.ts npx vgpu examples cat raymarched-fractal renderer.ts --json ``` | Flag | Argument | | ------------ | -------------------- | | `--revision` | lowercase `` | | `--offline` | none | | `--json` | none | ### examples pull ```bash npx vgpu examples pull --out npx vgpu examples pull raymarched-fractal --out ./fractal --pretty ``` | Flag | Argument | | ------------ | ---------------------- | | `--out` | required `` | | `--revision` | lowercase `` | | `--offline` | none | | `--force` | none | | `--pretty` | none | ### examples cache ```bash npx vgpu examples cache path npx vgpu examples cache clear ``` ### Revision and offline fields | Input or output | Value | | ---------------- | ------------------------------------------------------------- | | `--revision` | Immutable lowercase SHA-256 revision | | `--offline` | No network requests; requires previously verified cached data | | `lastVerifiedAt` | Included in applicable structured offline results | ### Exit codes | Code | Error class | | ---- | ----------------------------------------------------- | | `0` | success | | `2` | `VGPU-EXAMPLES-USAGE` | | `3` | `VGPU-EXAMPLES-NOT-FOUND` | | `4` | `VGPU-EXAMPLES-NETWORK` | | `5` | `VGPU-EXAMPLES-INTEGRITY` and incompatible API errors | | `6` | `VGPU-EXAMPLES-DESTINATION-EXISTS` | | `7` | `VGPU-EXAMPLES-FILESYSTEM` | ## mcp VGPU exposes the existing docs and examples behavior as two typed MCP tools: * `docs` supports `search`, `read`, `resolve`, `list`, `grep`, and `symbols` operations against the documentation bundled with the package. * `examples` supports `search`, `show`, and `read`. On Linux and macOS, the local stdio transport also supports `download`. Both `read` operations are paginated for transport-safe responses. They accept an optional UTF-16 `offset` and `limit`; `limit` defaults to and cannot exceed 65,536 code units. When more content remains, structured output includes `truncated: true` and the `nextOffset` to request. Use the public, read-only Streamable HTTP endpoint when an agent only needs to inspect content: ```text https://vgpu.sh/api/mcp ``` The hosted endpoint is stateless and implements the modern MCP 2026-07-28 transport. Configure clients for automatic or modern protocol negotiation; legacy session-based HTTP is intentionally rejected because a request may be served by any deployment instance. The endpoint is also advertised at `https://vgpu.sh/.well-known/mcp.json`. Start the stdio server without filesystem writes when an agent is running locally: ```bash npx vgpu mcp ``` Bare stdio exposes the same read-only operations as HTTP. To enable `download` on Linux or macOS, explicitly select its output boundary in one of three ways: ```bash # Project-scoped clients that launch the server from the project directory npx vgpu mcp --project-from-cwd # A fixed project directory npx vgpu mcp --output-dir /absolute/path/to/project # A host-managed environment VGPU_MCP_OUTPUT_DIR=/absolute/path/to/project npx vgpu mcp ``` `--output-dir` and `VGPU_MCP_OUTPUT_DIR` must name an existing absolute directory; VGPU canonicalizes it before serving. An explicit CLI selector overrides the environment variable, and `--output-dir` cannot be combined with `--project-from-cwd`. Without one of these configurations, `download` is omitted from the tool schema. The agent supplies a normalized relative destination beneath that boundary: ```json { "operation": "download", "id": "gradient", "destination": "examples/gradient" } ``` Absolute destinations, dot segments, encoded paths, backslashes, control characters, the boundary directory itself, and existing destinations are rejected. Successful structured output reports the canonical absolute `destination`. VGPU coordinates concurrent VGPU writers with a lock and never exposes the human-operated `vgpu examples pull --force` behavior through MCP. Node does not expose a portable atomic no-replace rename for directories, so another process with write access to the output directory must not concurrently claim the same destination during final publication. Use project-scoped Claude Code (`.mcp.json`) or Cursor (`.cursor/mcp.json`) configuration with `--project-from-cwd` only when that client launches the command from the project directory: ```json { "mcpServers": { "vgpu": { "command": "npx", "args": ["-y", "vgpu", "mcp", "--project-from-cwd"] } } } ``` Codex can use the same project-scoped pattern in `.codex/config.toml` when Codex launches the MCP process from the active workspace; omitting `cwd` preserves that inherited working directory: ```toml [mcp_servers.vgpu] command = "npx" args = ["-y", "vgpu", "mcp", "--project-from-cwd"] ``` For global MCP configuration, use a fixed `--output-dir` or set `VGPU_MCP_OUTPUT_DIR` in the server environment. Claude Code and Codex MCP configurations load inside Conductor. Cursor reads `.cursor/mcp.json` only after you open the Conductor workspace in Cursor. Conductor does not define a separate MCP format. There is no cross-editor MCP convention that safely grants a local server write access to whichever workspace is currently active, so VGPU does not infer one. On Windows, the stdio server remains read-only even when an output boundary is configured because the CLI cannot provide the same safe publication guarantees there. ## install-dawn The `vgpu install-dawn` command downloads and verifies the portable Dawn prebuild, the native WebGPU implementation vgpu uses to render in Node.js. Run it when `vgpu doctor` reports a missing Dawn runtime. ```text Usage: vgpu install-dawn Download and verify the portable Dawn binary for this platform. Honors GH_TOKEN/GITHUB_TOKEN and VGPU_CACHE_DIR. ``` ```bash npx vgpu install-dawn ``` ## install-software-renderer The `vgpu install-software-renderer` command downloads and verifies a portable CPU renderer. Use it on machines without a usable GPU — such as CI runners or headless servers — so vgpu can still render. ```text Usage: vgpu install-software-renderer Download and sha256-verify the portable CPU software renderer for this platform. Honors VGPU_CACHE_DIR. ``` ```bash npx vgpu install-software-renderer ``` ## snapshot The `vgpu snapshot` command is an internal self-test used by vgpu's own CI: it renders a scene built into the CLI inside the Docker GPU harness (`VGPU_DOCKER_TEST=1`) and compares the pixels against a committed baseline to catch toolchain regressions. To verify that your machine is set up correctly, use `vgpu doctor` instead. ```text Usage: vgpu snapshot [--ci] [--update] [--baseline ] ``` `VGPU_DOCKER_TEST=1` is required. | Flag | Argument | | ------------ | -------- | | `--ci` | none | | `--update` | none | | `--baseline` | `` | ```bash VGPU_DOCKER_TEST=1 npx vgpu snapshot --ci VGPU_DOCKER_TEST=1 npx vgpu snapshot --update VGPU_DOCKER_TEST=1 npx vgpu snapshot --baseline ``` ## Global options | Flag | Shorthand | Output | | ----------- | --------- | --------------------- | | `--help` | `-h` | CLI help | | `--version` | `-v` | installed CLI version | ```bash npx vgpu --help npx vgpu --version ``` --- For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md) For an index of all available documentation, see [/llms.txt](/llms.txt) For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)