Homebrew

Distribute your CLI tools via Homebrew with automatic formula generation and tap updates.

Prerequisites

1. GitHub CLI installed and authenticated
2. A Homebrew tap repository
3. GitHub token with repo access

# Install GitHub CLI
brew install gh

# Authenticate
gh auth login

# Create a tap repository (if needed)
gh repo create my-org/homebrew-tap --public

Service Configuration

name: my-cli
provider: homebrew
project: my-org
license: MIT

build:
  language: go
  version: "1.23"
  env_vars:
    CGO_ENABLED: "0"

homebrew:
  tap_url: https://github.com/my-org/homebrew-tap
  project_url: https://github.com/my-org/my-cli
  token_env: GH_TOKEN

Required Fields

Field	Description
name	Binary and formula name
project	GitHub organization/user
homebrew.tap_url	URL to your Homebrew tap repository
homebrew.project_url	URL to your project repository
homebrew.token_env	Environment variable containing GitHub token

Optional Fields

Field	Type	Default	Description
license	string	-	Software license (MIT, Apache-2.0, etc.)
description	string	-	Package description

Deployment Steps

The Homebrew recipe executes:

1. build binaries — Cross-compile for macOS (Intel + Apple Silicon) and Linux
2. create checksums — Generate SHA256 checksums
3. create archives — Package binaries as .tar.gz
4. update formula — Generate Homebrew formula
5. push to tap — Commit and push to tap repository

Generated Formula

Pilum generates a formula like:

class MyCli < Formula
  desc "My awesome CLI tool"
  homepage "https://github.com/my-org/my-cli"
  version "1.0.0"
  license "MIT"

  on_macos do
    if Hardware::CPU.arm?
      url "https://github.com/my-org/my-cli/releases/download/v1.0.0/my-cli-darwin-arm64.tar.gz"
      sha256 "abc123..."
    else
      url "https://github.com/my-org/my-cli/releases/download/v1.0.0/my-cli-darwin-amd64.tar.gz"
      sha256 "def456..."
    end
  end

  on_linux do
    url "https://github.com/my-org/my-cli/releases/download/v1.0.0/my-cli-linux-amd64.tar.gz"
    sha256 "ghi789..."
  end

  def install
    bin.install "my-cli"
  end

  test do
    system "#{bin}/my-cli", "--version"
  end
end

GitHub Token

Set up a token with repo scope:

1. Go to GitHub → Settings → Developer settings → Personal access tokens
2. Generate a token with repo scope
3. Export it:

export GH_TOKEN="ghp_xxxxx"

Or add to your CI environment variables.

Example Commands

# Build and release
pilum deploy --tag=v1.0.0

# Build binaries only
pilum build --tag=v1.0.0

# Preview commands
pilum dry-run --tag=v1.0.0

Multi-Platform Builds

Pilum automatically builds for:

Platform	Architecture	File
macOS	Intel (amd64)	my-cli-darwin-amd64.tar.gz
macOS	Apple Silicon (arm64)	my-cli-darwin-arm64.tar.gz
Linux	x86_64 (amd64)	my-cli-linux-amd64.tar.gz

Troubleshooting

Formula Push Fails

Step 5: push to tap
  my-cli  ✗ - authentication required

Ensure GH_TOKEN is set:

export GH_TOKEN="ghp_xxxxx"

Checksum Mismatch

If users report checksum errors after updating:

1. Verify the release assets match the formula
2. Re-run pilum deploy --tag=vX.Y.Z to regenerate

Binary Not Found

Ensure the build produces the expected binary:

ls dist/
# Should show: my-cli-darwin-amd64, my-cli-darwin-arm64, my-cli-linux-amd64

Installation by Users

Once published, users install with:

brew tap my-org/tap
brew install my-cli

Or in one command:

brew install my-org/tap/my-cli

Next Steps

• Service Configuration — Full reference
• Build Configuration — Cross-compilation settings
• Troubleshooting — Common issues