Installation

Before you install: Node 20+ and npm

Install Node 20 or newer (it includes npm) from nodejs.org first — choose the LTS installer for your operating system and keep every default option. The vvd installer can download a private Node runtime into ~/.vvd/node when it finds none, but that fallback sometimes fails (especially on Windows), so don't rely on it: a real Node + npm install is the reliable path.

Check you're ready:

node --version && npm --version

v22.22.0
10.9.3

Install via script (recommended)

The installer needs a shell and an internet connection.

macOS and Linux:

curl -fsSL https://beta.vvd.world/cli/install.sh | sh

→ Downloading the vvd CLI…
✓ Installed vvd → /Users/you/.vvd/bin/vvd
✓ Linked vvd → /usr/local/bin/vvd (ready in this terminal)

Windows, in PowerShell:

irm https://beta.vvd.world/cli/install.ps1 | iex

→ Downloading the vvd CLI…
✓ Installed vvd → C:\Users\you\.vvd\bin\vvd.cmd

Restart your terminal so the 'vvd' command works.

On macOS and Linux the command works in the terminal you're sitting in. On Windows the installer edits your user PATH, and PowerShell reads that at startup — so restart the terminal once.

Everything the installer touches lives in one folder in your home directory (~/.vvd). There's no system package, no daemon, no sudo, and no global npm install.

Install with your sign-in code

The Workshop → Developer tab in the app hands you this form with your one-time code already in it — it installs and signs you in in one step:

curl -fsSL https://beta.vvd.world/cli/install.sh | VVD_TOKEN=vvd_otc_7f3c1a92 sh

On Windows: $env:VVD_TOKEN="vvd_otc_7f3c1a92"; irm https://beta.vvd.world/cli/install.ps1 | iex

Verify installation

Don't move on until this prints a version:

vvd version

  ● vvd v0.8.11

Then let vvd doctor check everything at once — Node, the bundler, your sign-in, and whether vvd is reachable. It prints the fix beneath any failing line, and vvd doctor --fix applies it:

vvd doctor

vvd doctor — checking your setup

✓ Node 20.18.1
✓ Bundler (esbuild) ready
✓ Signed in as Alex
✓ Reach VVD at https://beta.vvd.world

All good — you're ready to build. ✦

Troubleshooting

vvd: command not found right after installing. The install worked, but nothing on your PATH was writable, so the change only applies to new terminals. Either open a new terminal, or run the export PATH=… line the installer printed:

export PATH="$HOME/.vvd/bin:$PATH"

Windows: still not found after installing. Restart the terminal. The installer changed your user PATH, and PowerShell only reads it at startup.

The bundler setup fails on your first build. Run vvd doctor --fix — it downloads the prebuilt bundler binary straight from the npm registry (no npm involved), falling back to npm only if that download fails. If it still fails, the doctor line prints the actual reason (an HTTP status, a DNS error, npm's own output). The usual cure: install Node LTS with npm from nodejs.org — keep every default option, ignore the Docker and package-manager tabs — restart your terminal, then run vvd doctor --fix again.

curl: command not found. The installer falls back to wget, but you need one of the two to fetch it in the first place. Behind a corporate proxy, the usual HTTPS_PROXY variable applies to both.

Update

The CLI checks its published version before every real command and updates itself in place, then re-runs the exact command you typed — you never have to think about it. Offline it skips the check and runs the version you have.

vvd update

Uninstall

The CLI lives entirely in ~/.vvd, so removing it is one command. This also deletes your stored credentials.

rm -rf ~/.vvd

On Windows:

Remove-Item -Recurse -Force $env:USERPROFILE\.vvd

If the installer added a # VVD CLI line to your shell rc file or a symlink at /usr/local/bin/vvd, remove those by hand. On Windows, remove %USERPROFILE%\.vvd\bin from your user PATH.

Next steps