zb init

Initialize zerobrew directories and configure your shell environment

The zb init command sets up zerobrew for first use by creating necessary directories and configuring your shell environment to use zerobrew packages.

Usage

zb init [OPTIONS]

Options

--no-modify-path · flag

Skip automatic shell configuration. Use this if you want to manually configure your shell or manage PATH yourself.

What Gets Initialized

Directory Structure

The following directories are created:

• $ZEROBREW_ROOT/store - Content-addressable package storage
• $ZEROBREW_ROOT/db - Package installation database
• $ZEROBREW_ROOT/cache - Downloaded bottle cache
• $ZEROBREW_ROOT/locks - Concurrency control
• $ZEROBREW_PREFIX/bin - Symlinks to package executables
• $ZEROBREW_PREFIX/Cellar - Package installation directories (kegs)

Shell Configuration

Unless --no-modify-path is specified, init adds a configuration block to your shell profile:

For Bash/Zsh:

• Environment variables (ZEROBREW_DIR, ZEROBREW_ROOT, ZEROBREW_PREFIX, etc.)
• PKG_CONFIG_PATH configuration
• SSL/TLS certificate paths (CURL_CA_BUNDLE, SSL_CERT_FILE, SSL_CERT_DIR)
• PATH updates to include zerobrew binaries

For Fish:

• Creates ~/.config/fish/conf.d/zerobrew.fish with equivalent configuration

Shell Profile Detection

The command automatically detects your shell and updates the appropriate config file:

Shell	Config File Priority
zsh	.zshenv → .zshrc (respects $ZDOTDIR)
bash	.bash_profile → .bashrc
fish	.config/fish/conf.d/zerobrew.fish
other	.profile

Permissions

If the target directories require elevated permissions, init will:

1. Prompt for sudo to create directories
2. Create the directory structure
3. Change ownership to your user account

This is common when using system paths like /opt/zerobrew.

Examples

Standard Initialization

Configure zerobrew with default settings:

zb init

Output:

==> Initializing zerobrew...
    Creating directories (requires sudo)...
    ✓ Updated zerobrew configuration in /home/user/.bashrc
    ✓ Added /home/user/.zerobrew/bin and /opt/zerobrew/bin to PATH
==> Initialization complete!

Manual PATH Configuration

Skip automatic shell configuration:

zb init --no-modify-path

Output:

==> Initializing zerobrew...
    → Skipped shell configuration (--no-modify-path)
    → To use zerobrew, add /home/user/.zerobrew/bin and /opt/zerobrew/bin to your PATH
==> Initialization complete!

Then manually add to your shell config:

export ZEROBREW_DIR="$HOME/.zerobrew"
export ZEROBREW_PREFIX="/opt/zerobrew"
export PATH="$ZEROBREW_DIR/bin:$ZEROBREW_PREFIX/bin:$PATH"

Custom Paths

Use environment variables to customize locations:

zb --root /custom/root --prefix /custom/prefix init

On macOS, the prefix path is limited to 13 characters due to Mach-O binary format constraints. Longer paths will cause warnings and may fail for path-sensitive packages like git and curl.

Auto-Initialization

If you run any zerobrew command without initializing first, you’ll be prompted:

Note: Zerobrew needs to be initialized first.
    This will create directories at:
      • /home/user/.zerobrew
      • /opt/zerobrew

Initialize now? [Y/n]

To skip this prompt, use the --auto-init flag:

zb --auto-init install jq

Or set the environment variable:

export ZEROBREW_AUTO_INIT=1

Environment Variables Set

After initialization, these environment variables are configured:

ZEROBREW_DIR · string

Location of zerobrew installation (default: ~/.zerobrew)

ZEROBREW_BIN · string

Location of zerobrew binaries (default: ~/.zerobrew/bin)

ZEROBREW_ROOT · string

Root directory for zerobrew data (store, db, cache)

ZEROBREW_PREFIX · string

Installation prefix for packages (bin, Cellar)

PKG_CONFIG_PATH · string

Updated to include zerobrew’s pkg-config files

CURL_CA_BUNDLE · string

SSL certificate bundle (set if ca-certificates is installed)

SSL_CERT_FILE · string

SSL certificate file (set if ca-certificates is installed)

SSL_CERT_DIR · string

SSL certificate directory (set if ca-certificates is installed)

Managed Configuration Block

The shell configuration is wrapped in marker comments:

# >>> zerobrew >>>
# ... zerobrew configuration ...
# <<< zerobrew <<<

Running zb init again will update the configuration block without duplicating it.

Troubleshooting

Changes Not Taking Effect

After initialization, reload your shell configuration:

# Bash
source ~/.bashrc

# Zsh
source ~/.zshrc

# Or restart your terminal

Permission Denied

If you see permission errors, the command will prompt for sudo automatically. Ensure you have sudo privileges.

macOS Prefix Length Warning

Warning: Prefix "/opt/my-long-prefix" (18 chars) exceeds the macOS Mach-O limit of 13 characters.
         Path-sensitive packages (e.g. git, curl) will fail to install.
         Consider a shorter prefix, e.g.: zb init <root> /opt/zerobrew

Use a shorter prefix path (13 characters or less) on macOS.

Related Commands

• zb install - Install packages after initialization
• zb migrate - Migrate from Homebrew