metalbrew

name	metalbrew
description	Use when installing, removing, searching, inspecting, or upgrading macOS (Apple Silicon) command-line packages with the metalbrew CLI — a Homebrew-compatible, Zig-based bottle package manager that installs into ~/.metalbrew without sudo. Also use when the user mentions "metalbrew", or wants brew-style package management without Homebrew or Ruby.

metalbrew

Overview

metalbrew is a Homebrew-compatible package manager written in Zig. It reads Homebrew's public formulae.brew.sh JSON index and installs the same prebuilt bottles (from ghcr.io, sha256-verified) into its own prefix — ~/.metalbrew by default, no sudo. It never touches an existing Homebrew.

Target: macOS arm64 (Apple Silicon) only.

When to use

• Installing / removing / upgrading CLI tools on Apple Silicon without Homebrew.
• Installing macOS GUI apps or vendor binaries via metalbrew cask.
• Searching or inspecting formula metadata and dependencies.
• The user names metalbrew, or wants brew-like installs without Ruby/sudo.

Not for: Linux or Intel macs; building from source (bottles only).

Quick reference

Command	What it does
metalbrew update	Download + cache the formula index. Run this first.
metalbrew info <formula>	Version, description, dependencies.
metalbrew search <query>	Case-insensitive substring search over names.
metalbrew deps <formula>	Transitive runtime deps, in install order.
metalbrew install <formula>	Fetch + verify + relocate + link a bottle and its deps.
metalbrew list	List installed packages.
metalbrew uninstall <formula>	Unlink and remove an installed package.
metalbrew upgrade [<formula>]	Upgrade all installed packages, or just one.

Casks (GUI apps and vendor binaries)

Use metalbrew cask when the user wants to install a macOS GUI app or a vendor-distributed binary, rather than a CLI tool from the Homebrew formula index.

Command	What it does
metalbrew cask install <token>	Download, verify, and install a cask.
metalbrew cask uninstall <token>	Remove a cask and its artifacts.
metalbrew cask info <token>	Version, homepage, artifact type.
metalbrew cask list	List installed casks.
metalbrew cask upgrade [<token>]	Upgrade all casks, or just one.

Key points:

• Apps (.zip, .dmg, .tar.gz app bundles) go to ~/Applications; binaries go to <prefix>/bin. Artifacts are staged under <prefix>/Caskroom/<token>/<version>/.
• No sudo required except for .pkg casks — those need metalbrew --allow-sudo cask install <token>.
• The com.apple.quarantine xattr is kept; Gatekeeper may prompt on first launch — this is expected (right-click → Open, or approve in System Settings).

Key facts

• update is a prerequisite. info, search, deps, install, and upgrade read the cached index; without it they report "No index. Run metalbrew update first."
• Prefix: defaults to ~/.metalbrew (Cellar/, bin/, opt/, …). Override per-invocation with the METALBREW_PREFIX env var.
• Linked binaries land in ~/.metalbrew/bin. Add it to PATH to run them, or invoke directly (e.g. ~/.metalbrew/bin/xz --version).
• Bottles are integrity-checked (sha256) and relocated + ad-hoc re-signed so they run from the metalbrew prefix.

Common mistakes

• Running install/search before update → "No index" message. Fix: update first.
• Expecting Intel/Linux support — it's arm64 macOS only.
• Expecting tools on PATH immediately — link target is ~/.metalbrew/bin.

Verify it's installed

metalbrew --version (or metalbrew help) lists the commands above. Install this skill itself into ~/.claude/skills/ with metalbrew skill install.