vx - Universal Development Tool Manager

One command to rule them all -- Zero setup, Zero learning curve

Built for the AI-native era: Unix Philosophy meets Scriptability

中文文档 | Documentation | Quick Start | Examples

---

Built for AI-Native Development

vx follows the Unix Philosophy and Scriptability principles recommended by Anthropic for AI-native development tools:

Principle	How vx Implements It
Unix Philosophy	One tool, one job -- vx manages all runtimes transparently
Scriptability	Full bash integration, CI/CD ready, headless mode support
Composability	Works with any AI coding assistant (Claude Code, Cursor, Copilot)
Zero Configuration	AI agents can use any tool without environment setup

When AI agents like Claude Code need to execute commands across different ecosystems:

# Without vx: AI must handle complex environment setup
# "First install Node.js, then configure npm, set PATH..."

# With vx: AI just runs commands directly
vx npx create-react-app my-app  # Works immediately
vx uvx ruff check .             # Works immediately
vx cargo build --release        # Works immediately

vx enables AI to have full-stack development capabilities without worrying about environment management and dependencies.

---

Design Philosophy

The Problem

Every time we start a new development project, we face the same frustrating cycle:

• Install Node.js and npm for frontend tools
• Set up Python and pip/uv for scripts and automation
• Configure Go for backend services
• Manage Rust toolchain for system tools
• Deal with version conflicts and PATH issues
• Repeat this process across different machines and environments

With the rise of MCP (Model Context Protocol), this problem has become even more pronounced. Many MCP servers require uvx for Python tools and npx for Node.js packages, forcing developers to manage multiple tool ecosystems just to get AI assistance working.

The Solution: Zero Learning Curve

vx eliminates this complexity while maintaining zero learning curve:

# Instead of learning and managing multiple tools:
npx create-react-app my-app     # Requires Node.js setup
uvx ruff check .                # Requires Python/UV setup
go run main.go                  # Requires Go installation

# Just use vx with the same commands you already know:
vx npx create-react-app my-app  # Auto-installs Node.js if needed
vx uvx ruff check .             # Auto-installs UV if needed
vx go run main.go               # Auto-installs Go if needed

---

Quick Start

Installation

Linux/macOS:

curl -fsSL https://raw.githubusercontent.com/loonghao/vx/main/install.sh | bash

Windows (PowerShell):

powershell -c "irm https://raw.githubusercontent.com/loonghao/vx/main/install.ps1 | iex"

Stable Installation in Rate-Limited Networks

# 1) Pin a stable installer version (recommended for CI and enterprise networks)
VX_VERSION="0.9.6" curl -fsSL https://raw.githubusercontent.com/loonghao/vx/main/install.sh | bash

# 2) Configure multi-source release mirrors (comma separated)
VX_RELEASE_BASE_URLS="https://mirror.example.com/vx/releases,https://github.com/loonghao/vx/releases" \
  curl -fsSL https://raw.githubusercontent.com/loonghao/vx/main/install.sh | bash

# Windows mirror fallback (comma/semicolon separated)
$env:VX_RELEASE_BASE_URLS="https://mirror.example.com/vx/releases,https://github.com/loonghao/vx/releases"
powershell -c "irm https://raw.githubusercontent.com/loonghao/vx/main/install.ps1 | iex"

The installer will try all configured release base URLs automatically, then fallback across different asset naming patterns.

Start Using Immediately

# No setup needed - just prefix your commands with 'vx'
vx node --version               # Auto-installs Node.js
vx python --version             # Auto-installs Python via UV
vx go version                   # Auto-installs Go
vx cargo --version              # Auto-installs Rust

---

Two Ways to Use vx

1. Direct Execution (For Quick Tasks)

Just prefix any command with vx -- tools are auto-installed on first use:

# Run any tool instantly
vx npx create-react-app my-app
vx uvx ruff check .
vx go run main.go
vx cargo build --release

2. Project Development Environment (For Teams)

Create a vx.toml file to define your project's tool requirements:

# Initialize a new project
vx init

# Or create vx.toml manually
cat > vx.toml << 'EOF'
[tools]
node = "20"
python = "3.12"
uv = "latest"
go = "1.21"

[scripts]
dev = "npm run dev"
test = "npm test"
lint = "uvx ruff check ."
EOF

Then use the development environment commands:

# One-click setup: install all project tools
vx setup

# Enter development shell with all tools available
vx dev

# Run project scripts
vx run dev
vx run test
vx run lint

# Manage project tools
vx add bun                      # Add a tool
vx remove go                    # Remove a tool
vx sync                         # Sync tools with vx.toml

---

Command Reference

Tool Execution

Command	Description
vx <runtime>[@version] [args...]	Execute a runtime (auto-installs if needed)
vx <runtime>[@version]::<executable> [args...]	Execute specific executable from a runtime
vx <ecosystem>:<package>[::executable] [args...]	Execute a package (RFC 0027)
vx --with <runtime>[@version] <command>	Inject companion runtimes for this invocation
vx install <runtime>@<version>	Install a specific runtime version
vx uninstall <runtime>[@version]	Uninstall runtime versions
vx switch <runtime>@<version>	Switch to a different version
vx which <runtime>	Show which version is being used
vx versions <runtime>	Show available versions
vx list	List all supported runtimes
vx search <query>	Search available runtimes

Shell and Environment

Command	Description
vx shell launch <runtime>[@version] [shell]	Launch shell with runtime environment (canonical)
vx dev	Enter development shell with project tools
vx dev -c <cmd>	Run a command in the dev environment

Global Package Management (vx pkg)

Command	Description
vx pkg install <ecosystem>:<package>	Install a global package
vx pkg uninstall <ecosystem>:<package>	Uninstall a global package
vx pkg list	List globally installed packages
vx pkg info <ecosystem>:<package>	Show package information

Project Management

Command	Description
vx init	Initialize project configuration (vx.toml)
vx setup	Install all tools defined in vx.toml
vx sync	Sync installed tools with vx.toml
vx lock	Generate or update vx.lock for reproducibility
vx check	Check version constraints and tool availability
vx add <runtime>	Add a runtime to project configuration
vx remove <runtime>	Remove a runtime from project configuration
vx run <script>	Run a script defined in vx.toml

System Management

Command	Description
vx cache info	Show disk usage and cache statistics
vx cache prune	Clean up cache and orphaned packages
vx config	Manage global configuration
vx self-update	Update vx itself
vx provider list	List available providers

---

Project Configuration (vx.toml)

# VX Project Configuration
# Run 'vx setup' to install all tools
# Run 'vx dev' to enter the development environment

[tools]
node = "20"                     # Major version
python = "3.12"                 # Minor version
uv = "latest"                   # Always latest
go = "1.21.6"                   # Exact version
rustup = "latest"               # Rust toolchain manager

[settings]
auto_install = true             # Auto-install missing tools in dev shell
parallel_install = true         # Install tools in parallel

[env]
NODE_ENV = "development"
DEBUG = "true"

[scripts]
dev = "npm run dev"
test = "npm test && cargo test"
build = "npm run build"
lint = "uvx ruff check . && npm run lint"
format = "uvx ruff format . && npm run format"
# Enhanced: Use {{args}} for complex tool arguments
test-pkgs = "cargo test {{args}}"
lint-fix = "eslint {{args}}"

Enhanced Script System

vx supports advanced argument passing for complex tool workflows:

# Pass complex arguments directly to tools
vx run test-pkgs -p vx-runtime --lib
vx run lint-fix --fix --ext .js,.ts src/

# Get script-specific help
vx run test-pkgs -H

# List all available scripts
vx run --list

Key Features:

• Zero conflicts: Pass -p, --lib, --fix directly to scripts
• Script help: Use -H for script-specific documentation
• Flexible arguments: Use {{args}} in script definitions for maximum flexibility
• Backward compatible: Existing scripts continue to work

---

MCP Integration

vx was designed with MCP (Model Context Protocol) in mind. Just change the command from the tool name to vx:

Before (Complex Setup Required)

{
  "mcpServers": {
    "browsermcp": {
      "command": "npx",
      "args": ["-y", "@browsermcp/mcp@latest"]
    },
    "python-tool": {
      "command": "uvx",
      "args": ["some-python-tool@latest"]
    }
  }
}

After (Zero Setup with vx)

{
  "mcpServers": {
    "browsermcp": {
      "command": "vx",
      "args": ["npx", "-y", "@browsermcp/mcp@latest"]
    },
    "python-tool": {
      "command": "vx",
      "args": ["uvx", "some-python-tool@latest"]
    }
  }
}

---

Real-World Examples

Team Onboarding

# New team member joins the project
git clone https://github.com/your-org/your-project
cd your-project

# One command to set up everything
vx setup

# Start developing
vx dev

Multi-Language Project

# Frontend (Node.js) + Backend (Go) + Scripts (Python)
cat > vx.toml << 'EOF'
[tools]
node = "20"
go = "1.21"
uv = "latest"

[scripts]
frontend = "npm run dev"
backend = "go run cmd/server/main.go"
migrate = "uvx alembic upgrade head"
EOF

# Install everything
vx setup

# Run different parts
vx run frontend
vx run backend
vx run migrate

Python Development

vx uv init my-python-app
cd my-python-app
vx uv add fastapi uvicorn
vx uv add --dev pytest ruff
vx uv run uvicorn main:app --reload
vx uvx ruff check .

Node.js Development

vx npx create-react-app my-app
cd my-app
vx npm install
vx npm run dev

Go Development

vx go mod init my-go-app
vx go run main.go
vx go build -o app

Rust Development

vx cargo new my-rust-app
cd my-rust-app
vx cargo add serde tokio
vx cargo run

---

Supported Tools (142 providers)

vx manages 142 tools via Starlark DSL providers. Below are some highlights:

Language Runtimes

Tool	Commands	Description
Node.js	node, npm, npx	JavaScript runtime and package manager
Bun	bun, bunx	Fast all-in-one JavaScript runtime
Deno	deno	Secure JavaScript/TypeScript runtime
Go	go	Go programming language
Rust	cargo, rustc, rustup	Rust toolchain
Java	java, javac	Java Development Kit
Zig	zig	Zig programming language
Python	python (via UV)	Python runtime
.NET	dotnet	.NET SDK and runtime

Package Managers

Tool	Commands	Description
UV	uv, uvx	Fast Python package manager
pnpm	pnpm, pnpx	Fast, disk-efficient package manager
Yarn	yarn	JavaScript package manager
Conda	conda	Cross-platform package manager

Build Tools

Tool	Commands	Description
Just	just	Command runner for project tasks
Task	task	Task runner / build tool (go-task)
CMake	cmake	Cross-platform build system generator
Ninja	ninja	Small build system focused on speed
Meson	meson	High-productivity build system
xmake	xmake	Cross-platform build utility
protoc	protoc	Protocol Buffers compiler

DevOps and Cloud Tools

Tool	Commands	Description
Podman	podman	Container runtime and tooling
Terraform	terraform	Infrastructure as Code
kubectl	kubectl	Kubernetes CLI
Helm	helm	Kubernetes package manager
AWS CLI	aws	Amazon Web Services CLI
Azure CLI	az	Microsoft Azure CLI
gcloud	gcloud	Google Cloud Platform CLI
k3d	k3d	Lightweight Kubernetes in Docker
Skaffold	skaffold	Continuous development for Kubernetes

Code Quality and Security

Tool	Commands	Description
Ruff	ruff	Fast Python linter and formatter
Biome	biome	Fast formatter and linter for web
oxlint	oxlint	Oxidized JavaScript linter
golangci-lint	golangci-lint	Go linters aggregator
Trivy	trivy	Security scanner
Grype	grype	Vulnerability scanner
gitleaks	gitleaks	Secret scanning

CLI Utilities

Tool	Commands	Description
ripgrep	rg	Fast regex search
fd	fd	Fast file finder
bat	bat	Cat with syntax highlighting
fzf	fzf	Fuzzy finder
jq	jq	JSON processor
yq	yq	YAML/JSON/XML processor
delta	delta	Better git diff
lazygit	lazygit	Git terminal UI

AI Tools

Tool	Commands	Description
Ollama	ollama	Run LLMs locally
mcpcall	mcpcall	MCP client for CI/smoke tests

Run vx list to see all 142 supported tools, or vx search <query> to find a specific tool.

---

Why vx?

Feature	vx	nvm/pyenv/etc.
Zero Learning Curve	Same commands you know	New commands to learn
Multi-Language	One tool for all	One tool per language
Auto-Install	On first use	Manual installation
Project Config	vx.toml	Varies by tool
Team Sync	vx setup	Manual coordination
MCP Ready	Just add vx	Complex setup
Cross-Platform	Windows/macOS/Linux	Varies
AI Agent DX	Structured output, schema introspection	No agent support

---

Advanced Configuration

Global Configuration

~/.config/vx/config.toml:

[defaults]
auto_install = true
check_updates = true
update_interval = "24h"

[tools.node]
version = "20"

[tools.uv]
version = "latest"

Shell Integration

# Add to your shell profile for auto-completion
eval "$(vx shell init bash)"   # Bash
eval "$(vx shell init zsh)"    # Zsh
vx shell init fish | source    # Fish

Self-Update with GitHub Token

# Avoid rate limits in shared environments
vx self-update --token ghp_your_token_here

# Or set environment variable
export GITHUB_TOKEN=ghp_your_token_here
vx self-update

---

Installation Options

Package Managers

# Windows
winget install loonghao.vx
choco install vx
scoop install vx

# macOS
brew tap loonghao/vx && brew install vx

# Arch Linux
yay -S vx-bin

# Cargo
cargo install --git https://github.com/loonghao/vx

GitHub Actions

Use vx in your CI/CD workflows:

- uses: loonghao/vx@main
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}

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

Note: Use @main for latest, or pin to a specific release tag (e.g., @vx-v0.9.6). Check releases for the latest version.

See GitHub Action Guide for full documentation.

---

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

1. Report Issues: Open an issue
2. Feature Requests: Start a discussion
3. Code Contributions: Submit pull requests

---

License

MIT License - see LICENSE for details.

Support

• Documentation: GitHub Wiki
• Discussions: GitHub Discussions
• Issues: Bug Reports
• Contact: hal.long@outlook.com