Version Management

Installing Multiple Versions

Unlike Homebrew, Coldbrew lets you install multiple versions of the same package:

# Install multiple Node.js versions
crew install node@18 node@20 node@22

# List what's installed
crew list node
# node@18.19.0
# node@20.10.0
# node@22.0.0

Setting Default Versions

Set which version to use globally when no project configuration is present:

# Set Node 20 as the global default
crew default node@20

# Check the current default
crew default node
# node@20.10.0

How Shims Work

Coldbrew uses shims to automatically select the right version based on your project. When you run node, Coldbrew's shim:

1. Checks for coldbrew.toml in the current directory and parents
2. Looks for version files (.nvmrc, .node-version, etc.)
3. Falls back to your global default
4. Uses the latest installed version as last resort

Version File Detection

Coldbrew automatically detects version files from popular tools:

This means your existing projects work automatically – no migration needed.

Version Resolution Order

When determining which version to use, Coldbrew checks in this order:

1. coldbrew.toml – Project-specific Coldbrew configuration
2. Version files – .nvmrc, .python-version, etc.
3. Global default – Set with crew default
4. Latest installed – Highest version number available

Pinning Versions

Prevent a package from being upgraded:

# Pin Node 20 to prevent upgrades
crew pin node@20

# See pinned packages
crew list --pinned

# Unpin when ready to upgrade
crew unpin node

Removing Old Versions

Clean up versions you no longer need:

# Remove a specific version
crew uninstall node@18

# Interactive cleanup of old versions
crew gc

# See what would be removed
crew gc --dry-run

Checking Which Version is Active

See which version will be used in the current directory:

# Check active version
crew which node
# /Users/you/.coldbrew/cellar/node/20.10.0/bin/node
# (from coldbrew.toml)

# See resolution details
crew which node --verbose