🚀 vx - Universal Development Tool Manager

---

🎯 What is vx?

vx is a powerful, fast, and extensible development tool manager that provides a unified interface for managing, installing, and executing development tools across different languages and ecosystems. Think of it as a combination of nvm, rustup, pyenv, and package managers, all in one lightning-fast tool.

💡 Design Philosophy

The Problem We Solve

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.

Our 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

🌟 Why vx?

• 🔄 Universal Interface: Execute any supported tool through a single, consistent interface
• 📚 Zero Learning Curve: Use the exact same commands you already know (npx, uvx, go, etc.)
• ⚡ Lightning Fast: Built in Rust with async-first architecture for maximum performance
• 🚀 Auto-Installation: Automatically download and install missing tools with beautiful progress bars
• 🔒 Environment Isolation: All tools run in vx-managed environments (no system PATH conflicts)
• 📦 Format Agnostic: Supports ZIP, TAR.GZ, TAR.XZ, TAR.BZ2, and raw binaries
• 🎨 Beautiful UX: Rich progress bars, colorful output, and intuitive commands
• 🤖 MCP Ready: Perfect for MCP servers - just prefix commands with vx

🚀 Latest Improvements (v0.3.0)

• 🔄 Self-Update System: Built-in self-update with GitHub token support to avoid rate limits
• 📁 Unified Path Management: New vx-paths system for standardized tool installation paths
• 📊 Enhanced Tool Discovery: Improved list and which commands with detailed status information
• 🏗️ Modular Architecture: Complete rewrite with vx-installer engine for better maintainability
• 📊 Advanced Progress Tracking: Beautiful progress bars with ETA and transfer rates
• 🔧 Enhanced Installation System: Support for multiple archive formats and installation methods
• 🔌 Plugin System: Extensible architecture with built-in and external plugin support
• 🛡️ Security First: Built-in checksum verification and secure downloads
• 🌍 Cross-Platform: Seamless operation on Windows, macOS, and Linux

✨ Features

🎯 Core Features

• 🔄 Universal Interface: Execute any supported tool through a single, consistent interface
• 📦 Multi-Version Management: Install, manage, and switch between multiple versions of tools
• ⚡ Zero Configuration: Works out of the box with intelligent defaults
• 🚀 Auto-Installation: Automatically download and install missing tools with beautiful progress tracking
• 🎯 Project-Specific: Support for project-level tool configurations
• 🔌 Plugin Architecture: Modular design with extensible plugin system
• 🔄 Self-Update System: Built-in updates with GitHub token support to avoid API rate limits
• 📁 Unified Path Management: Standardized tool installation paths across all platforms

🎨 Enhanced CLI Experience

• 📊 Beautiful Progress Bars: Rich progress bars with ETA, transfer rates, and visual feedback
• 🌈 Colorful Output: Better visual distinction with colored messages and emojis
• ⏳ Smooth Animations: Elegant loading indicators and spinner animations
• 🤝 Interactive Experience: User-friendly prompts and confirmation dialogs
• 💡 Smart Error Messages: Helpful suggestions and clear error reporting with recovery hints
• 🔧 Environment Control: --use-system-path flag for flexible tool execution

🛠️ Advanced Installation Engine

• 📦 Universal Format Support: ZIP, TAR.GZ, TAR.XZ, TAR.BZ2, and raw binaries
• 🔒 Security First: Built-in checksum verification and secure HTTPS downloads
• ⚡ Async Performance: Lightning-fast concurrent downloads and installations
• 🎨 Customizable Progress: Multiple progress styles (default, simple, minimal, custom)
• 🔧 Flexible Methods: Support for archives, binaries, scripts, and package managers
• 🌍 Cross-Platform: Seamless operation across Windows, macOS, and Linux

🏗️ Modern Architecture

• 📊 Package Management: Chocolatey-like layered package management system
• 🔍 Smart Discovery: Automatic tool detection and intelligent version resolution
• ⚙️ Configuration Management: Global and project-level configuration with TOML support
• 📈 Dependency Tracking: Advanced dependency management and conflict resolution
• 🧹 Maintenance Tools: Automated cleanup of orphaned packages and cache management
• 📋 Rich CLI: Comprehensive command-line interface with detailed help and examples
• 📁 Unified Path Management: Standardized tool paths (~/.vx/tools/<tool>/<version>/) across all platforms

🚀 Quick Start

Installation

🚀 Quick Install (Recommended)

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"

🧠 Smart Install (Multi-Channel with Auto-Fallback)

For the most reliable installation experience with automatic fallback to multiple distribution channels:

Linux/macOS:

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

This smart installer automatically:

• 🌍 Detects your geographic region for optimal CDN selection
• ⚡ Tests channel speeds and selects the fastest available
• 🔄 Falls back to alternative channels if primary fails
• 📊 Shows detailed progress with beautiful progress bars

🔧 Advanced Installation Options

Install specific version:

# Linux/macOS
VX_VERSION="0.1.0" curl -fsSL https://raw.githubusercontent.com/loonghao/vx/main/install.sh | bash

# Windows
$env:VX_VERSION="0.1.0"; powershell -c "irm https://raw.githubusercontent.com/loonghao/vx/main/install.ps1 | iex"

Install with GitHub token (avoids rate limits):

# Linux/macOS
GITHUB_TOKEN="your_token_here" curl -fsSL https://raw.githubusercontent.com/loonghao/vx/main/install.sh | bash

# Windows
$env:GITHUB_TOKEN="your_token_here"; powershell -c "irm https://raw.githubusercontent.com/loonghao/vx/main/install.ps1 | iex"

Install to custom directory:

# Linux/macOS
VX_INSTALL_DIR="$HOME/bin" curl -fsSL https://raw.githubusercontent.com/loonghao/vx/main/install.sh | bash

# Windows
$env:VX_INSTALL_DIR="C:\tools\vx"; powershell -c "irm https://raw.githubusercontent.com/loonghao/vx/main/install.ps1 | iex"

Force specific distribution channel:

# Use jsDelivr CDN (good for China/Asia)
VX_FORCE_CHANNEL="jsdelivr" curl -fsSL https://raw.githubusercontent.com/loonghao/vx/main/install-smart.sh | bash

# Use Fastly CDN (good for Europe)
VX_FORCE_CHANNEL="fastly" curl -fsSL https://raw.githubusercontent.com/loonghao/vx/main/install-smart.sh | bash

# Use GitHub directly (good for Americas)
VX_FORCE_CHANNEL="github" curl -fsSL https://raw.githubusercontent.com/loonghao/vx/main/install-smart.sh | bash

🌐 Multi-Channel Distribution

vx uses a sophisticated multi-channel distribution system to ensure reliable downloads worldwide:

Channel	Description	Best For	Rate Limits
GitHub Releases	Primary distribution	Americas, authenticated users	60/hour (unauth), 5000/hour (auth)
jsDelivr CDN	Global CDN with China support	Asia-Pacific, China	Unlimited
Fastly CDN	High-performance global CDN	Europe, global	Unlimited

Automatic Fallback: If one channel fails, the installer automatically tries the next available channel.

Package Managers

Chocolatey (Windows):

choco install vx

Scoop (Windows):

scoop bucket add loonghao https://github.com/loonghao/scoop-vx.git
scoop install vx

WinGet (Windows):

winget install loonghao.vx

Homebrew (macOS):

brew tap loonghao/vx
brew install vx

Arch Linux (AUR):

# Using yay
yay -S vx-bin

# Using paru
paru -S vx-bin

Cargo (from source):

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

Manual Installation

Download the latest release from GitHub Releases and extract to your PATH.

Build from Source

git clone https://github.com/loonghao/vx
cd vx

# Build and install using the installer (recommended)
# Linux/macOS
BUILD_FROM_SOURCE=true ./install.sh

# Windows
.\install.ps1 -BuildFromSource

# Or build manually
cargo build --release
cp target/release/vx ~/.local/bin/  # Linux/macOS
# copy target\release\vx.exe %USERPROFILE%\.local\bin\  # Windows

⚡ Quick Examples: Same Commands, Better Experience

# 🎯 Use the EXACT same commands you already know - just add 'vx'!

# Python development (no Python setup required)
vx uv pip install requests           # Auto-installs UV if needed
vx uvx ruff check .                  # Auto-installs ruff via UV
vx uvx black --check .               # Auto-installs black via UV

# Node.js development (no Node.js setup required)
vx npm install react                 # Auto-installs Node.js if needed
vx npx create-react-app my-app       # Auto-installs create-react-app
vx npx -y cowsay "Hello from vx!"    # One-time tool execution

# Go development (no Go setup required)
vx go build                          # Auto-installs Go if needed
vx go run main.go                    # Same commands you know

# Rust development (no Rust setup required)
vx cargo run                         # Auto-installs Rust if needed
vx cargo build --release             # Same Cargo commands

# 🤖 Perfect for MCP servers - just prefix with 'vx':
# Instead of: npx @browsermcp/mcp@latest
# Use:        vx npx @browsermcp/mcp@latest
# Instead of: uvx some-python-tool
# Use:        vx uvx some-python-tool

# 🔧 Advanced features when you need them
vx --use-system-path python --version  # Use system tools when needed
vx list --status                      # Show all tools with installation status
vx which node --all                   # Show all installed versions of a tool
vx stats                              # Package statistics and usage

# 🔄 Self-update with GitHub token support (solves rate limit issues)
vx self-update --check                # Check for updates
vx self-update --token ghp_xxxx       # Update with GitHub token (recommended for teams)
vx self-update --prerelease           # Include pre-release versions

# 🎯 Version management with beautiful progress bars
vx install uv@0.7.12                 # Install specific versions
vx install node@20.0.0               # Rich progress tracking
vx switch node@18.19.0               # Instant version switching

# ⚙️ Project configuration
vx init                               # Initialize project configuration
vx config                             # Manage global settings

📖 Supported Tools

🔧 Built-in Plugins

Tool	Commands	Category	Auto-Install	Progress Bars	Description
UV	vx uv pip, vx uv venv, vx uv run, vx uv add	Python	✅	✅	Extremely fast Python package installer
UVX	vx uvx <package>, vx uvx ruff, vx uvx black	Python	✅	✅	Python application runner (via UV)
Node.js	vx node, vx npm, vx npx	JavaScript	✅	✅	JavaScript runtime and package manager
NPX	vx npx <package>, vx npx create-react-app	JavaScript	✅	✅	Node.js package runner
Go	vx go build, vx go run, vx go test	Go	✅	✅	Go programming language toolchain
Rust	vx cargo build, vx cargo run, vx cargo test	Rust	✅	✅	Rust programming language and Cargo

🎯 Installation Features

• 📊 Beautiful Progress Bars: Real-time download progress with ETA and transfer rates
• 🔒 Secure Downloads: HTTPS-only with automatic checksum verification
• 📦 Multiple Formats: ZIP, TAR.GZ, TAR.XZ, TAR.BZ2, and raw binaries
• ⚡ Concurrent Operations: Parallel downloads for maximum speed
• 🎨 Customizable Styles: Choose from default, simple, minimal, or custom progress styles
• 🔧 Flexible Methods: Archives, binaries, scripts, and package managers

🏗️ Plugin Categories

• Languages: Go, Rust, Node.js, Python (via UV)
• Package Managers: npm, Cargo, UV (pip-compatible)
• Package Runners: npx, uvx (with complete environment isolation)
• Build Tools: Go build, Cargo, and language-specific toolchains
• Runtimes: Node.js with automatic version management

🚀 vx-installer Engine

vx is powered by the vx-installer engine, a state-of-the-art installation system that provides:

✨ Advanced Installation Features

• 📊 Beautiful Progress Tracking: Rich progress bars with ETA, transfer rates, and visual feedback
• 📦 Universal Format Support: ZIP, TAR.GZ, TAR.XZ, TAR.BZ2, and raw binaries
• ⚡ Lightning Performance: Async-first architecture with concurrent downloads
• 🔒 Security First: Built-in checksum verification and secure HTTPS downloads
• 🎨 Customizable Experience: Multiple progress styles and installation methods

🎯 Installation Methods

Method	Description	Use Case	Progress
Archive	Extract from compressed archives	Tools distributed as ZIP/TAR	✅
Binary	Direct binary installation	Single executable tools	✅
Script	Run installation scripts	Custom installation logic	✅
Package Manager	Use system package managers	System-wide installations	✅

📈 Performance Benchmarks

Operation	Archive Size	Time	Memory Usage
Download	50MB	2.3s	8MB
Extract ZIP	100MB	1.8s	12MB
Extract TAR.GZ	100MB	2.1s	10MB
Install Binary	25MB	0.5s	4MB

Benchmarks on Intel i7-10700K, 32GB RAM, SSD storage

🔌 MCP Integration: The Perfect Solution

vx was designed with MCP (Model Context Protocol) in mind. Many MCP servers require uvx and npx, but setting up these tools can be complex and error-prone. vx solves this with zero configuration and zero learning curve.

The MCP Challenge

MCP servers often require multiple tool ecosystems:

# Traditional setup requires managing multiple tools:
npm install -g some-package     # Requires Node.js setup
uvx install some-python-tool    # Requires Python/UV setup
# Plus dealing with PATH conflicts, version mismatches, etc.

The vx Solution: Just Add vx

With vx, you simply prefix your existing commands with vx - no learning curve, no configuration:

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"]
    }
  }
}

🎯 What You Get

• 📚 Zero Learning Curve: Use the exact same npx and uvx commands you already know
• 🚀 Zero Configuration: No need to install Node.js, Python, UV, or manage PATH
• 🔒 Complete Isolation: MCP tools run in isolated environments, no conflicts
• 📊 Beautiful Progress: See exactly what's happening with rich progress bars
• 🛡️ Security First: Automatic checksum verification and secure downloads
• 🌍 Cross-Platform: Identical behavior on Windows, macOS, and Linux
• ⚡ Lightning Fast: Concurrent downloads and installations

🏗️ Project Architecture

vx is built with a modern, modular architecture that emphasizes performance, extensibility, and maintainability. The recent vx-installer integration brings state-of-the-art installation capabilities.

📦 Core Components

vx/
├── vx-cli/              # Command-line interface with rich UX
├── vx-core/             # Core functionality and utilities
├── vx-installer/        # 🆕 Universal installation engine
├── vx-config/           # Configuration management (TOML-based)
├── vx-plugin/           # Plugin system and trait definitions
├── vx-tools/            # Built-in tool plugins
│   ├── vx-tool-node/    # Node.js support with NPX integration
│   ├── vx-tool-go/      # Go toolchain support
│   ├── vx-tool-rust/    # Rust and Cargo support
│   └── vx-tool-uv/      # UV (Python) with UVX support
└── vx-package-managers/ # Package manager plugins
    └── vx-pm-npm/       # NPM package manager integration

🚀 vx-installer Engine

The heart of vx's installation system, providing:

• 📦 Format Handlers: ZIP, TAR.GZ, TAR.XZ, TAR.BZ2, Binary
• 📊 Progress System: Beautiful progress bars with customizable styles
• 🔒 Security Layer: Checksum verification and secure downloads
• ⚡ Async Core: High-performance concurrent operations
• 🔧 Extensible: Plugin-based format and method support

🎯 Design Principles

• 🔌 Plugin Architecture: Extensible design with trait-based plugins
• ⚡ Performance First: Rust-powered with async-first operations
• 🛡️ Safety & Security: Memory safety, error handling, and secure downloads
• 🔧 Modularity: Clean separation of concerns with focused crates
• 📦 Composability: Mix and match components as needed
• 🎨 User Experience: Beautiful CLI with progress tracking and helpful messages

⚙️ Configuration

Global Configuration

~/.config/vx/config.toml:

[defaults]
auto_install = true        # Auto-install missing tools
check_updates = true       # Check for updates
update_interval = "24h"    # Update check frequency

[tools.uv]
version = "0.5.26"
install_method = "official"

[tools.node]
version = "20.11.0"
install_method = "official"

[tools.go]
version = "1.21.6"

Project Configuration

.vx.toml:

[tools]
uv = "0.5.26"
node = "20.11.0"
go = "1.21.6"

[defaults]
auto_install = true

Plugin Configuration

# List all plugins
vx plugin list

# Get plugin info
vx plugin info uv

# Enable/disable plugins
vx plugin enable rust
vx plugin disable go

# Search plugins
vx plugin search python

🎯 Real-World Examples

Python Development with UV

# Create a new Python project
vx uv init my-python-app
cd my-python-app

# Add dependencies
vx uv add fastapi uvicorn
vx uv add --dev pytest black

# Run the application
vx uv run uvicorn main:app --reload

# Run tests
vx uv run pytest

# Use uvx for Python applications (with environment isolation)
vx uvx ruff check .
vx uvx black --check .
vx uvx cowsay -t "Hello from vx uvx!"

# All tools run in vx-managed environments
vx uv --version  # Uses vx-managed uv

Node.js Development

# Install and use Node.js
vx npm install express
vx node server.js

# Use npx for one-time tools (with environment isolation)
vx npx create-react-app my-app
vx npx -y typescript --init
vx npx cowsay "Hello from vx!"

# All tools run in vx-managed environments
vx npm --version  # Uses vx-managed npm
vx node --version # Uses vx-managed Node.js

Go Development

# Initialize Go module
vx go mod init my-go-app

# Build and run
vx go build
vx go run main.go

# Test
vx go test ./...

Rust Development

# Create new Rust project
vx cargo new my-rust-app
cd my-rust-app

# Add dependencies
vx cargo add serde tokio

# Build and run
vx cargo run

Multi-Language Project

# Frontend (Node.js) + Backend (Go) + Scripts (Python)
vx npm install          # Frontend dependencies
vx go mod tidy          # Backend dependencies
vx uv pip install -r requirements.txt  # Script dependencies

# Run different parts
vx npm run dev          # Frontend dev server
vx go run cmd/server/main.go  # Backend server
vx uv run python scripts/deploy.py  # Deployment script

🔄 Self-Update System

vx includes a powerful self-update system that solves GitHub API rate limit issues commonly encountered in shared environments.

🚀 Quick Update

# Check for updates
vx self-update --check

# Update to latest version
vx self-update

# Update with GitHub token (recommended for teams/shared networks)
vx self-update --token ghp_your_github_token_here

# Include pre-release versions
vx self-update --prerelease

# Force update even if already up to date
vx self-update --force

🔐 GitHub Token Support

Problem: GitHub's public API has a rate limit of 60 requests per hour for unauthenticated users. In shared environments (offices, schools, apartments), multiple users may hit this limit.

Solution: Use a GitHub token to increase the rate limit to 5,000 requests per hour:

# Create a GitHub token at: https://github.com/settings/tokens
# No special permissions needed - just basic access

# Use token for updates
vx self-update --token ghp_xxxxxxxxxxxxxxxxxxxx

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

📊 Update Features

• 🔍 Smart Detection: Automatically detects current and latest versions
• 📦 Cross-Platform: Supports Windows, macOS, and Linux binaries
• 🔒 Secure Downloads: HTTPS-only with automatic verification
• 📋 Release Notes: Shows changelog for new versions
• 🔄 Backup & Rollback: Automatically backs up current version
• ⚡ Fast Downloads: Concurrent downloads with progress bars
• 🎯 Format Support: ZIP, TAR.GZ archives and raw binaries

📊 Package Management

Multi-Version Support

# Install multiple versions
vx install go@1.20.0
vx install go@1.21.6

# List installed versions with detailed status
vx list --status
vx stats

# Show tool installation paths
vx which go --all
vx which node --all

# Switch between versions
vx switch go@1.20.0
vx switch go@1.21.6

# Remove specific versions
vx remove go 1.20.0
vx remove go --all

# Cleanup orphaned packages
vx cleanup

Package Statistics

# View package statistics
vx stats
# Output:
# 📊 Package Statistics:
#   📦 Total packages: 3
#   🔢 Total versions: 5
#   💾 Total size: 2.1 GB
#   🕒 Last updated: 2025-01-30 10:30:00 UTC

🔧 Troubleshooting

Installation Issues

GitHub API Rate Limit Exceeded

Problem: Getting "API rate limit exceeded" error during installation.

Solutions:

1. Use GitHub Token (Recommended):

   # Linux/macOS
   GITHUB_TOKEN="your_token_here" curl -fsSL https://raw.githubusercontent.com/loonghao/vx/main/install.sh | bash
   
   # Windows
   $env:GITHUB_TOKEN="your_token_here"; powershell -c "irm https://raw.githubusercontent.com/loonghao/vx/main/install.ps1 | iex"
   

2. Specify Version Explicitly:

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

3. Use Smart Installer with CDN Fallback:

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

4. Use Package Managers:

   # Windows
   winget install loonghao.vx
   scoop install vx
   
   # macOS
   brew install loonghao/vx/vx
   

Download Failures

Problem: Downloads fail or are very slow.

Solutions:

1. Force Specific Channel:

   # Use jsDelivr CDN (good for Asia/China)
   VX_FORCE_CHANNEL="jsdelivr" curl -fsSL https://raw.githubusercontent.com/loonghao/vx/main/install-smart.sh | bash
   
   # Use Fastly CDN (good for Europe)
   VX_FORCE_CHANNEL="fastly" curl -fsSL https://raw.githubusercontent.com/loonghao/vx/main/install-smart.sh | bash
   

2. Enable Debug Mode:

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

3. Build from Source:

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

Network Issues in China

Problem: Slow or failed downloads due to network restrictions.

Solutions:

1. Use jsDelivr CDN:

   VX_FORCE_CHANNEL="jsdelivr" curl -fsSL https://raw.githubusercontent.com/loonghao/vx/main/install-smart.sh | bash
   

2. Use Mirror URLs:

   curl -fsSL https://fastly.jsdelivr.net/gh/loonghao/vx@main/install-smart.sh | bash
   

Runtime Issues

Tool Not Found

Problem: vx: command not found after installation.

Solutions:

1. Add to PATH manually:

   echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
   source ~/.bashrc
   

2. Check installation location:

   which vx
   ls -la ~/.local/bin/vx
   

Permission Denied

Problem: Permission errors when running vx.

Solutions:

1. Fix permissions:

   chmod +x ~/.local/bin/vx
   

2. Check ownership:

   ls -la ~/.local/bin/vx
   chown $USER:$USER ~/.local/bin/vx
   

Getting Help

If you're still experiencing issues:

1. Enable Debug Mode:

   VX_DEBUG=true vx your-command
   

2. Check System Requirements:

   • Linux: glibc 2.17+ or musl
   • macOS: 10.12+
   • Windows: Windows 10+

3. Report Issues:

   • GitHub Issues
   • Include debug output and system information

🛠️ Development

Prerequisites

• Rust 1.70+
• Cargo

Building

git clone https://github.com/loonghao/vx
cd vx
cargo build --release

Testing

cargo test
cargo run -- --help

Plugin Development

See MODULAR_ARCHITECTURE.md for detailed plugin development guide.

🚀 Roadmap

Current Status (v0.3.0)

• ✅ Core plugin architecture with trait-based extensibility
• ✅ 6 built-in tools (UV, UVX, Node.js, NPX, Go, Rust)
• ✅ Environment isolation system with complete PATH management
• ✅ 🆕 Self-update system with GitHub token support for rate limit avoidance
• ✅ 🆕 Unified path management with vx-paths system (~/.vx/tools/<tool>/<version>/)
• ✅ 🆕 Enhanced tool discovery with improved list --status and which --all commands
• ✅ vx-installer engine with universal format support
• ✅ Beautiful progress bars with ETA and transfer rates
• ✅ Security-first downloads with checksum verification
• ✅ Async installation system with concurrent operations
• ✅ Multi-version package management with intelligent switching
• ✅ MCP integration support for seamless proxy usage
• ✅ Package runner support (npx, uvx) with environment isolation
• ✅ Project configuration support with TOML-based configs

Upcoming Features

🔧 New Tool Support (Phase 7)

• just - Modern command runner and build tool (vx just --list, vx just build)
• kubectl - Kubernetes command-line tool (vx kubectl get pods, vx kubectl apply)
• deno - Modern JavaScript/TypeScript runtime (vx deno run, vx deno task)
• podman - Container management (vx podman run, vx podman build)
• zig - Systems programming language (vx zig build, vx zig run)

🚀 Enhanced Features

• Enhanced Package Managers: pnpm, yarn, bun with full vx-installer integration
• System Package Managers: Homebrew, Chocolatey, apt, yum support
• Specialized Tools: Rez for VFX, Spack for HPC environments
• External Plugin Support: .dll, .so, and script-based plugins
• Plugin Marketplace: Community-driven plugin ecosystem
• Advanced Installation Methods: Docker, containers, and virtual environments
• GUI Interface: Desktop application with visual tool management
• CI/CD Integrations: GitHub Actions, GitLab CI, Jenkins plugins
• Team Configuration Sync: Shared configurations and tool versions
• Performance Optimizations: Caching, parallel operations, and smart updates

🤝 Contributing

We welcome contributions! Here's how you can help:

1. Report Issues: Found a bug? Open an issue
2. Feature Requests: Have an idea? Start a discussion
3. Plugin Development: Create plugins for new tools
4. Documentation: Improve docs and examples
5. Code Contributions: Submit pull requests

🚀 Release Process

This project uses Release Please for automated releases:

• Follow Conventional Commits specification
• Automatic versioning: Version bumps based on commit types
• Automatic changelog: Generated from commit history
• Automatic releases: GitHub releases created when Release PR is merged

# New feature (bumps minor version)
git commit -m "feat: add Python plugin support"

# Bug fix (bumps patch version)
git commit -m "fix: resolve installation issue on Windows"

# Breaking change (bumps major version)
git commit -m "feat!: redesign plugin API"

See Release Guide for detailed guidelines.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Inspired by tools like asdf, mise, proto, and chocolatey
• Built with ❤️ using Rust and modern development practices
• Special thanks to the Rust community and all contributors

📞 Support

• 📖 Documentation: Full documentation
• 💬 Discussions: GitHub Discussions
• 🐛 Issues: Bug Reports
• 📧 Contact: hal.long@outlook.com

---

Made with ❤️ for developers, by developers