Skip to content

vc-env

A version manager for the vcluster CLI — install many vcluster versions side by side and let a shim pick the right one per shell, per directory, or per machine.

Get started Installation guide GitHub

Think of vc-env as tfenv / pyenv for vcluster. It installs each vcluster binary under $VCENV_ROOT/versions/<v>/vcluster, drops a shim on your PATH, and resolves the right version at every call — so vcluster create, vcluster connect and friends keep working unchanged, they just hit the version you actually want.

vc-env install 0.21.1      # download, checksum-verify, install
vc-env global  0.21.1      # or `vc-env local` / `vc-env shell`
vcluster version           # → 0.21.1

Why vc-env

  • Transparent shim

    $VCENV_ROOT/shims/vcluster is prepended to PATH and dispatches to the resolved binary — scripts, IDEs and CI call vcluster as usual.

    How selection works

  • Three-level version resolution

    Shell (VCENV_VERSION) > local (.vcluster-version, walked up) > global ($VCENV_ROOT/version). First match wins.

    CLI reference

  • Cached release list

    list-remote and latest go through a three-layer cache (baked-in baseline → disk → delta fetch), so they stay fast and respect the GitHub rate limit.

    Caching strategy

  • Atomic install + checksum

    vc-env install streams with a progress bar, verifies the SHA256 from the release, and writes atomically (temp + rename). An interrupted install never leaves a half-written binary.

    install command

  • Cross-platform

    Prebuilt binaries for darwin/amd64, darwin/arm64, linux/amd64 and linux/arm64; OS and CPU architecture are detected automatically.

    Supported platforms

  • Self-upgrade

    vc-env upgrade replaces the current binary in place with the latest stable release of vc-env — no package manager required.

    upgrade command

Install

Pick how you want to install the vc-env binary. The next step is always the same: export VCENV_ROOT and run eval "$(vc-env init)" in your shell profile.

os=$(uname -s | tr '[:upper:]' '[:lower:]')
arch=$(uname -m); case $arch in x86_64) arch=amd64 ;; aarch64) arch=arm64 ;; esac
curl -fsSL -o vc-env "https://github.com/mmpyro/vc-env/releases/download/v1.2.0/vc-env-$os-$arch"
chmod +x vc-env && sudo mv vc-env /usr/local/bin/vc-env
vc-env version

git clone https://github.com/mmpyro/vc-env.git
cd vc-env
make build
sudo mv build/vc-env /usr/local/bin/vc-env
vc-env version

make build-all
ls build/

Then wire the shim into your shell:

# in ~/.bashrc or ~/.zshrc
export VCENV_ROOT="$HOME/.vcenv"
eval "$(vc-env init)"
source <(vc-env completion bash)  # or: zsh / fish / powershell

Full install details, platform notes and troubleshooting: Installation and configuration.

What's next

Guide Read it when you want to…
Installation and configuration install vc-env, set VCENV_ROOT, wire the shim, and resolve common errors
CLI reference know every command, flag, environment variable and exit code
Caching strategy understand how list-remote / latest are cached and how to tune the TTL