VX - Universal Development Tool Manager

vx is a universal development tool manager that automatically installs and manages development tools (Node.js, Python/uv, Go, Rust, etc.) with zero configuration.

Core Concept

Instead of requiring users to manually install tools, prefix any command with vx:

bash
1vx node --version      # Auto-installs Node.js if needed
2vx uv pip install x    # Auto-installs uv if needed
3vx go build .          # Auto-installs Go if needed
4vx cargo build         # Auto-installs Rust if needed
5vx just test           # Auto-installs just if needed

vx is fully transparent - same commands, same arguments, just add vx prefix.

Essential Commands

Tool Execution (most common)

bash
1vx <tool> [args...]           # Run any tool (auto-installs if missing)
2vx node app.js                # Run Node.js
3vx python script.py           # Run Python (via uv)
4vx npm install                # Run npm
5vx npx create-react-app app   # Run npx
6vx cargo test                 # Run cargo
7vx just build                 # Run just (task runner)
8vx git status                 # Run git

Tool Management

bash
1vx install node@22            # Install specific version
2vx install uv go rust         # Install multiple tools at once
3vx list                       # List all available tools
4vx list --installed           # List installed tools only
5vx versions node              # Show available versions
6vx switch node@20             # Switch active version
7vx uninstall go@1.21          # Remove a version

Project Management

bash
1vx init                       # Initialize vx.toml for project
2vx sync                       # Install all tools from vx.toml
3vx setup                      # Full project setup (sync + hooks)
4vx dev                        # Enter dev environment with all tools
5vx run test                   # Run project scripts from vx.toml
6vx check                      # Verify tool constraints
7vx lock                       # Generate vx.lock for reproducibility

Environment & Config

bash
1vx env list                   # List environments
2vx config show                # Show configuration
3vx cache info                 # Show cache usage
4vx search <query>             # Search available tools
5vx info                       # System info and capabilities

Project Configuration (vx.toml)

Projects use vx.toml in the root directory:

toml
1[tools]
2node = "22"         # Major version
3go = "1.22"         # Minor version
4uv = "latest"       # Always latest
5rust = "1.80"       # Specific version
6just = "*"          # Any version
7
8[scripts]
9dev = "npm run dev"
10test = "cargo test"
11lint = "npm run lint && cargo clippy"
12build = "just build"
13
14[hooks]
15pre_commit = ["vx run lint"]
16post_setup = ["npm install"]

Using --with for Multi-Runtime

When a command needs additional runtimes available:

bash
1vx --with bun node app.js     # Node.js + Bun in PATH
2vx --with deno npm test        # npm + Deno available

Package Aliases

vx supports package aliases — short commands that automatically route to ecosystem packages:

bash
1# These are equivalent:
2vx vite              # Same as: vx npm:vite
3vx vite@5.0          # Same as: vx npm:vite@5.0
4vx rez               # Same as: vx uv:rez
5vx pre-commit        # Same as: vx uv:pre-commit
6vx meson             # Same as: vx uv:meson
7vx release-please    # Same as: vx npm:release-please

Benefits:

• Simpler commands without remembering ecosystem prefixes
• Automatic runtime dependency management (node/python installed as needed)
• Respects project vx.toml version configuration

Available Aliases:

Companion Tool Environment Injection

When vx.toml includes tools like MSVC, vx automatically injects discovery environment variables into all subprocess environments. This allows any tool needing a C/C++ compiler to discover the vx-managed installation.

toml
1# vx.toml — MSVC env vars injected for ALL tools
2[tools]
3node = "22"
4cmake = "3.28"
5rust = "1.82"
6
7[tools.msvc]
8version = "14.42"
9os = ["windows"]

Now tools like node-gyp, CMake, Cargo (cc crate) automatically find MSVC:

bash
1# node-gyp finds MSVC via VCINSTALLDIR
2vx npx node-gyp rebuild
3
4# CMake discovers the compiler
5vx cmake -B build -G "Ninja"
6
7# Cargo cc crate finds MSVC for C dependencies
8vx cargo build

Injected Environment Variables (MSVC example):

MSVC Build Tools (Windows)

Microsoft Visual C++ compiler for Windows development:

bash
1# Install MSVC Build Tools
2vx install msvc@latest
3vx install msvc 14.40       # Specific version
4
5# Using MSVC tools via namespace
6vx msvc cl main.cpp -o main.exe
7vx msvc link main.obj
8vx msvc nmake
9
10# Direct aliases
11vx cl main.cpp              # Same as: vx msvc cl
12vx nmake                    # Same as: vx msvc nmake
13
14# Version-specific usage
15vx msvc@14.40 cl main.cpp

Available MSVC Tools:

Supported Tools (50+)

Important Rules for AI Agents

1. Always use vx prefix when running tools in vx-managed projects
2. Use vx just instead of just for task runner commands
3. Use vx npm instead of npm directly
4. Use vx cargo instead of cargo directly
5. Check vx.toml first to understand project tool requirements
6. Use vx run <script> for project-defined scripts
7. Never suggest manual tool installation - vx handles it automatically
8. Commands like vx install are for explicit pre-installation; normal usage auto-installs

GitHub Actions Integration

vx provides a GitHub Action (action.yml) for CI/CD workflows. Use it in .github/workflows/ files:

Basic Usage

yaml
1- uses: loonghao/vx@main
2  with:
3    version: 'latest'           # vx version (default: latest)
4    github-token: ${{ secrets.GITHUB_TOKEN }}

Pre-install Tools

yaml
1- uses: loonghao/vx@main
2  with:
3    tools: 'node go uv'         # Space-separated tools to pre-install
4    cache: 'true'               # Enable tool caching (default: true)

Project Setup (vx.toml)

yaml
1- uses: loonghao/vx@main
2  with:
3    setup: 'true'               # Run `vx setup --ci` for vx.toml projects

Full Example

yaml
1name: CI
2on: [push, pull_request]
3
4jobs:
5  build:
6    runs-on: ${{ matrix.os }}
7    strategy:
8      matrix:
9        os: [ubuntu-latest, macos-latest, windows-latest]
10
11    steps:
12      - uses: actions/checkout@v6
13
14      - uses: loonghao/vx@main
15        with:
16          tools: 'node@22 uv'
17          setup: 'true'
18          cache: 'true'
19
20      - run: vx node --version
21      - run: vx npm test

Action Inputs

Action Outputs

Docker Support

vx provides a Docker image for containerized workflows:

dockerfile
1# Use vx as base image
2FROM ghcr.io/loonghao/vx:latest
3
4# Tools are auto-installed on first use
5RUN vx node --version
6RUN vx uv pip install mypackage

Multi-stage Build with vx

dockerfile
1FROM ghcr.io/loonghao/vx:latest AS builder
2RUN vx node --version && vx npm ci && vx npm run build
3
4FROM nginx:alpine
5COPY --from=builder /home/vx/dist /usr/share/nginx/html

GitHub Actions with Docker

yaml
1jobs:
2  build:
3    runs-on: ubuntu-latest
4    container:
5      image: ghcr.io/loonghao/vx:latest
6    steps:
7      - uses: actions/checkout@v6
8      - run: vx node --version
9      - run: vx npm test