homebrew

name	homebrew
description	Install and manage CLI tools with Homebrew — the primary CLI package manager on Bluefin.
domain	sysadmin

Homebrew

Homebrew is the primary CLI tool installer on Bluefin. Because the base OS image is immutable, brew install is the correct way to add CLI utilities to the user environment. Homebrew runs rootless under /home/linuxbrew and does not require sudo.

Load with: point your agent at this file.

When to Use

• Installing any CLI tool or developer utility
• Managing a declarative package list via Brewfile
• Updating installed CLI tools independently of the OS image

When NOT to Use

• GUI applications — use flatpak install or Bazaar instead
• OS-level system tools or kernel modules — use a Distrobox container
• Language-specific packages (npm, pip, cargo) — use the language's own package manager inside a dev container

Installation Location

Homebrew on Bluefin is pre-installed at /home/linuxbrew/.linuxbrew. It is configured system-wide via /etc/profile.d/brew.sh (from ublue-os/brew).

Default shell behavior (bash): Brew environment variables are set, but PATH is appended — system binaries take precedence over Homebrew. This is intentional design to prevent brew from overriding critical system tools like dbus.

zsh (optional shell): Full brew shellenv runs — brew binaries are prepended to PATH, so brew takes precedence over system binaries.

Default shell on Bluefin: bash — verify with getent passwd $USER | cut -d: -f7

Verify the installation:

which brew
brew --prefix   # should print /home/linuxbrew/.linuxbrew

Core Commands

# Search for a package
brew search <name>

# Install a package
brew install <formula>

# Remove a package
brew remove <formula>

# Update Homebrew itself and refresh formula metadata
brew update

# Upgrade all installed packages
brew upgrade

# Upgrade a specific package
brew upgrade <formula>

# List installed packages
brew list

# Show info about a package
brew info <formula>

Bluefin ujust Integration

Bluefin provides two ujust recipes that wrap Homebrew workflows:

# Install packages from the Bluefin curated Brewfile
# (includes common developer tools: gh, fzf, ripgrep, bat, etc.)
ujust bbrew

# Set up the full Bluefin CLI experience
# (installs the Bluefin shell environment and curated tool set)
ujust bluefin-cli

Run ujust --show bbrew or ujust --show bluefin-cli to see exactly what each installs.

Brewfile — Declarative Package Management

A Brewfile lets you declare packages as code and reproduce an environment:

# ~/Brewfile
brew "gh"
brew "fzf"
brew "ripgrep"
brew "bat"
brew "eza"
brew "zoxide"

# Install everything in ~/Brewfile
brew bundle

# Install from a specific file
brew bundle --file=~/dotfiles/Brewfile

# Check which Brewfile entries are not yet installed
brew bundle check

# Remove packages not listed in Brewfile (careful — destructive)
brew bundle cleanup --force

Keeping Packages Current

# Update metadata + upgrade everything (recommended weekly habit)
brew update && brew upgrade

# Check for problems with the Homebrew install
brew doctor

Troubleshooting

brew not found:

Brew is configured via /etc/profile.d/brew.sh for interactive login shells. If brew is not found:

• Non-interactive shell (e.g., a script, SSH command without login): source the profile explicitly or use the full path /home/linuxbrew/.linuxbrew/bin/brew
• Wrong shell invocation: ensure you launched an interactive login shell (bash -l or a new terminal session)
• Verify the system config exists: ls /etc/profile.d/brew.sh

⚠️ Do NOT add eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)" to ~/.bashrc — this would prepend brew bins to PATH and break the intentional system-over-brew priority for bash users.

Formula fails to build:

brew install --verbose <formula>   # verbose output shows where it fails
brew doctor                        # checks for common environment issues

Outdated formula metadata:

brew update   # refreshes the formula index

System binary priority (bash — default shell): In the default bash shell, system binaries take precedence over Homebrew. This is intentional by design — brew bins are appended to PATH via /etc/profile.d/brew.sh. There is no conflict to work around for bash users.

zsh users who want system-over-brew priority: If you use zsh and need system binaries to take precedence, add to ~/.zshrc:

# Override brew shellenv to append instead of prepend
eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv | grep -Ev '\bPATH=')"
export PATH="${PATH}:${HOMEBREW_PREFIX}/bin:${HOMEBREW_PREFIX}/sbin"