# Installation and versions

npm package, platform binaries, updates, and building with Zig.

See versions, changes and requirements in [Framework 4.0 and CLI 1.2](/docs/guides/releases/).


<span id="usar-la-distribución-npm"></span>

<span class="section-anchor" id="section-1"></span>

## Using the npm distribution

```bash
npm install -g @wu-framework/cli@1.2.0
wu --version
wu --help
```

The package exposes the `wu` command through `bin/wu.js` and declares Node `>=20`. The launcher does not compile Zig during installation: it looks for a binary already packaged for the platform. Application dependencies are installed afterward, inside a project, using `wu install`.

For a temporary package invocation, use npm's executor:

```bash
npx @wu-framework/cli@1.2.0 --version
```

This invocation still requires Node/npm and may query the registry. It is not equivalent to executing the binary directly.

<span id="plataformas-seleccionadas-por-el-launcher"></span>

<span class="section-anchor" id="section-2"></span>

## Platforms selected by the launcher

| Node platform | Architecture | Expected file in `bin/` |
| --- | --- | --- |
| `win32` | `x64` | `wu-win32-x64.exe` |
| `linux` | `x64` | `wu-linux-x64` |
| `linux` | `arm64` | `wu-linux-arm64` |
| `darwin` | `x64` | `wu-darwin-x64` |
| `darwin` | `arm64` | `wu-darwin-arm64` |

The release publishes six packages: the launcher and five optional `@wu-framework/cli-<os>-<cpu>` packages, pinned exactly to `1.2.0`. npm selects the platform; Windows ARM64 uses the x64 binary. The launcher verifies the version and SHA-256 against `bin/SHA256SUMS`. This release also keeps all five binaries inside the root package as a fallback.

On Unix, if the system rejects the binary with `EACCES`, the launcher attempts to fix the executable permission and retries once. On Windows, its internal npm invocations run `npm.cmd` through the system interpreter.

Linux binaries are static musl builds and also run on Alpine. The release uses ReleaseSafe and exactly Zig `0.16.0`. If optional packages are missing, reinstall with `npm install -g @wu-framework/cli@1.2.0 --include=optional`; `wu update` already adds that option. An unsupported combination, wrong package version or mismatched checksum ends with a diagnostic and exit code `1`.

<span id="actualizar"></span>

<span class="section-anchor" id="section-3"></span>

## Updating

```bash
wu update
```

The launcher queries `@wu-framework/cli@latest`, validates the returned version, and compares SemVer. If it is higher, it globally installs that exact version. If npm cannot be queried or installation fails, it returns 1. It does not change framework dependencies inside projects.

The passive update notice uses a 24-hour cache, including failed queries. `wu update` queries again without waiting for that cache. `WU_DISABLE_UPDATE_CHECK=1` or an environment with `CI` skips the passive notice; neither disables an explicitly requested update.

```powershell
$env:WU_DISABLE_UPDATE_CHECK = '1'
wu --version
```

Running `wu.exe update` directly prints that updating belongs to the launcher and exits with 1. Use the npm-installed command to update.

Updating the CLI does not change the project: continue with `wu upgrade --dry-run`, review the Framework 4 migration, apply with `wu upgrade --yes` and run `wu install`. [Dependencies and migration](/docs/cli/dependencies/) explains pins, backups, codemods and CI exit codes.

<span id="construir-desde-el-código"></span>

<span class="section-anchor" id="section-4"></span>

## Building from source

`build.zig.zon` requires at least Zig **0.16.0**. The Zig package declares no external dependencies and builds an executable linked with libc.

```bash
zig build -Doptimize=ReleaseSafe
zig build test --summary all
zig build run -- --version
npm test
```

The `run` step forwards arguments after `--`. `npm test` checks invariants and Node tests for the launcher/compiler; this is a different suite from Zig test blocks. Compiling does not replace browser tests on a generated application.

For maintainers: `npm run build:binaries` generates the five platforms and their checksums. `node scripts/publish.mjs` runs checks and simulates publishing all six packages; only `--yes` publishes. It requires a clean tree, matching versions and valid binaries, and publishes platform packages before the launcher. Direct `npm publish` is rejected. This procedure distributes the CLI; it does not deploy an app.

<span id="diagnóstico-de-instalación"></span>

<span class="section-anchor" id="section-5"></span>

## Installation diagnostics

| Symptom | Check |
| --- | --- |
| `wu` is not recognized | Check the npm installation and that its executable directory is on PATH |
| `no usable executable` | Check the packaged binary or build the checkout with Zig |
| Unexpected version | Run `wu --version` and check which executable the shell resolves |
| Vue/Svelte compiler missing | Run `wu install` inside the project and review the microapp dependencies |
| Updating cannot reach the registry | Check connectivity and npm configuration; the passive notice does not block the requested command |

<span id="referencia-de-implementación"></span>

<span class="section-anchor" id="section-6"></span>

## Implementation references

- `wu-cli/package.json`
- `wu-cli/bin/wu.js`
- `wu-cli/scripts/build-all.mjs`
- `wu-cli/scripts/publish.mjs`
- `wu-cli/scripts/test-package.mjs`
- `wu-cli/tests/bin-wu.test.cjs`