Installation#

The managed installer currently provides the pinned CLI 0.3.0 release. The installer downloads a fixed-version CLI archive over HTTPS, checks its SHA-256 against the pinned release value, and sets up a managed Node.js 22 runtime in your user directory. It never replaces your system Node.js and does not need administrator rights.

Supported platforms: macOS and Linux (x64, arm64) and Windows (x64, arm64).

Use the exact npm package names in the public release table below. The managed installer continues to provide its existing pinned release.

npm packages for game development#

The table lists exact installation versions. @zuku/player is updated here to 0.1.2; the other eight packages retain the releases verified in the public npm registry on 2026-10-04. Install the packages your project needs.

Package	Version	Purpose
@zuku/zwf	`0.1.1`	ZWF2 HTML5 ZIP game package reading and writing
@zuku/sdk	`0.2.0`	ZUKU API and game bridge
zuku-engine-next2d	`0.1.1`	Jump engine integration and game package validation
@zuku/zwf-runtime	`0.1.2`	ZWF1 animation WebAssembly runtime and host loader
@zuku/lang	`0.1.0`	Validated JSON resources for 20 locales
@zuku/core	`27.0.1`	Command parsing, diagnostics and redaction
@zuku/player	`0.1.2`	Browser player from the maintained Next2D fork
@zuku/editor	`0.1.1`	Browser editor and embedding helper
@zuku/cli	`0.3.1`	Shared zuku and zukujs commands

npm install --save-exact @zuku/zwf@0.1.1 @zuku/sdk@0.2.0 zuku-engine-next2d@0.1.1 @zuku/zwf-runtime@0.1.2 @zuku/lang@0.1.0 @zuku/core@27.0.1 @zuku/player@0.1.2 @zuku/editor@0.1.1

@zuku/player 0.1.2 limits WebGPU adapter and device acquisition waits to two seconds. Renderer initialization failure or device loss can recover through WebGL on a fresh canvas. Recovery is limited to two attempts and reports an error if rendering cannot initialize.

Resource exports include JSON such as @zuku/lang/locales/ko.json and WebAssembly at @zuku/zwf-runtime/wasm. For browser projects, use an ESM bundler and follow each package's host instructions.

ZWF2 packages HTML5 ZIP games; ZWF1 stores animations. Use the package and loader for the appropriate format.

Each package retains its original license notice. The existing UNLICENSED declaration for @zuku/core is preserved. The Next.js server framework and operational servers are excluded from this game-library release.

Install the CLI from npm#

Use Node.js 22 or later with npm, then run:

npm install -g @zuku/cli@0.3.1
zuku --version
zukujs --version

zuku and zukujs share the same CLI, login, configuration and Agent Core state. The npm CLI 0.3.1 and the managed installer's pinned 0.3.0 release below have separate distribution paths.

macOS and Linux#

Download the installer with curl or wget, then run it with Bash.

curl

curl -fsSL --proto '=https' --tlsv1.2 https://zuzunza.com/install.sh -o install-zuku-cli.sh && bash install-zuku-cli.sh

wget

wget --https-only -O install-zuku-cli.sh https://zuzunza.com/install.sh && bash install-zuku-cli.sh

By default the CLI is installed to ~/.local/share/zukujs, with the commands ~/.local/bin/zuku and ~/.local/bin/zukujs.

Windows (PowerShell)#

& ([scriptblock]::Create((irm 'https://zuzunza.com/install.ps1')))

By default the CLI is installed to %LOCALAPPDATA%\ZukuJS, with bin\zuku.cmd and bin\zukujs.cmd. The installer adds that bin folder to the PATH of the current PowerShell session. No PowerShell profile changes are made.

Verify the install#

zuku --version

Then try the full local flow:

zuku create my-game
zukujs validate my-game

zuku and zukujs are the same CLI. Both names share one runtime, configuration, and login state in ~/.config/zukujs/ (Windows: %LOCALAPPDATA%\ZukuJS\).

Installer options#

Bash	PowerShell	What it does
`--prefix /absolute/path`	`-Prefix 'C:\absolute\path'`	Install into a directory you own; commands go in its `bin` folder
`--no-node`	`-NoNode`	Use an existing Node.js 22+ and npm (CLI-only releases)
`--dry-run`	`-DryRun`	Show the install plan without downloading or writing anything
`--help`	`-Help`	Show installer help

Quote paths that contain spaces:

bash install-zuku-cli.sh --prefix "$HOME/Tools/ZukuJS CLI" --dry-run

& ([scriptblock]::Create((irm 'https://zuzunza.com/install.ps1'))) -Prefix "$env:LOCALAPPDATA\Tools\ZukuJS CLI" -DryRun

Releases that include Studio always use the bundled Node.js 22 runtime; passing --no-node or -NoNode with them stops with an error before anything is installed.

For manual inspection, the fixed release archive is available at https://zuzunza.com/downloads/zukujs/cli/0.3.0/zukujs-cli-0.3.0.tgz. The installer is the supported way to set it up.

Updating or reinstalling#

Run the same install command again. It reuses the same install location. If a download check or the post-install check fails, your previous install and both command names are kept or restored.

Troubleshooting#

zuku: command not found (macOS/Linux)

The installer does not edit your shell configuration. Add the bin folder to PATH for the current terminal:

export PATH="$HOME/.local/bin:$PATH"
zuku --version

To make it permanent, add the same export line to your shell's startup file (for example ~/.bashrc or ~/.zshrc). If you used --prefix, add <prefix>/bin instead.

zuku not found in a new Windows terminal

Add %LOCALAPPDATA%\ZukuJS\bin to User environment variables > Path, then open a new terminal.

Node.js version conflicts

The managed installer supplies its own Node.js 22 runtime without changing your system Node.js. On Linux, the system must be able to run the official Node.js binaries. Installing the CLI from npm uses Node.js 22 or later from your own environment.

Install stops because zuku already exists

The installer won't overwrite a zuku or zukujs command that belongs to another program. Choose a different location with --prefix or -Prefix.

Linux Studio

Studio on Linux needs a graphical desktop plus the GTK 3 and WebKitGTK 4.1 system libraries. The installer does not install system packages.

Next steps#

Getting Started: create and run the starter game
Command reference: every command and flag
Errors: what error codes mean