Brew It Yourself: Make Your CLI Tool Installable via Homebrew

Introduction

Ever built a useful shell script and wished others could install it as easily as brew install your-tool? This guide shows you how to package a custom Bash script into a fully functional Homebrew formula without needing to publish to the official core repo.

What is a Homebrew Tap?

A Homebrew tap is a GitHub repository that contains custom Homebrew formulas. Think of it as your personal app store instantly available via brew tap. Perfect for:

• Internal tools — Company-specific utilities
• Small utilities — Quick scripts you want to share
• Personal CLI workflows — Your custom dotfiles and tools

Step 1: Prepare Your Script

Ensure your script has proper structure:

#!/usr/bin/env bash
set -euo pipefail

# Your script logic here
echo "Hello from your-tool!"

# Make executable and tag release
chmod +x your-script.sh
git tag v1.0.0
git push origin v1.0.0

Step 2: Create Release Archive

Homebrew needs a downloadable archive with a SHA256 checksum:

# Download tarball of your tag
curl -L -o v1.0.0.tar.gz \
  https://github.com/YOURNAME/YOUR_REPO/archive/refs/tags/v1.0.0.tar.gz

# Generate SHA256 checksum — you'll need this
shasum -a 256 v1.0.0.tar.gz

Step 3: Create the Tap Repository

Create a new repo named homebrew-<your-tap-name>. The homebrew- prefix is required.

Formula Structure

class YourTool < Formula
  desc "Description of your tool"
  homepage "https://github.com/YOURNAME/YOUR_REPO"
  url "https://github.com/YOURNAME/YOUR_REPO/archive/refs/tags/v1.0.0.tar.gz"
  sha256 "YOUR_SHA256_HASH_HERE"
  license "MIT"

  def install
    bin.install "your-script.sh" => "your-tool"
  end

  test do
    system "#{bin}/your-tool", "--help"
  end
end

Step 4: Users Install Your Tool

Once published, anyone can install with:

# Add your tap
brew tap YOURNAME/YOUR_REPO

# Install the tool
brew install your-tool

# Verify it works
your-tool --help

Key Tips for Success

Releasing Updates

# Tag new version
git tag v1.1.0
git push origin v1.1.0

# Get new SHA256
curl -L -o v1.1.0.tar.gz URL
shasum -a 256 v1.1.0.tar.gz

# Update formula with new version + SHA