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:

npx vgpu <command> [args] [flags]
npx vgpu --help
npx vgpu --version

The examples commands never execute fetched code.

Command inventory

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.

Usage: vgpu check <file.wgsl> [--require-validation]

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.

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.

Usage: vgpu docs <command> [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 <path|symbol>          Print docs by virtual path or unique symbol
  grep [-i] [--package <pkg>] <pattern>
                             Search docs content; case-sensitive unless -i is used
  find <query>               Find symbols and docs paths by substring
  path <symbol|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

npx vgpu docs cat <path|symbol>
npx vgpu docs cat /@vgpu/core/Buffer.docs.md

docs find

npx vgpu docs find <query>
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

npx vgpu docs grep [-i] [--package <pkg>] <pattern>
npx vgpu docs grep -i --package @vgpu/wgsl minify

docs help

npx vgpu docs help
npx vgpu docs --help

docs ls

npx vgpu docs ls [path]
npx vgpu docs ls /guides

docs path

npx vgpu docs path <symbol|path>
npx vgpu docs path Buffer

docs symbols

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.

Usage: vgpu doctor [--no-render] [--pretty]

Diagnose whether this machine can render headless with vgpu/node. JSON is written by default.

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.

vgpu examples — inspect canonical gallery source (never executes code)

Official origin: https://vgpu.sh

Usage:
  vgpu examples search <query> [--any] [--limit <n>] [--revision <sha256>] [--offline] [--pretty]
  vgpu examples show <id> [--revision <sha256>] [--offline] [--pretty]
  vgpu examples cat <id> <path> [--revision <sha256>] [--offline] [--json]
  vgpu examples pull <id> --out <directory> [--revision <sha256>] [--offline] [--force] [--pretty]
  vgpu examples cache path
  vgpu examples cache clear

Canonical agent invocation: npx vgpu examples ...

examples search

npx vgpu examples search <query>
npx vgpu examples search "raymarching hdr" --any --limit 10 --pretty

examples show

npx vgpu examples show <id>
npx vgpu examples show raymarched-fractal --pretty

examples cat

npx vgpu examples cat <id> <path>
npx vgpu examples cat raymarched-fractal renderer.ts
npx vgpu examples cat raymarched-fractal renderer.ts --json

examples pull

npx vgpu examples pull <id> --out <directory>
npx vgpu examples pull raymarched-fractal --out ./fractal --pretty

examples cache

npx vgpu examples cache path
npx vgpu examples cache clear

Revision and offline fields

Exit codes

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:

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:

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:

# 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:

{
  "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:

{
  "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:

[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.

Usage: vgpu install-dawn

Download and verify the portable Dawn binary for this platform.
Honors GH_TOKEN/GITHUB_TOKEN and VGPU_CACHE_DIR.

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.

Usage: vgpu install-software-renderer

Download and sha256-verify the portable CPU software renderer for this platform.
Honors VGPU_CACHE_DIR.

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.

Usage: vgpu snapshot [--ci] [--update] [--baseline <path>]

VGPU_DOCKER_TEST=1 is required.

VGPU_DOCKER_TEST=1 npx vgpu snapshot --ci
VGPU_DOCKER_TEST=1 npx vgpu snapshot --update
VGPU_DOCKER_TEST=1 npx vgpu snapshot --baseline <path>

Global options

npx vgpu --help
npx vgpu --version