Quick start

Get started with zerobrew and run your first commands

Quick start

This guide will help you get started with zerobrew by walking through the most common commands and workflows.

Your first installation

Let’s install a package using zerobrew. We’ll use jq, a popular command-line JSON processor:

1. Install a package

   Run the install command:

   zb install jq
   

   You’ll see output showing the installation progress:

   ==> Installing jq...
   ==> Resolving dependencies (1 packages)...
       jq 1.7.1
   ==> Downloading and installing formulas...
       jq               ━━━━━━━━━━━━━━━━━━━━━━━━ ✓ installed
   
   ==> Installed 1 packages in 0.68s
   
2. Verify the installation

   Check that jq is now available:

   jq --version
   

   You should see the version number printed.

Installing multiple packages

You can install multiple packages in a single command:

 zb install wget git curl

zerobrew will automatically:

• Resolve all dependencies
• Download packages in parallel
• Install them efficiently using content-addressable storage

Working with Brewfiles

Brewfiles allow you to manage your packages as code. This is useful for reproducible environments and dotfiles.

1. Create a Brewfile

   Create a file named Brewfile in your project directory:

   Brewfile

   # Development tools
   brew "git"
   brew "wget"
   brew "jq"
   
   # Programming languages
   brew "python@3.11"
   brew "node"
   
   # Optional: casks (macOS applications)
   # cask "docker-desktop"
   
2. Install from Brewfile

   Install all packages from the Brewfile:

   zb bundle
   

   Or specify a custom file:

   zb bundle install -f myfile
   
3. Export current packages

   You can also export your currently installed packages to a Brewfile:

   zb bundle dump
   

   To overwrite an existing file:

   zb bundle dump -f Brewfile --force
   

Running without installing

Use zbx to run a package without linking it to your prefix:

zbx jq --version

This is useful for:

• One-time commands
• Testing packages before installation
• Running different versions temporarily

Common commands

Here’s a quick reference of the most common zerobrew commands:

Install packages

# Install one package
zb install jq

# Install multiple packages
zb install wget git curl

# Build from source instead of using bottles
zb install ffmpeg --build-from-source

# Install without creating symlinks
zb install libsodium --no-link

Advanced options

zerobrew supports several global options:

Concurrency control

Adjust the number of parallel operations (default is 20):

zb --concurrency 10 install ffmpeg

Custom directories

Override the default installation directories:

zb --root /custom/root --prefix /custom/prefix install jq

Or use environment variables:

export ZEROBREW_ROOT="/custom/root"
export ZEROBREW_PREFIX="/custom/prefix"
zb install jq

Auto-initialize

Automatically initialize zerobrew if not already set up:

zb --auto-init install jq

Shell completion

Generate shell completion scripts for your shell:

Bash

zb completion bash > ~/.local/share/bash-completion/completions/zb

Understanding the output

When you install a package, zerobrew shows detailed progress:

==> Installing jq...

Indicates the package being installed.

==> Resolving dependencies (3 packages)...
    jq 1.7.1
    oniguruma 6.9.9
    libffi 3.4.4

Shows all packages that will be installed, including dependencies.

==> Downloading and installing formulas...
    jq               ━━━━━━━━━━━━━━━━━━━━━━━━ ✓ installed
    oniguruma        ━━━━━━━━━━━━━━━━━━━━━━━━ ✓ installed
    libffi           ━━━━━━━━━━━━━━━━━━━━━━━━ ✓ installed

Progress bars for each package showing download and installation status.

==> Installed 3 packages in 1.23s

Summary with total time elapsed.

Next steps

Commands reference

Explore all available zerobrew commands and options

Configuration

Learn about environment variables and configuration options

Remember that zerobrew is experimental. If you encounter issues with a specific formula, you can always fall back to using Homebrew for that package while using zerobrew for others.