Quick Start

This guide walks through the fastest path from a clean machine to a working vs setup.

1. Install vs

brew tap unsdk/tap
brew install vs

brew install unsdk/tap/vs

cargo install vs-cli

cargo install --git https://github.com/unsdk/vs vs-cli

curl -fsSL https://raw.githubusercontent.com/unsdk/vs/main/scripts/install.sh | bash

irm https://raw.githubusercontent.com/unsdk/vs/main/scripts/install.ps1 | iex

curl -fsSL https://raw.githubusercontent.com/unsdk/vs/main/scripts/install.sh | bash -s -- --version v0.0.2 --variant lua

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/unsdk/vs/main/scripts/install.ps1))) -Version v0.0.2 -Variant lua

cargo build -p vs-cli

cargo build -p vs-cli --no-default-features --features lua
cargo build -p vs-cli --no-default-features --features wasi
cargo build -p vs-cli --no-default-features --features full

cargo build -p vs-cli --profile min-size --no-default-features
cargo build -p vs-cli --profile min-size --no-default-features --features lua
cargo build -p vs-cli --profile min-size --no-default-features --features wasi

2. Choose the active home

The current implementation resolves the active home in this order:

1. VS_HOME, when it is set
2. otherwise ~/.vs

Example:

export VS_HOME="$HOME/.vs"

3. Point vs at a registry source

For local development, the repository ships a fixture registry index:

vs config registry.address /absolute/path/to/fixtures/registry/index.json
vs available

In current builds, registry.address accepts either a registry base URL or a direct local index.json path.

When vs is built with the lua feature and registry.address is unset, vs falls back to the official vfox plugin registry:

https://version-fox.github.io/vfox-plugins

Commands that need registry metadata, such as vs available, vs search, and vs add <name>, refresh the cached index automatically when a registry source is configured. In other words, the current CLI workflow is to configure registry.address and then use a registry-backed command, rather than running a standalone registry refresh command.

4. Add a plugin

Add a plugin from the registry:

vs add nodejs

Or add one directly from a source directory:

vs add nodejs --source /absolute/path/to/plugin --backend lua

5. Install and activate a runtime

Install a specific version:

vs install nodejs@20.11.1

Activate it globally:

vs use nodejs@20.11.1 -g

Check the active version:

vs current nodejs

6. Run a command through the resolved environment

vs exec nodejs node -v

This works even before shell activation.

7. Enable shell activation

Example for Bash:

eval "$(vs activate bash)"

Once activation is loaded, vs can react to directory changes and apply the currently resolved tool versions to the shell session.

Where to go next

• Read Configuration for file locations and precedence rules.
• Keep CLI Commands nearby while you are exploring the command surface.
• Review Shell Activation if you want shell-specific setup examples.