CLI

Installing the CLI

# Latest release (needs Node.js 18+, curl, tar)
curl -fsSL https://raw.githubusercontent.com/duncantidd/wizz.js/main/scripts/install-cli.sh | bash

# From a clone of the repository
./scripts/install-cli.sh            # latest release
./scripts/install-cli.sh --local    # the working tree (developing Wizz itself)
./scripts/install-cli.sh ./wizz-1.17.0.tgz   # a specific tarball (path or URL)

The installer puts the compiler and runtime in $XDG_DATA_HOME/wizz (default ~/.local/share/wizz) and the launcher in $XDG_BIN_HOME (default ~/.local/bin). It needs no administrator privileges and never edits shell profiles. To check the release checksum yourself before running anything, see Verify before installing. To uninstall, delete both:

rm -f "${XDG_BIN_HOME:-$HOME/.local/bin}/wizz"
rm -rf "${XDG_DATA_HOME:-$HOME/.local/share}/wizz"

Command summary

Usage:
wizz init [directory] [--force]   Scaffold a starter project
wizz build [input-directory] [output-directory] [--json] [--adapter <name>]
wizz dev [--port <n>] [--host <addr>]
wizz mcp [--root <dir>] [--allow-write]
                                  Serve Wizz tooling to AI agents over MCP (stdio)
wizz update                       Update the managed installation to the latest release
wizz install-vscode-extension     Install the latest VS Code extension from a release
wizz --version                    Print the compiler and contract versions

wizz init

Scaffolds the showcase starter: index.html, a global App.css, a landing page with a reactive head, a persisted counter, an animated terminal card, a server-rendered /home page, a sample /api/health handler, and a README. The result runs with no manual edits.

wizz init              # scaffold into the current (empty) directory
wizz init my-app       # scaffold into ./my-app
wizz init my-app --force   # allow a non-empty directory; existing files are never overwritten

wizz dev

Uses the current directory as the project. Builds src into dist, serves it, server-renders eligible routes, runs /api/** handlers with .env.server loaded, and live-reloads tabs over /_wizz/reload when sources change.

wizz dev                       # build src → dist, serve http://127.0.0.1:3000, watch
wizz dev --port 4321
wizz dev --host 0.0.0.0        # opt out of loopback (remote development only)
HOST=0.0.0.0 wizz dev          # same, from the environment (--host wins)

• Requires an index.html shell, checked before the server opens.
• Watches with native file events and a 250 ms polling fallback (reliable on WSL's /mnt/c).
• Binds to 127.0.0.1 by default — it has no auth or TLS and executes handlers with your secrets.
• Compile errors are reported while the server keeps running; a busy port exits with a message naming --port.

wizz build

Compiles every .wizz file (continuing past failures so you see them all), writes the route and API manifests, copies the runtime, the shell, App.css, and src/server/, extracts scoped CSS into dist/app.css, and writes dist/package.json as {"type":"module"}. Exits non-zero if any component fails.

wizz build                     # src → dist
wizz build components public   # explicit input and output (both, or neither)
wizz build --json              # machine-readable diagnostics on stdout
wizz build --adapter node      # also emit dist/server.mjs
wizz build --adapter=node --json

--json diagnostics

--json (any position) prints a versioned envelope to stdout instead of prose. Fields may be added within format version 1; existing fields keep their meaning.

{
  "format": "wizz-build-diagnostics@1",
  "ok": false,
  "diagnostics": [
    {
      "code": "WIZZ-P018",
      "severity": "error",
      "message": "Mismatched closing tag. Expected </p>, found </main> at Broken.wizz:1:16.",
      "file": "Broken.wizz",
      "line": 1,
      "column": 16
    }
  ],
  "files": [{ "file": "App.wizz", "serverRenderable": true }]
}

# CI gate: fail on any diagnostic and print the codes
wizz build --json > build.json || true
node -e '
  const report = require("./build.json");
  for (const d of report.diagnostics) console.log(d.code, d.file + ":" + d.line, d.message);
  process.exit(report.ok ? 0 : 1);
'

--adapter node

Opt-in, build-only. Emits dist/server.mjs, a standalone SSR + API host using only Node built-ins. The JSON envelope gains "adapter": "node". Unknown adapter names fail at the CLI boundary with the list of known ones.

wizz build --adapter node
node dist/server.mjs              # http://localhost:8080
PORT=3000 node dist/server.mjs

wizz mcp

Starts the Model Context Protocol server on stdio for AI agents. The root is fixed at startup, and writes stay disabled unless you opt in. See MCP Server for the tools and security model.

wizz mcp                                   # root = current directory, read-only
wizz mcp --root /path/to/project           # fix the project root
wizz mcp --root /path/to/project --allow-write   # enable compile-gated writes

wizz update

Fetches the latest release and swaps it into the managed directory in place. The old installation is kept aside until the new one is ready, so the launcher never breaks mid-update. Takes no arguments.

wizz update

wizz install-vscode-extension

Downloads the latest release's wizz-vscode-<version>.vsix and installs it with the code command: syntax highlighting, compiler diagnostics, component navigation, and build commands. The extension drives the installed CLI, so keep wizz on your PATH or set wizz.compilerPath.

wizz install-vscode-extension

# without the CLI
code --install-extension wizz-vscode-<version>.vsix

wizz --version

wizz --version
# wizz 1.17.0 (compiler 1.17.0, syntax 1.4.1, output 1.8.2)

Stability & exit codes

The supported commands, their documented defaults, generated output paths, and non-zero failure behavior are stable within a CLI major version. Build failures, invalid usage (unknown commands, stray flags, a single build directory), and a missing shell for dev all exit non-zero.