Quick Start

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

1. Build the CLI

During development, build the default CLI binary from the workspace root:

cargo build -p vs-cli

The resulting binary is written to target/debug/vs.

Backend-specific builds are also supported:

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

For smaller distributable binaries, the workspace also exposes a size-focused profile:

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.