Proto

proto - Pluggable Multi-Language Version Manager

proto is a next-generation version manager for multiple programming languages. It provides a unified interface for managing Node.js, npm, pnpm, yarn, Bun, Deno, Rust, Go, Python, and 800+ tools via plugins.

When to Use proto

• Managing language/tool versions across projects
• Pinning versions in .prototools for team consistency
• Installing and running tools without global pollution
• Replacing nvm, pyenv, rustup, gvm with a single tool

Installation

# Linux, macOS, WSL
bash <(curl -fsSL https://moonrepo.dev/install/proto.sh)

# Specific version, non-interactive
bash <(curl -fsSL https://moonrepo.dev/install/proto.sh) 1.2.3 --yes

Shell Setup

# Add to shell profile
eval "$(proto activate bash)"   # Bash
eval "$(proto activate zsh)"    # Zsh

Quick Reference

Core Commands

proto install <tool>           # Install tool
proto install node 20.10.0     # Install specific version
proto install node --build     # Build from source (v0.45+)
proto run <tool>               # Run with detected version
proto exec node pnpm -- cmd    # Bootstrap multi-tool env (v0.53+)
proto pin <tool> <version>     # Pin version locally
proto pin <tool> --global      # Pin globally
proto versions <tool>          # List available versions
proto outdated                 # Check for updates
proto clean                    # Remove unused tools
proto upgrade                  # Upgrade proto itself
proto diagnose                 # Identify installation issues
proto debug config             # List all .prototools files
proto debug env                # Show environment info

Configuration: .prototools

# .prototools
node = "20.10.0"
npm = "10.2.0"
pnpm = "8.12.0"
yarn = "4.0.0"
bun = "1.0.0"
deno = "1.40.0"
rust = "1.75.0"
go = "1.21.0"
python = "3.12.0"

[plugins]
my-tool = "https://example.com/plugin.wasm"

[settings]
auto-install = true
auto-clean = true
detect-strategy = "prefer-prototools"

[env]
NODE_ENV = "development"

Version Specifiers

Supported Tools (Built-in)

JavaScript/TypeScript

proto install node     # Node.js runtime
proto install npm      # npm package manager
proto install pnpm     # pnpm package manager
proto install yarn     # Yarn package manager
proto install bun      # Bun runtime
proto install deno     # Deno runtime

Systems Languages

proto install rust     # Rust (includes cargo)
proto install go       # Go

Other

proto install python   # Python (includes pip)

Version Detection Order

1. CLI argument: proto run node 18.0.0 2. Environment variable: PROTO_NODE_VERSION=18.0.0 3. Local .prototools (current + parent dirs) 4. Ecosystem files: .nvmrc, .node-version, package.json engines 5. Global .prototools: ~/.proto/.prototools

Common Workflows

Pin Versions for Team

# Pin to local .prototools
proto pin node 20.10.0
proto pin pnpm 8.12.0

# Pin globally (user default)
proto pin node 20 --global

Install All Tools

# Install everything from .prototools
proto install

Check for Updates

proto outdated                    # Check for updates
proto outdated --update --latest  # Update .prototools

Run with Specific Version

proto run node 18 -- script.js    # Override version
PROTO_NODE_VERSION=18 proto run node  # Via env var

Proto Exec (v0.53+)

Bootstrap an environment with multiple tools:

# Run command with multiple tools
proto exec node@24 pnpm@10 ruby@3.4 -- pnpm run app:start

# Load tools from config
proto exec --tools-from-config -- npm test

# Interactive shell with activated tools
proto exec node pnpm -- bash

Build From Source (v0.45+)

Compile tools from source (useful when pre-built binaries unavailable):

proto install ruby --build
proto install node --build
proto install python --build

Supported: Deno, Go, Moon, Node, Python, Ruby.

# .prototools
[settings.build]
install-system-packages = true
write-log-file = true

Plugins

Add Third-Party Plugin

proto plugin add atlas "https://raw.githubusercontent.com/.../plugin.toml"
proto install atlas

List Plugins

proto plugin list           # Show all plugins
proto plugin list --versions  # With version info

Plugin Sources

[plugins]
# Remote TOML plugin
atlas = "https://example.com/atlas/plugin.toml"

# Remote WASM plugin
custom = "https://example.com/plugin.wasm"

# GitHub releases (recommended for distribution)
my-tool = "github://org/repo"

# Local development (WASM)
local = "file://./target/wasm32-wasip1/release/plugin.wasm"

WASM Plugin Development

Build plugins with proto_pdk crate targeting wasm32-wasip1:

# Build plugin
cargo build --target wasm32-wasip1 --release

# Test locally
proto install my-tool --log trace

Test configuration for local development:

# .prototools
[settings]
unstable-lockfile = true  # Create .protolock for consistency

[plugins.tools]
my-tool = "file://./target/wasm32-wasip1/release/my_tool.wasm"

Required WASM functions:

• register_tool - Metadata (name, type)
• download_prebuilt - Configure download/install
• locate_executables - Define executable paths
• load_versions - Fetch available versions

Optional: native_install, detect_version_files, parse_version_file

Settings

[settings]
# Auto-install missing tools
auto-install = true

# Auto-clean unused tools
auto-clean = true

# Version detection strategy
# first-available, prefer-prototools, only-prototools
detect-strategy = "prefer-prototools"

# Pin "latest" alias to local or global config
pin-latest = "local"

# Create .protolock for reproducible installs
unstable-lockfile = true

# Disable telemetry
telemetry = false

[settings.http]
# Configure proxies
proxies = ["https://internal.proxy"]
root-cert = "/path/to/cert.pem"

[settings.offline]
timeout = 500  # ms

Environment Variables

Development/Testing Variables

Integration with moon

proto is the toolchain backend for moon. Configure in .moon/toolchains.yml (v2):

# .moon/toolchains.yml
javascript:
  packageManager: "pnpm"

node:
  version: "20.10.0"

Or pin moon itself via proto:

# .prototools
moon = "1.31.0"

CI/CD Integration

# GitHub Actions
- uses: moonrepo/setup-toolchain@v0
  with:
    auto-install: true

Additional Resources

For detailed configuration, consult:

• `references/config.md` - Complete .prototools reference
• `references/plugins.md` - Plugin development guide
• `references/commands.md` - Full CLI reference

Examples

• `examples/prototools-full.toml` - Complete configuration
• `examples/plugin.toml` - TOML plugin example

Proto CLI Reference

Complete reference for all proto commands.

Installation Commands

proto install

Install tools from .prototools or specific versions.

proto install                    # Install all from .prototools
proto install node               # Install node (latest or pinned)
proto install node 20.10.0       # Install specific version
proto install node --pin         # Install and pin locally
proto install node --pin global  # Install and pin globally
proto install --config-mode all  # Include global config

proto uninstall

Remove installed tool versions.

proto uninstall node 20.10.0
proto uninstall node --all       # Remove all versions

Execution Commands

proto run

Execute a tool with the detected version.

proto run node                   # Run with detected version
proto run node 18                # Run specific version
proto run node -- script.js      # Pass arguments
PROTO_NODE_VERSION=18 proto run node  # Via env var

proto use

Switch to a pinned version in current shell.

proto use node 20
proto use node latest

Version Management

proto pin

Pin a version to .prototools.

proto pin node 20.10.0           # Pin locally
proto pin node 20 --global       # Pin globally
proto pin node 20 --to user      # Pin to ~/.prototools

proto unpin

Remove a pinned version.

proto unpin node
proto unpin node --global

proto versions

List available versions for a tool.

proto versions node              # All versions (installed marked)

proto outdated

Check for version updates.

proto outdated                   # Check all tools
proto outdated --config-mode all # Include global
proto outdated --update          # Update .prototools
proto outdated --update --latest # Update to latest
proto outdated --json            # JSON output

Plugin Commands

proto plugin add

Register a plugin.

proto plugin add <name> <source>
proto plugin add atlas "https://example.com/atlas/plugin.toml"

proto plugin remove

Unregister a plugin.

proto plugin remove atlas

proto plugin list

List registered plugins.

proto plugin list                # All plugins
proto plugin list --versions     # With version info
proto plugin list node npm       # Specific plugins

proto plugin info

Show plugin details.

proto plugin info node

Alias Commands

proto alias

Create a version alias.

proto alias node work 18.0.0     # Create 'work' alias
proto alias node lts 20.10.0     # Override 'lts'

proto unalias

Remove an alias.

proto unalias node work

Maintenance Commands

proto clean

Remove unused tools and cache.

proto clean                      # Clean stale tools (30+ days unused)
proto clean plugins              # Clean plugins only
proto clean --days 7             # Custom threshold

proto upgrade

Upgrade proto itself.

proto upgrade                    # Upgrade to latest
proto upgrade --check            # Check only
proto upgrade 0.50.0             # Specific version

proto setup

Initialize proto in current shell.

proto setup                      # Configure shell
proto setup bash                 # Specific shell
proto setup --no-modify-profile  # Don't modify profile

Debug Commands

proto debug env

Show environment and configuration.

proto debug env

Output includes:

• Store paths (root, bins, shims, plugins, tools, temp)
• Proto version
• OS and architecture
• Config sources
• Virtual paths
• Environment variables

proto debug config

Show resolved configuration.

proto debug config
proto debug config --json

Activate Command

proto activate

Generate shell activation script.

eval "$(proto activate bash)"    # Bash
eval "$(proto activate zsh)"     # Zsh
source (proto activate fish | psub)  # Fish

Common Options

Environment Variables

Proto Configuration Reference

Complete reference for .prototools configuration.

File Location

Proto searches for .prototools in this order:

1. Current directory 2. Parent directories (up to filesystem root) 3. User home: ~/.prototools 4. Proto store: ~/.proto/.prototools

Version Pinning

# Exact versions (recommended for CI)
node = "20.10.0"
npm = "10.2.0"
pnpm = "8.12.0"
yarn = "4.0.0"
bun = "1.0.18"
deno = "1.40.0"
rust = "1.75.0"
go = "1.21.5"
python = "3.12.0"

# Pin proto itself
proto = "0.51.0"

# Partial versions (resolves to latest patch)
node = "20.10"
node = "20"

# Tilde (patch updates only)
node = "~20.10"

# Caret (minor updates)
node = "^20"

# Aliases
rust = "stable"
node = "lts"

Plugin Configuration

[plugins]
# Remote TOML plugin
atlas = "https://raw.githubusercontent.com/example/plugin.toml"

# Remote WASM plugin
custom = "https://example.com/plugin.wasm"

# Local file (development)
dev-tool = "file://./target/wasm32-wasip1/debug/plugin.wasm"

# From registry (when available)
# tool = "source:tool-name"

Settings

[settings]
# Auto-install missing tools on `proto run`
auto-install = true

# Auto-clean unused tools
auto-clean = true

# Disable telemetry
telemetry = false

# Version detection strategy
# first-available - Use first found (default)
# prefer-prototools - Prefer .prototools over ecosystem files
# only-prototools - Only use .prototools
detect-strategy = "prefer-prototools"

HTTP Settings

[settings.http]
# Proxy configuration
proxies = ["https://internal.proxy", "https://corp.net/proxy"]

# Mark proxies as secure (bypass SSL checks)
secure-proxies = ["http://internal.proxy"]

# Custom root certificate
root-cert = "/path/to/root/cert.pem"

Offline Settings

[settings.offline]
# Timeout for connectivity check (milliseconds)
timeout = 500

Environment Variables

[env]
# Set environment variables
DEBUG = "*"
NODE_ENV = "development"

# Variable substitution
API_URL = "${BASE_URL}/api"

# Unset a variable
UNWANTED_VAR = false

Environment-Specific Configuration

Use PROTO_ENV for environment-specific configs:

PROTO_ENV=production proto run node

Lookup order with PROTO_ENV=production:

1. ./.prototools.production 2. ./.prototools 3. ~/.prototools.production 4. ~/.prototools 5. ~/.proto/.prototools

Per-Tool Settings

[tools.node]
# Tool-specific configuration
aliases = { lts = "20.10.0", current = "21.0.0" }

[tools.node.env]
# Environment variables for this tool only
NODE_OPTIONS = "--max-old-space-size=4096"

Environment Variables Reference

Complete Example

# .prototools

# Tool versions
node = "20.10.0"
npm = "10.2.0"
pnpm = "8.12.0"
rust = "1.75.0"
python = "3.12.0"
go = "1.21.5"
proto = "0.51.0"

# Third-party plugins
[plugins]
atlas = "https://raw.githubusercontent.com/crashdump/proto-tools/main/toml-plugins/atlas/plugin.toml"
pkl = "https://raw.githubusercontent.com/milesj/proto-plugins/master/pkl.toml"

# Global settings
[settings]
auto-install = true
auto-clean = true
detect-strategy = "prefer-prototools"
telemetry = false

# Network configuration
[settings.http]
proxies = ["https://corporate.proxy:8080"]

# Environment variables
[env]
NODE_ENV = "development"
RUST_BACKTRACE = "1"