Configuration

Learn how to configure Coldbrew for your projects and system.

Project Configuration: coldbrew.toml

Create a coldbrew.toml file in your project root to define dependencies. This file is similar to a package.json for system packages.

# coldbrew.toml - Project package configuration

# Required packages for this project
[packages]
node = "20"           # Major version only
python = "3.12"       # Minor version
go = "1.21.5"         # Exact version

# Development-only packages
[dev_packages]
rust = "1.75"
jq = "1.7"

Creating a Configuration File

Run crew init to create a new configuration file:

crew init

Version Specifiers

Coldbrew supports flexible version specifications:

  • "20" – Latest version matching major version 20
  • "20.10" – Latest version matching 20.10.x
  • "20.10.0" – Exact version
  • "latest" – Always use the latest version

Lock Files: coldbrew.lock

Lock files pin exact versions and checksums for reproducible builds. Generate one with:

crew lock

The lock file contains:

# coldbrew.lock - Auto-generated, do not edit manually

[[package]]
name = "node"
version = "20.10.0"
sha256 = "abc123..."
bottle_url = "https://ghcr.io/..."

[[package]]
name = "python"
version = "3.12.1"
sha256 = "def456..."
bottle_url = "https://ghcr.io/..."

Best Practice: Commit both coldbrew.toml and coldbrew.lock to version control. This ensures everyone on your team uses the exact same versions.

Global Configuration: config.toml

Global settings are stored in ~/.coldbrew/config.toml:

# ~/.coldbrew/config.toml - Global Coldbrew settings

# Number of parallel downloads (default: 4)
parallel_downloads = 8

# Cache settings
[cache]
# Keep downloaded bottles for this many days
retention_days = 30

# Bottle selection preferences
[bottles]
# Prefer bottles with specific OS version
prefer_os_version = "14"  # macOS Sonoma

Environment Variables

Coldbrew respects these environment variables:

VariableDescription
COLDBREW_HOMEInstallation directory (default: ~/.coldbrew)
COLDBREW_CACHECache directory (default: ~/.coldbrew/cache)
COLDBREW_NO_COLORDisable colored output
GITHUB_TOKENGitHub token for private taps and higher rate limits

Directory Structure

Coldbrew organizes files in a predictable structure:

~/.coldbrew/
├── bin/           # Shims and active version symlinks
├── cellar/        # Installed packages by version
│   ├── node/
│   │   ├── 20.10.0/
│   │   └── 18.19.0/
│   └── python/
│       └── 3.12.1/
├── cache/         # Downloaded bottles and index
├── taps/          # Third-party repositories
└── config.toml    # Global configuration