vx upgrade

vx upgrade brings vx to a newer release (vx upgrade TAG pins one, v0.4.0 or 0.4.0; default latest; a second tag is refused, not dropped), the way it was installed. Named upgrade per CLI convention (bun upgrade, deno upgrade). Refuses when running from source: use git pull.

Usage

vx upgrade [TAG] [-g|--global]

Examples

In a project whose package.json lists @vzn/vx, beside a bun.lock:

› vx upgrade  0.0.1 → 0.0.2

  bun add @vzn/vx@0.0.2 in /repo

From a global vx in that project, both move:

› vx upgrade  project 0.0.1 → 0.0.2

  bun add @vzn/vx@0.0.2 in /repo

› vx upgrade  global 0.0.1 → 0.0.2

  /usr/local/bin/vx

✓ vx upgrade  global installed 0.0.2

Options

Option	Meaning
`TAG`	the release to install, `v0.4.0` or `0.4.0`; default latest
`-g`, `--global`	move only the global vx, below

A binary installed by hand

A compiled binary installed by hand replaces itself. It reads its platform package (@vzn/vx-<os>-<arch>) from the npm registry and checks npm’s registry signature over <name>@<version>:<integrity> against npm’s signing key, pinned in vx (key id SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U), then the tarball’s SHA-512 against that signed integrity, and only then extracts package/vx, stages it in a fresh directory beside the binary and renames it over. The host that serves the tarball cannot make that signature, so a swapped tarball, or a document with a swapped integrity, is refused: the npm registry signature for … is not valid — refusing to install; nothing replaced, or the download did not match the integrity npm signed … nothing replaced. A release signed with a key id vx does not pin says so: … is signed with an npm key this vx does not know (…) — if npm rotated its signing key, this vx's installer needs updating. A release with no signature or no integrity is refused before the download. Every refusal comes before anything is written. There is no fallback to GitHub’s release digest: when the registry is unreachable, the upgrade is refused.

A host it cannot reach (no route, a proxy that is down) is one line, could not reach registry.npmjs.org to read the release (…) — check the network or the proxy and re-run, never a stack; so is a document cut after the headers or not JSON (a captive portal’s page served with a 200), and a tarball cut the same way. A binary whose directory this user cannot write (a root-owned /usr/local/bin) is refused before the download: cannot write to <dir> (EACCES), where this vx lives — nothing downloaded; re-run as a user who can (sudo vx upgrade), …. The new binary keeps the old one’s mode (and, as root, its owner), and must answer --version before the upgrade reports it installed: one that does not start on this machine, or does not answer within 10 s, is swapped back for the previous vx, and the command exits 1 saying so (item 1097): ✓ vx upgrade installed 0.0.2. On the version it already is it says › vx upgrade already at <version> and downloads nothing.

A package manager’s install

A vx a package manager installed (the npm package’s launcher runs …/node_modules/@vzn/vx-<os>-<arch>/vx) is upgraded by that package manager, never by a rename over its file, which the next install would undo. The path names the install:

Install	Detected by	Runs
npm global	`<prefix>/lib/node_modules`	`npm install -g @vzn/vx@<v>`
pnpm global	`…/pnpm/global/…`	`pnpm add -g @vzn/vx@<v>`
bun global	`~/.bun/install/global`	`bun add -g @vzn/vx@<v>`
yarn global	`…/yarn/global/…`	`yarn global add @vzn/vx@<v>`
a project’s dependency	the package.json that lists `@vzn/vx`	its manager’s add, same field

A project’s package.json is the tree’s root, or for a hoisted workspace the nearest one above the current directory that lists @vzn/vx. Its manager is its lockfile (pnpm-lock.yaml, bun.lock, yarn.lock, package-lock.json), else packageManager, else npm; the field it is listed in is kept (--save-dev, --dev, …), and pnpm at a workspace root adds --workspace-root. The lockfile is updated by that manager. Every @vzn/vx-* plugin the same package.json lists from the registry moves in the same install, to the same release, since every @vzn package releases together: pnpm add @vzn/vx@0.0.2 @vzn/vx-otel@0.0.2 --save-dev. A plugin left behind is installed even when core is already at the release (› vx upgrade plugins → 0.0.2); a plugin in another field than core is refused, so no install moves a dependency’s field. The versions are pinned, so pnpm’s minimumReleaseAge refuses a release too young rather than mixing releases, and the error names minimumReleaseAgeExclude. vx prints what it runs, runs it there, and exits with an error if it fails:

A project’s vx and the global one

Inside a project with its own vx, a global vx hands vx upgrade to the project’s (§ Which vx runs), and one run moves both to the same version (TAG, or latest): first the project’s dependency, then the global vx that started the run, each the way it was installed. Each line names its install, and a refusal names the one that failed (vx upgrade: global vx /usr/local/bin/vx: cannot write to …); a project that fails leaves the global as it was. The project’s vx run directly (a package script, node_modules/.bin/vx) has no global behind it, so only the project moves.

vx upgrade -g (--global) moves only the global vx, wherever it runs: it never hands the call to a project’s vx, and it never touches a package.json or a plugin. Run as the project’s own vx, it refuses: vx upgrade -g: no global vx ran — <path> is the project's own. Install one (bun add -g @vzn/vx), or run \vx upgrade` to move the project’s`.

After the upgrade

After an upgrade that installed something, inside a workspace, the new vx runs vx lock at the workspace root, since a release may record the lock differently. A lock that fails leaves the upgrade done and prints vx upgrade vx lock failed: run vx lock. vx upgrade -g never locks.

vx never installs Node or a package manager: one not on PATH is refused with the command to run. A vx run from a bunx cache has nothing installed to upgrade, and says to ask for @vzn/vx@latest instead.

Exit codes

Code	When
`0`	installed, or already at that version
`1`	anything refused or swapped back: from source, a cache install, a host it cannot reach, a directory it cannot write, a signature or integrity that does not verify, a binary that does not start, a package manager that failed or is missing

Turborepo, Nx and other product names are trademarks of their owners. vx is not affiliated with or endorsed by them.