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 :

vx node --version # Auto-installs Node.js if needed vx uv pip install x # Auto-installs uv if needed vx go build . # Auto-installs Go if needed vx cargo build # Auto-installs Rust if needed vx 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)

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

Tool Management

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

Project Management

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

Environment & Config

vx env list # List environments vx config show # Show configuration vx cache info # Show cache usage vx search <query> # Search available tools vx info # System info and capabilities

Project Configuration (vx.toml)

Projects use vx.toml in the root directory:

[tools] node = "22" # Major version go = "1.22" # Minor version uv = "latest" # Always latest rust = "1.80" # Specific version just = "*" # Any version

[scripts] dev = "npm run dev" test = "cargo test" lint = "npm run lint && cargo clippy" build = "just build"

[hooks] pre_commit = ["vx run lint"] post_setup = ["npm install"]

Using --with for Multi-Runtime

When a command needs additional runtimes available:

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

Supported Tools (50+)

Category Tools

JavaScript node, npm, npx, bun, deno, pnpm, yarn, vite

Python uv, uvx, python, pip

Rust cargo, rustc, rustup

Go go, gofmt

System git, just, jq, cmake, make, ninja, meson

Cloud docker, kubectl, helm, awscli, azcli, gcloud, terraform

.NET dotnet, msbuild, nuget

Other zig, java, protoc, ffmpeg, gh, ollama, dagu, skills

Important Rules for AI Agents

• Always use vx prefix when running tools in vx-managed projects

• Use vx just instead of just for task runner commands

• Use vx npm instead of npm directly

• Use vx cargo instead of cargo directly

• Check vx.toml first to understand project tool requirements

• Use vx run <script> for project-defined scripts

• Never suggest manual tool installation - vx handles it automatically

• 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

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

Pre-install Tools

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

Project Setup (vx.toml)

• uses: loonghao/vx@main with: setup: 'true' # Run vx setup --ci for vx.toml projects

Full Example

name: CI on: [push, pull_request]

jobs: build: runs-on: ${{ matrix.os }} strategy: matrix: os: [ubuntu-latest, macos-latest, windows-latest]

steps:
  - uses: actions/checkout@v6

  - uses: loonghao/vx@main
    with:
      tools: 'node@22 uv'
      setup: 'true'
      cache: 'true'

  - run: vx node --version
  - run: vx npm test

Action Inputs

Input Default Description

version

latest

vx version to install

github-token

${{ github.token }}

GitHub token for API requests

tools

''

Space-separated tools to pre-install

cache

true

Enable caching of ~/.vx directory

cache-key-prefix

vx-tools

Custom prefix for cache key

setup

false

Run vx setup --ci for vx.toml projects

Action Outputs

Output Description

version

The installed vx version

cache-hit

Whether the cache was hit

Docker Support

vx provides a Docker image for containerized workflows:

Use vx as base image

FROM ghcr.io/loonghao/vx:latest

Tools are auto-installed on first use

RUN vx node --version RUN vx uv pip install mypackage

Multi-stage Build with vx

FROM ghcr.io/loonghao/vx:latest AS builder RUN vx node --version && vx npm ci && vx npm run build

FROM nginx:alpine COPY --from=builder /home/vx/dist /usr/share/nginx/html

GitHub Actions with Docker

jobs: build: runs-on: ubuntu-latest container: image: ghcr.io/loonghao/vx:latest steps: - uses: actions/checkout@v6 - run: vx node --version - run: vx npm test