bold-brew/README.md

Bold Brew (bbrew)

A modern Terminal UI for managing Homebrew packages and casks

Website • Docs • Changelog

---

🌟 Official Homebrew TUI for Project Bluefin

Bold Brew is the official Terminal UI for managing Homebrew in Project Bluefin and Aurora, next-generation Linux desktops that serve tens of thousands of users worldwide.

"This application features full package management for homebrew in a nice nerdy interface"
— Bluefin Documentation

---

✨ Features

• 🚀 Modern TUI Interface - Clean and responsive terminal user interface
• 📦 Complete Package Management - Manage both Homebrew formulae and casks
• 📋 Brewfile Mode - Curated package collections from Brewfiles (perfect for themed installers)
• 🔍 Advanced Search - Fast fuzzy search across all packages
• 🎯 Smart Filters - Filter by installed, outdated, leaves, or casks
• 📊 Analytics Integration - See popular packages based on 90-day download stats
• 🔄 Real-time Updates - Live feedback during package operations
• ⌨️ Keyboard Shortcuts - Intuitive keybindings for all operations
• 🎨 Type Indicators - Visual distinction between formulae [F] and casks [C]
• 🗂️ XDG Compliance - Follows XDG Base Directory Specification for cache storage
• 🔒 Security Scanning - Automated vulnerability and security checks

🛠️ Installation

Via Homebrew

brew install Valkyrie00/homebrew-bbrew/bbrew

Manually

Download the latest version from the releases page

📖 Quick Start

Standard Mode

Launch the application to browse all Homebrew packages:

bbrew

Brewfile Mode (New!)

Launch with a curated Brewfile to show only specific packages:

bbrew -f /path/to/Brewfile

In Brewfile mode, you can:

• View only packages from the Brewfile
• Pick and choose what to install individually
• Use all standard features (search, filters, etc.)

Perfect for creating themed collections like IDE choosers, dev tools, AI tools, K8s tools, etc.

See the examples/ directory for ready-to-use Brewfiles.

Keyboard Shortcuts

Navigation & Search

• / - Search packages (fuzzy search)
• ↑/↓ or j/k - Navigate package list
• Enter - View package details
• Esc - Clear search / Close modals

Filters

• F - Filter installed packages
• O - Filter outdated packages
• L - Filter leaves (explicitly installed, no dependencies)
• C - Filter casks only

Package Operations

• I - Install selected package
• U - Update selected package
• R - Remove selected package
• Ctrl+U - Update all outdated packages

Other

• Ctrl+R - Refresh package database
• Q - Quit application

📋 What's New in v2.0.0

🎉 Major Features

• Homebrew Casks Support - Full support for managing GUI applications and binaries
• Leaves Filter - Show only explicitly installed packages (excluding dependencies)
• XDG Base Directory Support - Cache follows platform standards (~/.cache/bbrew on Linux, ~/Library/Caches/bbrew on macOS)
• Type Indicators - Clear visual distinction between formulae [F] and casks [C]

🔧 Technical Improvements

• Updated to Go 1.25
• Migrated to Podman and OCI-compliant Containerfile
• Enhanced Makefile with 15+ new targets and help system
• Integrated automated security scanning (govulncheck + gosec)
• Fixed implicit memory aliasing issues
• Improved error handling and logging

🐛 Bug Fixes

• Fixed cask analytics endpoint
• Corrected installed casks detection
• Fixed tview special character rendering for type tags
• Improved directory permission handling (0750)

🖼️ Screenshots

Main interface with package list and filters

Filtered view showing installed packages

Fuzzy search in action

📊 Platform Support

Platform	Support	Notes
🍎 macOS	✅ Full	Native Homebrew support
🐧 Linux	✅ Full	Linuxbrew/Homebrew support

🛡️ Security

Security is a priority for Bold Brew. We use:

• govulncheck - Go vulnerability database scanning
• gosec - Static security analysis
• Automated CI/CD - Security checks on every PR and push

Found a security issue? Please report it privately via GitHub Security Advisories.

🔧 Development

Prerequisites

• Go 1.25+
• Homebrew (for testing)
• Podman (optional, for containerized builds)

Building from Source

# Clone the repository
git clone https://github.com/Valkyrie00/bold-brew.git
cd bold-brew

# Build locally
make build-local

# Run tests
make test

# Run linter
make quality-local

# Run security scans
make security

Project Structure

bold-brew/
├── cmd/bbrew/           # Main application entry point
├── internal/
│   ├── models/          # Data models (Formula, Cask, Package)
│   ├── services/        # Business logic (Brew, App, I/O)
│   └── ui/              # TUI components and layout
├── .github/workflows/   # CI/CD pipelines
└── Makefile             # Build automation

🤝 Contributing

Contributions are welcome! Please:

1. 🍴 Fork the project
2. 🔨 Create your feature branch (git checkout -b feat/amazing-feature)
3. 📝 Commit your changes using Conventional Commits
4. 🧪 Run tests and linters (make test quality-local)
5. 🚀 Push to the branch (git push origin feat/amazing-feature)
6. 📬 Open a Pull Request

🦸Contributors

Bold Brew exists thanks to the efforts of these wonderful people

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

💖 Support

• 🌟 Star the project
• 🐛 Report a bug
• 💡 Request a feature
• 📣 Share the project with your friends

---

_{Built with ❤️ for the community and for all developers}