A version manager for vcluster CLI, similar to tfenv and pyenv.

Manage multiple versions of the vcluster CLI and switch between them seamlessly.

• Docs index
• Installation and configuration
• CLI reference
• Caching strategy

Latest release: v1.0.0 (tag: v1.0.0).

• Install and manage multiple vcluster CLI versions
• Automatic version switching based on project directory (.vcluster-version)
• Shell-level, local (directory), and global version configuration
• Version priority: shell > local > global
• Auto-detection of OS and architecture for binary downloads
• Shim-based transparent proxying of vcluster commands

git clone https://github.com/mmpyro/vc-env.git
cd vc-env
make build

The binary will be at build/vc-env. Move it to a directory in your PATH:

sudo mv build/vc-env /usr/local/bin/

make build-all

This produces binaries for:

• linux/amd64
• linux/arm64
• darwin/amd64
• darwin/arm64

Add to your ~/.bashrc or ~/.zshrc:

export VCENV_ROOT="$HOME/.vcenv"

Reload your shell:

source ~/.bashrc  # or source ~/.zshrc

Add the following to your ~/.bashrc or ~/.zshrc (after the VCENV_ROOT export):

eval "$(vc-env init)"

This sets up:

• A vc-env shell function for vc-env shell support
• PATH prepend for the vcluster shim

# Install a specific version
vc-env install 0.21.1

# Install the latest stable version
vc-env install

# Set global default
vc-env global 0.21.1

# Set for current directory (creates .vcluster-version)
vc-env local 0.21.1

# Set for current shell session
vc-env shell 0.21.1

vcluster version

The shim automatically resolves and uses the correct version.

Full reference: docs/cli-reference.md

When vcluster is invoked, the version is resolved in this order:

1. Shell — VCENV_VERSION environment variable (set via vc-env shell)
2. Local — .vcluster-version file in the current or parent directories (set via vc-env local)
3. Global — $VCENV_ROOT/version file (set via vc-env global)

If no version is configured at any level, the command fails with an informative error.

Add the following to your ~/.bashrc:

# vc-env setup
export VCENV_ROOT="$HOME/.vcenv"
eval "$(vc-env init)"
source <(vc-env autocompletion)

Add the following to your ~/.zshrc:

# vc-env setup
export VCENV_ROOT="$HOME/.vcenv"
eval "$(vc-env init)"
source <(vc-env autocompletion)

vc-env uses a three-layer caching strategy to keep list-remote and latest fast and reliable. For more details on how it works and how to configure it, see docs/caching.md.

$VCENV_ROOT/
├── versions/           # Installed vcluster versions
│   ├── 0.21.1/
│   │   └── vcluster    # vcluster binary
│   └── 0.22.0/
│       └── vcluster
├── shims/
│   └── vcluster        # Shim script (auto-generated)
└── version             # Global version file

make test

make test-docker

make build          # Current platform
make build-all      # All platforms

See LICENSE for details.