Homebrew Provider

Wraps Homebrew  — the brew command — to manage formulae and casks on macOS and Linux. For most macOS users, this is the first provider you’ll actually touch.

Platforms: macOS, Linux

Usage

# Install a formula (CLI tool)
hams brew install ripgrep
 
# Install a cask (GUI app)
hams brew install --cask visual-studio-code
 
# Remove
hams brew remove htop
 
# See what hams is managing
hams brew list
 
# Attach tags and a one-liner to an already-recorded package
hams brew enrich htop --hams-tag=cli --hams-intro="An interactive process viewer"

Every install actually runs brew install first, and on success writes the entry into <profile>/Homebrew.hams.yaml. Removal mirrors that: brew uninstall first, then the entry disappears from the YAML.

What a Hamsfile looks like

# macOS/Homebrew.hams.yaml
schema_version: 1
provider: Homebrew
 
groups:
  - tag: dev-tools
    items:
      - app: ripgrep
        intro: Fast recursive grep alternative.
      - app: htop
        tags: [cli]
        intro: An interactive process viewer.
      - app: ffmpeg
        intro: Multimedia framework for audio/video processing.
 
  - tag: apps
    items:
      - app: visual-studio-code
        cask: true
        intro: Microsoft's code editor.

• app is the name you’d type after brew install
• cask: true tells hams it’s a cask, not a formula
• tags and intro are for humans. brew couldn’t care less
• groups[].tag is your own grouping label — name it whatever makes sense

How state is probed

During apply, the Homebrew provider runs brew list --formula and brew list --cask and compares the machine’s actual installs against the Hamsfile:

• In the Hamsfile, not on the machine → install it
• On the machine, not in the Hamsfile → hams leaves it alone (it only manages what you declared)
• In both → skip, and record the installed version to .state/

That second point matters: hams won’t uninstall things you brew installed outside of hams. Not unless you explicitly added and then removed them from a Hamsfile.

First-time setup on a fresh Mac

On a brand-new machine that doesn’t have Homebrew yet, hams apply needs your permission to install it. By default — on a non-TTY (CI, pipe) — hams exits with an actionable error; on an interactive terminal, hams shows you the exact install.sh command, warns about the Xcode CLT dialog gotcha, and asks [y/N/s].

To skip the prompt and just go:

# Bootstrap brew then apply everything
hams apply --bootstrap --from-repo=zthxxx/hams-store

See hams apply → About the bootstrap prompt for the full rationale. Short version: hams never runs curl | bash from the internet without your explicit consent.

Importing an existing machine’s brew state

Moving your current brew setup into hams? Two options:

# Option 1: have hams scan what's installed and write it into the Hamsfile
hams brew list --import-existing
 
# Option 2: grab the list of top-level packages and move them in by hand
brew leaves > /tmp/brew-list.txt