vix upgrade

vix upgrade updates the local Vix environment.

It can upgrade the vix CLI itself, install or upgrade SDK profiles, and upgrade globally installed packages from the Vix registry. The command is intentionally centered on the developer machine, not on one project directory. Use it when the local Vix installation needs to move to a newer release, when a project needs a native SDK profile that is not installed yet, or when a global package should be refreshed.

vix upgrade

In the normal Vix workflow, the CLI is the bootstrap. SDK profiles provide the native development layer used by vix build, vix run, and vix dev. vix upgrade is the command that keeps both layers current.

What it upgrades

vix upgrade has three modes.

vix upgrade                  upgrade the Vix CLI
vix upgrade --sdk web        install or upgrade a SDK profile
vix upgrade -g gk/jwt        upgrade a globally installed package

The default mode is the CLI upgrade. SDK mode is selected with --sdk. Global package mode is selected with -g or --global.

Upgrade the CLI

Run vix upgrade without extra mode flags to upgrade the CLI.

vix upgrade

This resolves the latest release, downloads the CLI asset for the current platform, verifies it, and replaces the local vix binary.

Check the installed version after the upgrade:

vix --version

Then inspect the environment:

vix doctor

This is the usual flow after updating the command-line tool.

vix upgrade
vix --version
vix doctor

Install a specific CLI version

Use a release tag when the machine should install a specific version instead of the latest release.

vix upgrade v2.7.0

The explicit option form is also accepted.

vix upgrade --version v2.7.0

This is useful for release testing, reproducing a build environment, or moving a machine to the same version used by the rest of a team.

Check before upgrading

Use --check when you only want to know whether an update is available.

vix upgrade --check

This does not install anything. It resolves the target version and compares it with the current CLI version when the local version can be detected.

For a scripted environment:

vix upgrade --check --json

Use --check when the command should report state without changing the filesystem.

Dry run

Use --dry-run when you want to see the upgrade plan without downloading or installing files.

vix upgrade --dry-run

For a specific version:

vix upgrade --version v2.7.0 --dry-run

Dry run is useful before changing a production machine, a CI image, or a development environment that needs to stay stable.

JSON output

Use --json when the command is called from scripts or automation.

vix upgrade --check --json

vix upgrade --dry-run --json

vix upgrade --sdk web --json

JSON output is designed for machines. Human progress output is suppressed so scripts do not need to parse styled terminal text.

Verbose output

Use --verbose when you need more diagnostic information.

vix upgrade --verbose

Verbose output is useful when a download fails, when a platform asset is missing, when a permission issue prevents replacement, or when you need to understand which command is being executed under the hood.

You can combine it with dry run:

vix upgrade --dry-run --verbose

SDK profiles

Use --sdk to install or upgrade a Vix SDK profile.

vix upgrade --sdk web

SDK profiles are the native Vix module sets used by projects. A backend service, a database project, a desktop shell, a P2P node, a game project, and an agent workflow do not need the same native modules. Profiles make that difference explicit while keeping the project workflow centered on the CLI.

After a profile is installed, build and run normally:

vix build
vix run
vix dev

The project does not need a manual SDK path in normal Vix workflows. The CLI resolves the installed SDK profile from the local Vix environment.

Install the default SDK

When --sdk is used without a profile, Vix installs or upgrades the default SDK profile.

vix upgrade --sdk

This is equivalent to:

vix upgrade --sdk default

Use the default profile for normal Vix.cpp projects, local development, and first-time setup when the project does not need a specialized module family yet.

List SDK profiles

Use --sdk list to see which SDK profile assets are available for the current release and platform.

vix upgrade --sdk list

This command does not install a profile. It checks the release assets and prints the profiles that can be installed.

Use JSON output when another tool needs to consume the result.

vix upgrade --sdk list --json

Inspect a SDK profile

Use --sdk info before installing a profile.

vix upgrade --sdk info web

The profile information shows the profile description, included modules, system dependencies, notes, and documentation link. This is the safest way to confirm whether a machine needs web, data, desktop, p2p, game, agent, or all.

The shortcut form is also available:

vix upgrade --sdk-info web

You can also write:

vix upgrade --sdk web --info

Use this command before installing a large profile, especially desktop, game, or all, because those profiles may require additional system libraries.

Available SDK profiles

default   normal Vix.cpp projects and local development
web       HTTP, middleware, WebSocket, validation, crypto, WebRPC, requests
data      database, ORM, KV, and cache workflows
desktop   desktop apps with the Vix UI desktop shell
p2p       peer-to-peer networking and local-first systems
game      game and realtime rendering workflows
agent     agent tooling and controlled automation workflows
all       complete SDK profile

The all profile is a complete SDK profile. It is not a shortcut that installs every smaller profile one by one.

Install one SDK profile

Install a profile by name:

vix upgrade --sdk web

Install a specific version of a profile:

vix upgrade --sdk web --version v2.7.0

After installation, inspect the profile again:

vix upgrade --sdk info web

Then verify that the environment is healthy:

vix doctor

Install multiple SDK profiles

A machine can have more than one SDK profile installed.

vix upgrade --sdk web data desktop

Comma-separated profiles are also accepted:

vix upgrade --sdk web,data,desktop

This is useful when one development machine is used for several kinds of projects. For example, the same machine may build a backend API with the web profile and a database tool with the data profile.

Install multiple profiles for a specific version:

vix upgrade --sdk web data --version v2.7.0

Where SDK profiles are installed

SDK profiles are installed under the Vix home directory.

~/.vix/sdk/<profile>/<version>/

Each profile can also have a current pointer and metadata file.

~/.vix/sdk/web/current
~/.vix/sdk/web/current.json

This lets the CLI resolve the active profile version without asking the user to pass a path every time.

Verify a SDK profile

After installing a profile, run a simple check.

cat > main.cpp <<'CPP'
#include <vix.hpp>

int main()
{
  vix::print("Hello from Vix.cpp");
  return 0;
}
CPP

vix run main.cpp

Expected output:

Hello from Vix.cpp

For a profile-specific module, use a small file that includes the module you need. For example, after installing the web profile:

cat > main.cpp <<'CPP'
#include <vix/requests/requests.hpp>
#include <vix/print.hpp>

int main()
{
  auto response = vix::requests::get("https://example.com/");

  vix::print("status:", response.status_code());
  return 0;
}
CPP

vix run main.cpp

If this compiles and runs, the CLI can find the installed SDK profile.

Global package upgrades

Use -g or --global to upgrade a package that is already installed globally.

vix upgrade -g gk/jwt

Scoped package syntax is accepted:

vix upgrade -g @gk/jwt

Install a specific package version:

vix upgrade -g gk/jwt@1.0.0

Global package upgrades use the local registry index and the global package manifest under the Vix home directory. The command resolves the package from the registry, checks the currently installed global package, then refreshes it when the target commit is different.

A global package must already be installed globally. If the package is not known in the global manifest, the command reports that the global package is not installed.

Check a global package

Use --check to inspect the target without installing.

vix upgrade -g gk/jwt --check

Use --dry-run to preview the upgrade plan.

vix upgrade -g gk/jwt --dry-run

Use JSON for scripts:

vix upgrade -g gk/jwt --check --json

Registry state for global packages

Global package upgrades depend on the local registry index.

If a package cannot be found, sync the registry first:

vix registry sync

Then try again:

vix upgrade -g gk/jwt

This keeps global package upgrades tied to the same registry workflow used by normal Vix package management.

Verification

CLI and SDK upgrades use GitHub Releases.

The downloaded artifact is verified with SHA-256. On Unix systems, minisign verification is also used when minisign is available. If the checksum cannot be verified, the upgrade should not continue.

This gives the command a clear rule: downloaded release assets must be checked before they are installed.

Environment variables

vix upgrade supports a small set of environment overrides.

VIX_REPO       override the GitHub repository used for CLI and SDK upgrades
VIX_CLI_PATH   override current Vix binary path detection

The default repository is:

vixcpp/vix

A maintainer can point upgrade checks to another repository when testing release assets.

VIX_REPO=my-org/vix vix upgrade --check

Use VIX_CLI_PATH when the command needs to detect or replace a specific local binary.

VIX_CLI_PATH="$HOME/.local/bin/vix" vix upgrade --check

Most users should not need these variables.

Common workflows

Update the CLI:

vix upgrade
vix --version
vix doctor

Check first, then upgrade:

vix upgrade --check
vix upgrade

Preview a CLI upgrade:

vix upgrade --dry-run

Install the Web SDK:

vix upgrade --sdk web
vix upgrade --sdk info web

Install SDK profiles for a multi-project machine:

vix upgrade --sdk web data desktop

Install a specific release:

vix upgrade --version v2.7.0
vix upgrade --sdk web --version v2.7.0

Upgrade a global package:

vix upgrade -g gk/jwt

Common mistakes

Confusing upgrade and update

vix upgrade changes the local Vix environment: the CLI, SDK profiles, or globally installed packages.

Project dependencies are handled by the project dependency workflow.

vix update

Use upgrade for the toolchain environment. Use update when a project dependency graph needs to move to newer package versions.

Installing only the CLI

The CLI gives you the command surface, but SDK profiles provide the native Vix layer used by project builds.

vix upgrade --sdk web

Install the profile that matches the modules used by the project.

Using the default SDK for web modules

The default SDK is the base profile. It does not include the web module family.

If the project uses vix::requests, WebSocket, middleware, validation, crypto, or WebRPC, install the web profile.

vix upgrade --sdk web

Installing all by default

The full SDK works, but it is usually more than a normal project needs.

vix upgrade --sdk all

For a backend or API, use web.

vix upgrade --sdk web

For database or ORM work, use data.

vix upgrade --sdk data

Use all when the machine really needs the complete platform.

Expecting --sdk list to install anything

This command only lists available SDK assets.

vix upgrade --sdk list

Install a profile explicitly:

vix upgrade --sdk web

Upgrading a global package that is not installed globally

vix upgrade -g upgrades a globally installed package. It does not silently create a new global install when the package is missing from the global manifest.

Check your global packages first with the package listing workflow, then upgrade the package name that is actually installed.

vix list -g
vix upgrade -g gk/jwt

Ignoring permissions

If the CLI was installed into a system location, the upgrade may need permissions that match that installation.

For user installs, prefer a user-writable location such as:

~/.local/bin/vix

If an upgrade fails with a permission error, fix the install location or run the command with the permissions required by that location.

Troubleshooting

vix upgrade --check cannot resolve the latest release

The command needs network access to GitHub Releases.

Try a specific version:

vix upgrade --version v2.7.0 --dry-run

Then run the upgrade when the network path is working.

SDK profile is unknown

Check the profile name.

vix upgrade --sdk list

Supported profile names are:

default
web
data
desktop
p2p
game
agent
all

SDK asset is not available

SDK profiles are release assets. Availability depends on the release and platform.

Check the current release first:

vix upgrade --sdk list

Then inspect the profile:

vix upgrade --sdk info web

Use a specific release if needed:

vix upgrade --sdk web --version v2.7.0

Package cannot be found for global upgrade

Refresh the registry index:

vix registry sync

Then retry:

vix upgrade -g gk/jwt

Need machine-readable failure output

Add --json.

vix upgrade --sdk web --json

The command returns structured error information instead of styled human output.

Command summary

vix upgrade
vix upgrade vX.Y.Z
vix upgrade --version vX.Y.Z

vix upgrade --check
vix upgrade --dry-run
vix upgrade --json
vix upgrade --verbose

vix upgrade --sdk
vix upgrade --sdk default
vix upgrade --sdk web
vix upgrade --sdk list
vix upgrade --sdk info web
vix upgrade --sdk-info web
vix upgrade --sdk web --version vX.Y.Z
vix upgrade --sdk web data desktop
vix upgrade --sdk web,data,desktop

vix upgrade -g gk/jwt
vix upgrade -g gk/jwt@1.0.0
vix upgrade -g @gk/jwt

Options

Option	Meaning
-g, --global	Upgrade a globally installed package
--sdk [profile]	Install or upgrade a Vix SDK profile
--sdk list	List SDK profile assets available in the current release
--sdk info [profile]	Show modules, system dependencies, notes, and docs for a profile
--sdk-info <profile>	Shortcut for vix upgrade --sdk info <profile>
--version <tag>	Use a specific release tag
--check	Check the target version without installing
--dry-run	Simulate without changing files
--json	Print machine-readable JSON output
--verbose	Print diagnostic details
-h, --help	Show command help

Next step

Use vix uninstall when you need to remove the CLI, remove SDK profiles, or remove globally installed packages from the local machine.

Open the uninstall guide