Homebrew

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"