alphaonedev/macos-brew

Purpose

This skill automates Homebrew operations on macOS, enabling efficient management of software packages, including formulae, casks, services, taps, and version pinning. It focuses on core Homebrew features to handle package installation, updates, and system integration via the /opt/homebrew PATH.

When to Use

Use this skill for macOS package management tasks, such as installing dependencies in scripts, updating tools in CI/CD pipelines, or configuring development environments. Apply it when dealing with Homebrew-specific features like casks for GUI apps or taps for custom repositories, especially in automated workflows or when ensuring reproducible setups.

Key Capabilities

• Formulae Management: Install, upgrade, or remove command-line tools (e.g., via brew install wget), including dependency resolution and version pinning using brew pin <formula>.
• Casks Handling: Manage GUI applications (e.g., brew install --cask google-chrome), with options to ignore dependencies or force reinstalls.
• Services Control: Start, stop, or restart background services (e.g., brew services start postgresql), integrating with macOS launchd.
• Taps Integration: Add external repositories (e.g., brew tap homebrew/cask), enabling access to non-core packages.
• PATH and Bundle Management: Configure /opt/homebrew in PATH for scripts, and use brew bundle to manage package lists from a Brewfile for reproducible environments.
• Version Pinning: Lock package versions to prevent updates (e.g., brew pin node@14), ensuring stability in production setups.

Usage Patterns

Invoke this skill in shell scripts or automation tools by calling brew commands directly. Always check for Homebrew installation first using which brew or command -v brew. For scripted installs, use a Brewfile: create a file with lines like brew 'git' and cask 'docker', then run brew bundle --file Brewfile. In AI agents, wrap commands in try-catch blocks for error handling, and export PATH with /opt/homebrew/bin prepended. Example: In a bash script, install and pin a package like this:

brew install node@14
brew pin node@14

Another pattern: For services, combine with conditional checks, e.g., only start if not running: brew services list | grep -q postgresql || brew services start postgresql.

Common Commands/API

Homebrew is CLI-based, so use these commands directly in scripts. All commands run via brew <subcommand> [flags] [args].

• Install Formula: brew install <formula> --force to overwrite existing; e.g., brew install git --force.
• Install Cask: brew install --cask <cask> --no-quarantine to skip macOS security prompts; e.g., brew install --cask visual-studio-code --no-quarantine.
• Update Packages: brew update && brew upgrade <formula>; add --ignore-pinned to upgrade pinned versions.
• Manage Taps: brew tap <user/repo> to add a tap; e.g., brew tap homebrew/cask-fonts.
• Handle Services: brew services start <service> or brew services restart <service> --all; e.g., brew services stop redis.
• Bundle Operations: brew bundle --file Brewfile to install from a file; Brewfile format: brew 'package' or cask 'app'.
• Pin Versions: brew pin <formula> to pin; brew unpin <formula> to release; e.g., brew pin [email protected].
• Cleanup: brew cleanup -s to remove old versions; always run after upgrades.

For API-like usage, pipe outputs to scripts, e.g., brew list --versions | grep node to query installed versions.

Integration Notes

Integrate Homebrew into scripts by ensuring /opt/homebrew/bin is in PATH; add export PATH="/opt/homebrew/bin:$PATH" to .zshrc or scripts. In CI/CD (e.g., GitHub Actions), install Homebrew first with /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)". No authentication is required, but if extending to private taps, use Git credentials via environment variables like export HOMEBREW_GIT_EMAIL="[email protected]". For cross-tool integration, combine with macOS tools: e.g., after brew install ffmpeg, use it in Python scripts via subprocess. Config format for Brewfile: plain text with lines like brew 'jq' # JSON processor. Always verify Homebrew version with brew --version before complex operations.

Error Handling

Handle common errors by checking exit codes; brew commands return non-zero on failure. For "formula not found", use brew search <formula> first or install with brew install <formula> 2>/dev/null || echo "Error: Formula missing". If "Permission denied", run with sudo or fix ownership on /opt/homebrew (e.g., sudo chown -R $(whoami) /opt/homebrew). For network issues during brew update, retry with brew update --verbose and check connectivity. In scripts, wrap commands like:

if ! brew install git; then
  echo "Installation failed; check logs" >&2
  exit 1
fi

Log outputs with brew install <formula> >> install.log 2>&1. For version conflicts, use brew doctor to diagnose and resolve.

Concrete Usage Examples

1. Install and Pin a Development Tool: To set up a project with a specific Node.js version, run: brew install node@14 followed by brew pin node@14. This ensures the version doesn't auto-update, maintaining consistency.

2. Manage a Service for a Web App: For a Redis-backed app, start the service with brew services start redis, and verify with brew services list | grep redis. If it fails, check with brew doctor and restart.

Graph Relationships

• Connected to "macos" cluster for broader macOS tools.
• Relates to "packages" tag, linking to general package managers like apt or yum skills.
• Associated with "homebrew" tag, potentially linking to advanced scripting or CI tools in the ecosystem.