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

vx-usage