vx 0.2.3

Universal Development Tool Manager
Documentation

vx - Universal Development Tool Manager

δΈ­ζ–‡ζ–‡ζ‘£

License: MIT Rust Test Release codecov Security audit GitHub release GitHub downloads Crates.io Documentation

πŸš€ The ultimate development tool manager - One tool to rule them all

⚠️ Early Development Stage

This project is currently in early experimental development stage. Features and APIs may change significantly between versions. Use with caution in production environments.

  • πŸ”¬ Experimental: Core features are being actively developed and tested
  • 🚧 Breaking Changes: APIs and configurations may change without notice
  • πŸ“ Feedback Welcome: Please report issues and share your experience
  • 🎯 MVP Focus: Currently supports UV, Node.js, Go, and Rust tools
  • πŸš€ Release Automation: Now with automated release management via release-plz

βœ… Recently Implemented

  • NPX Support: Full support for Node.js package runner with environment isolation
  • UVX Support: Complete Python application runner integration via UV
  • Environment Isolation: All tools run in vx-managed environments (no system PATH dependency)
  • Auto-Installation: Automatic tool download and installation on first use
  • MCP Integration: Ready for use as proxy in MCP server configurations
  • Improved CI/CD: Enhanced release automation with release-please integration

Current Limitations

  • Package Manager Integration: Additional package managers (pnpm, yarn, bun) in development
  • Configuration: Advanced project-specific configurations being enhanced
  • Plugin System: External plugin support planned for future releases

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.

✨ 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
  • 🎯 Project-Specific: Support for project-level tool configurations
  • πŸ”Œ Plugin Architecture: Modular design with extensible plugin system

🎨 Enhanced CLI Experience

  • πŸ“Š Progress Bars: Visual feedback for downloads and installations
  • 🌈 Colorful Output: Better visual distinction with colored messages
  • ⏳ Spinner Animations: Smooth loading indicators for operations
  • 🀝 Interactive Confirmations: User-friendly prompts and dialogs
  • πŸ’‘ Smart Error Messages: Helpful suggestions and clear error reporting
  • πŸ”§ Environment Isolation: --use-system-path flag for better control

πŸ› οΈ Advanced Features

  • πŸ“Š Package Management: Chocolatey-like layered package management
  • πŸ” Smart Discovery: Automatic tool detection and version resolution
  • βš™οΈ Configuration Management: Global and project-level configuration support
  • πŸ“ˆ Dependency Tracking: Track and manage tool dependencies
  • 🧹 Cleanup Tools: Orphaned package cleanup and maintenance
  • πŸ“‹ Rich CLI: Comprehensive command-line interface with helpful output

πŸš€ Quick Start

Installation

Quick Install (Recommended)

Linux/macOS:

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

Windows (PowerShell):

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

Package Managers

Homebrew (macOS/Linux):

brew install loonghao/tap/vx

Scoop (Windows):

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

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


# Standard release build

cargo build --release


# PGO-optimized build (recommended for best performance)

make build-pgo


# Windows: Run the build installer

.\install.ps1

Basic Usage

# Execute tools through vx - they'll be auto-installed if missing!

vx uv pip install requests

vx npm install react

vx node app.js

vx go build

vx cargo run


# Package runners with environment isolation

vx npx create-react-app my-app

vx npx -y cowsay "Hello from vx!"

vx uvx cowsay -t "Hello from vx uvx!"

vx uvx ruff check .


# Use system PATH instead of vx-managed tools

vx --use-system-path python --version

vx --use-system-path node --version


# List supported tools and plugins

vx list

vx plugin list


# Install specific versions

vx install uv@0.7.12

vx install node@20.0.0

vx install go@1.21.6


# Switch between versions

vx switch uv@0.7.12

vx switch node@18.19.0


# Project configuration

vx init

vx config

πŸ“– Supported Tools

πŸ”§ Built-in Plugins

Tool Commands Category Auto-Install 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

🎯 Plugin Categories

  • Languages: Go, Rust, Node.js, Python (via UV)
  • Package Managers: npm, Cargo, UV (pip-compatible)
  • Package Runners: npx, uvx (with environment isolation)
  • Build Tools: Go build, Cargo, etc.
  • Runtimes: Node.js

πŸ”Œ MCP Integration

vx is designed to work seamlessly as a proxy for package runners in MCP (Model Context Protocol) server configurations, providing environment isolation and automatic tool management.

Before (Direct Tool Usage)

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

After (vx Proxy)

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

Benefits

  • Environment Isolation: No conflicts with system-installed tools
  • Automatic Installation: Tools are downloaded and managed automatically
  • Version Control: Consistent tool versions across environments
  • Cross-Platform: Works identically on Windows, macOS, and Linux

βš™οΈ 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

πŸ“Š Package Management

Multi-Version Support

# Install multiple versions

vx install go@1.20.0

vx install go@1.21.6


# List installed versions

vx stats


# 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

πŸ› οΈ 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.1.1)

  • βœ… Core plugin architecture
  • βœ… 6 built-in tools (UV, UVX, Node.js, NPX, Go, Rust)
  • βœ… Environment isolation system
  • βœ… Auto-installation system
  • βœ… Multi-version package management
  • βœ… MCP integration support
  • βœ… Package runner support (npx, uvx)
  • βœ… Project configuration support

Upcoming Features

  • More package managers (pnpm, yarn, bun)
  • System package managers (Homebrew, Chocolatey)
  • Specialized tools (Rez for VFX, Spack for HPC)
  • External plugin support (.dll, .so, scripts)
  • Plugin marketplace
  • GUI interface
  • CI/CD integrations
  • Team configuration sync

🀝 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

Made with ❀️ for developers, by developers