llms-full.txt

# vx

> vx is a universal development tool manager — prefix any command with `vx` and it auto-installs the tool on first use. No manual setup, no version conflicts. 136 tools, one command prefix.

vx eliminates the complexity of managing multiple language runtimes (Node.js, Python, Go, Rust, etc.) while maintaining zero learning curve. Built with Rust for performance, it supports direct execution, project environments via `vx.toml`, MCP integration, and AI-native development workflows. Providers are defined using Starlark DSL (`provider.star`) — a declarative, zero-compilation extension system.

- **Install (Linux/macOS)**: `curl -fsSL https://raw.githubusercontent.com/loonghao/vx/main/install.sh | bash`
- **Install (Windows)**: `powershell -c "irm https://raw.githubusercontent.com/loonghao/vx/main/install.ps1 | iex"`
- **Platforms**: Windows, macOS, Linux (x86_64, aarch64)
- **Language**: Rust 1.93+, **License**: MIT
- **Repository**: https://github.com/loonghao/vx
- **GitHub Action**: `loonghao/vx@main`
- **AI Agent Entry Point**: [AGENTS.md](https://github.com/loonghao/vx/blob/main/AGENTS.md)
- **Claude Code Instructions**: [CLAUDE.md](https://github.com/loonghao/vx/blob/main/CLAUDE.md)
- **Full doc index**: [llms.txt](https://github.com/loonghao/vx/blob/main/llms.txt)

**vx = prefix any dev tool command with `vx` → it auto-installs the tool and runs it.**

## Key Features

- **Zero Learning Curve**: Same commands you already know — just prefix with `vx`. No new syntax.
- **Auto-Install on First Use**: Runtimes are downloaded and installed automatically when first needed.
- **136 Tools**: Node.js, Python/UV, Go, Rust, Bun, Deno, Java, Zig, MSVC, CMake, and many more.
- **Project Environments**: Define tool requirements in `vx.toml`, then `vx setup` installs everything.
- **Enhanced Script System**: `{{args}}` passthrough lets you pass complex flags directly to scripts.
- **MCP Ready**: Replace `npx`/`uvx` with `vx` in MCP server configs — zero additional setup.
- **Starlark DSL Providers**: Define custom tools via `provider.star` without writing Rust code. 4 templates cover 90% of cases.
- **Package Aliases**: `vx vite` → `vx npm:vite`, `vx meson` → `vx uv:meson`.
- **Companion Tool Injection**: Tools like MSVC auto-inject env vars for all subprocesses.
- **Shell Integration**: Auto-completion for bash, zsh, and fish. GitHub Actions via `loonghao/vx`.

## Technical Stack

- **Core**: Rust 1.93+, async/await with Tokio
- **Provider DSL**: Starlark (Python-like) via `provider.star` — declarative, zero-compilation
- **Architecture**: 5-layer system with strict downward-only dependency rule
- **Starlark Stdlib**: 14 modules (runtime, platform, env, layout, permissions, system_install, etc.)
- **Provider Templates**: `github_rust_provider`, `github_go_provider`, `github_binary_provider`, `system_provider`
- **Installer**: Supports .tar.gz, .tar.xz, .tar.bz2, .zip, binary formats
- **Version Resolution**: Semantic versioning with range support (`^`, `~`, `>=`)
- **Telemetry**: OpenTelemetry + tracing, JSON metrics output

## Quick Start

```bash
# Install (Linux/macOS)
curl -fsSL https://raw.githubusercontent.com/loonghao/vx/main/install.sh | bash
# Install (Windows)
powershell -c "irm https://raw.githubusercontent.com/loonghao/vx/main/install.ps1 | iex"
# Other: winget install loonghao.vx  |  brew tap loonghao/vx && brew install vx

# Direct execution — runtimes auto-install on first use
vx node --version               # Auto-installs Node.js
vx npm install                  # Uses the installed Node.js
vx python --version             # Auto-installs Python via UV
vx uvx ruff check .             # Auto-installs UV and runs ruff
vx go version                   # Auto-installs Go
vx cargo --version              # Auto-installs Rust toolchain

# Project setup
vx setup                        # Install all tools from vx.toml
vx dev                          # Enter development shell with all tools
vx run test                     # Run project scripts

# AI-optimized output
vx list --json                  # JSON for parsing
vx list --format toon           # Token-optimized (saves 40-60% tokens)
vx analyze --json               # Project analysis as JSON
```

## Project Configuration (vx.toml)

```toml
[tools]
node = "20"                     # Major version (resolves to latest 20.x.x)
python = "3.12"                 # Minor version
uv = "latest"                   # Always latest
go = "1.21.6"                   # Exact version
rust = ">=1.70"                 # Version range

[settings]
auto_install = true
parallel_install = true

[env]
NODE_ENV = "development"

[scripts]
dev = "npm run dev"
test = "npm test && cargo test"
lint = "uvx ruff check . && npm run lint"
# Use {{args}} for argument passthrough
test-pkgs = "cargo test {{args}}"
lint-fix = "eslint {{args}}"
```

## CLI Commands

### Tool Execution

| Command | Description |
|---------|-------------|
| `vx <tool> [args...]` | Execute a tool (auto-installs if needed) |
| `vx install <tool>[@version]` | Install a specific tool version |
| `vx uninstall <tool> [version]` | Uninstall tool versions |
| `vx switch <tool>@<version>` | Switch to a different version |
| `vx which <tool>` | Show which version is being used |
| `vx versions <tool>` | Show available versions |
| `vx list` | List all supported tools |
| `vx search <query>` | Search available tools |

### Project Environment

| Command | Description |
|---------|-------------|
| `vx init` | Initialize project configuration (`vx.toml`) |
| `vx setup` | Install all tools defined in `vx.toml` |
| `vx dev` | Enter development shell with project tools |
| `vx sync` | Sync installed tools with `vx.toml` |
| `vx add <tool>` | Add a tool to project configuration |
| `vx run <script>` | Run a script defined in `vx.toml` |
| `vx run --list` | List all available scripts |

### System Management

| Command | Description |
|---------|-------------|
| `vx cache info` | Show disk usage and cache statistics |
| `vx doctor` | Diagnose dev environment issues |
| `vx self-update` | Update vx itself |
| `vx metrics` | Show execution telemetry |
| `vx metrics --json` | JSON output for AI/scripting |
| `vx --debug <cmd>` | Run with debug logging |

### Exit Codes

| Code | Meaning | Code | Meaning |
|------|---------|------|---------|
| 0 | Success | 4 | Version not found |
| 1 | General error | 5 | Network error |
| 2 | Tool not found | 6 | Permission error |
| 3 | Installation failed | 7 | Configuration error |

## MCP Integration

Replace `npx`/`uvx` with `vx` in any MCP server configuration:

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

| Original config | vx-powered config |
|----------------|-------------------|
| `"command": "npx"` | `"command": "vx", "args": ["npx", ...]` |
| `"command": "uvx"` | `"command": "vx", "args": ["uvx", ...]` |
| `"command": "node"` | `"command": "vx", "args": ["node", ...]` |
| `"command": "python"` | `"command": "vx", "args": ["python", ...]` |

## GitHub Actions

```yaml
- uses: loonghao/vx@main
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}
- run: vx node --version
- run: vx npm ci && vx npm test
- run: vx go test ./...
```

## Architecture

```
┌─────────────────────────────────────────────────────────┐
│  vx-cli            (Application layer — CLI entry)      │
├─────────────────────────────────────────────────────────┤
│  vx-resolver       (Orchestration — resolve & execute)  │
│  vx-setup / vx-migration / vx-project-analyzer          │
├─────────────────────────────────────────────────────────┤
│  vx-runtime / vx-starlark / vx-installer                │
│  vx-version-fetcher / vx-config / vx-console            │
├─────────────────────────────────────────────────────────┤
│  vx-core / vx-paths / vx-cache / vx-versions            │
│  vx-manifest / vx-args   (Foundation layer)             │
├─────────────────────────────────────────────────────────┤
│  vx-providers/*  (136 Providers — provider.star DSL)    │
└─────────────────────────────────────────────────────────┘
```

**Dependency rule**: Each layer may only depend on layers **below** it. Never upward.

**Key Concepts**:
- **Runtime**: A single executable (e.g., `node`, `npm`, `go`)
- **Provider**: A group of related runtimes (e.g., NodeProvider provides `node`, `npm`, `npx`)
- **Bundled Runtime**: A Runtime shipped inside another (e.g., npm bundled with node)
- **provider.star**: Starlark DSL file that declaratively describes a Provider — no Rust code needed

**Two-Phase Execution Model**:
1. **Analysis Phase (Starlark)**: `provider.star` runs as pure computation returning descriptor dicts. No I/O.
2. **Execution Phase (Rust)**: Rust runtime interprets descriptors and performs actual downloads and process execution.

**Version Resolution Priority** (highest → lowest):
1. Command-line override: `vx node@22 app.js`
2. Project `vx.toml`: `[tools] node = "22"`
3. Parent directory `vx.toml` (traverses up)
4. User global config: `~/.config/vx/config.toml`
5. Provider default: latest stable version

**Common Mistakes**:
| ❌ Don't | ✅ Do instead |
|----------|---------------|
| `npm install` | `vx npm install` |
| `pip install flask` | `vx uv pip install flask` |
| Tell user to "install Node.js first" | Run `vx node --version` (auto-installs) |
| Suggest `nvm use 22` | `vx switch node@22` or set in `vx.toml` |
| `println!` for logging | `tracing::info!`, `tracing::debug!` |
| Inline `#[cfg(test)] mod tests {}` | Tests in `crates/<name>/tests/` |

## Provider System (provider.star)

Minimal complete provider example:

```starlark
# crates/vx-providers/ripgrep/provider.star
load("@vx//stdlib:provider.star", "runtime_def", "github_permissions")
load("@vx//stdlib:provider_templates.star", "github_rust_provider")

name        = "ripgrep"
description = "ripgrep — recursively searches directories"
ecosystem   = "custom"

runtimes    = [runtime_def("rg", aliases=["ripgrep"])]
permissions = github_permissions()

_p = github_rust_provider("BurntSushi", "ripgrep",
    asset      = "rg-{version}-{triple}.{ext}",
    executable = "rg",
)

fetch_versions   = _p["fetch_versions"]
download_url     = _p["download_url"]
install_layout   = _p["install_layout"]
store_root       = _p["store_root"]
get_execute_path = _p["get_execute_path"]
environment      = _p["environment"]
```

**Starlark Standard Library** (14 modules):

| Module | Key exports |
|--------|-------------|
| `provider.star` | Unified facade — re-exports all helpers |
| `runtime.star` | `runtime_def`, `bundled_runtime_def`, `dep_def` |
| `platform.star` | `platform_map`, `platform_select`, `rust_triple`, `go_os_arch`, `archive_ext`, `exe_suffix` |
| `env.star` | `env_set`, `env_prepend`, `env_append`, `env_unset` |
| `layout.star` | `archive_layout`, `binary_layout`, `bin_subdir_layout`, hooks, path fns |
| `permissions.star` | `github_permissions`, `system_permissions` |
| `system_install.star` | `winget_install`, `brew_install`, `apt_install`, `cross_platform_install` |
| `script_install.star` | `curl_bash_install`, `irm_iex_install`, `platform_script_install` |
| `provider_templates.star` | `github_rust_provider`, `github_go_provider`, `github_binary_provider`, `system_provider` |
| `github.star` | GitHub API helpers, `make_fetch_versions`, `make_download_url` |
| `http.star` | `fetch_versions_from_api`, `fetch_versions_with_tag_prefix` |
| `install.star` | `archive_install`, `binary_install`, `msi_install` |
| `semver.star` | `semver_gt`, `semver_sort`, `semver_parse`, `semver_compare` |
| `test.star` | `cmd`, `check_path`, `check_env` testing DSL |

**Provider template selection**:
- GitHub releases + Rust triple naming → `github_rust_provider` (most common)
- GitHub releases + goreleaser style → `github_go_provider`
- Single binary (no archive) → `github_binary_provider`
- System package manager only → `system_provider`

## Configuration

**Global config** (`~/.config/vx/config.toml`):

```toml
[defaults]
auto_install = true
check_updates = true

[tools.node]
version = "20"
```

**Environment Variables**:

| Variable | Description |
|----------|-------------|
| `VX_HOME` | Override default `~/.vx` directory |
| `VX_NO_AUTO_INSTALL` | Disable automatic tool installation |
| `VX_VERBOSE` | Enable verbose output |
| `VX_NO_COLOR` | Disable colored output |
| `GITHUB_TOKEN` | GitHub token for API rate limit avoidance |
| `VX_PROVIDERS_PATH` | Additional provider search paths |

## Pre-commit Hooks

vx uses [prek](https://prek.j178.dev/) for pre-commit hooks:

```bash
vx prek install    # Install hooks once after cloning
vx prek run --all-files  # Run all hooks manually

# After adding/updating dependencies (fixes cargo-hakari failures):
vx cargo hakari generate && vx cargo hakari manage-deps
```

Hooks: `typos`, `cargo-fmt`, `cargo-clippy`, `cargo-check-tests`, `prettier`, `cargo-hakari`, `justfile-no-duplicate-recipes`, `check-merge-conflict`.

## Real-World Examples

**Team Onboarding**:
```bash
git clone https://github.com/your-org/your-project
cd your-project && vx setup && vx dev
```

**Python Development**:
```bash
vx uv init my-app && cd my-app
vx uv add fastapi uvicorn
vx uv run uvicorn main:app --reload
vx uvx ruff check .
```

**Node.js + Go Monorepo** (`vx.toml`):
```toml
[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"
```

## Key RFCs (Design Documents)

- [RFC 0001: vx.toml v2](https://github.com/loonghao/vx/blob/main/docs/rfcs/0001-vx-toml-v2-enhancement.md): Project configuration design
- [RFC 0003: Dynamic Scripts](https://github.com/loonghao/vx/blob/main/docs/rfcs/0003-dynamic-scripts.md): `{{args}}` passthrough design
- [RFC 0027: Implicit Package Execution](https://github.com/loonghao/vx/blob/main/docs/rfcs/0027-implicit-package-execution.md): `vx vite` → `vx npx vite`
- [RFC 0035: AI Integration](https://github.com/loonghao/vx/blob/main/docs/rfcs/0035-ai-integration-optimization.md): AI-native workflow optimization
- [RFC 0036: Starlark Provider Support](https://github.com/loonghao/vx/blob/main/docs/rfcs/0036-starlark-provider-support.md): Starlark DSL design
- [RFC 0038: provider.star replaces TOML](https://github.com/loonghao/vx/blob/main/docs/rfcs/0038-provider-star-replaces-toml.md): Single source of truth

## Documentation Index

See [llms.txt](https://github.com/loonghao/vx/blob/main/llms.txt) for the full documentation index. Key references:

- [provider.star Reference](https://github.com/loonghao/vx/blob/main/docs/guide/provider-star-reference.md): Complete Starlark DSL reference
- [Creating a Provider](https://github.com/loonghao/vx/blob/main/docs/guide/creating-provider.md): Step-by-step guide
- [Architecture Overview](https://github.com/loonghao/vx/blob/main/docs/architecture/OVERVIEW.md): Internal design, crate dependency graph
- [vx.toml Reference](https://github.com/loonghao/vx/blob/main/docs/config/vx-toml.md): Full project config reference
- [Troubleshooting](https://github.com/loonghao/vx/blob/main/docs/appendix/troubleshooting.md): Common issues and solutions
- [GitHub Actions Guide](https://github.com/loonghao/vx/blob/main/docs/guides/github-action.md): CI/CD integration
- [AGENTS.md](https://github.com/loonghao/vx/blob/main/AGENTS.md): Primary AI agent entry point with rules and decision trees