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

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