bakepkg

✨ Features

• 🚀 Simple: Build a signed, notarized .pkg from a single JSON config.
• ⚙️ Auto-scripting: Generates postinstall, uninstall.sh, and upgrade scripts automatically — no manual scripting required.
• 🛤️ PATH Integration: Writes /etc/paths.d and /etc/manpaths.d entries so binaries and man pages are immediately discoverable.
• 🖥️ Distribution UI: First-class support for Welcome screens, READMEs, Licenses, and Background images (including Dark Mode).
• 👤 Single-User Mode: Generates distribution packages with per-user installation domain choices.
• 🔐 Integrated Signing: Automatically signs binaries and the final installer with your Developer ID.
• 🍎 Modern Notarization: Directly integrates with Apple's Notary API — no more xcrun altool.
• 🧹 Automatic Sanitization: Strips com.apple.quarantine attributes to ensure smooth Gatekeeper validation.
• 🔬 Simulation Mode: Dry-run mode prints all commands without touching the system.
• 📚 Go Library: Use as a fluent API in your own Go tooling.

📦 Installation

Pre-built Binaries

Download the latest pre-built binary for macOS from the GitHub Releases page.

1. Visit the releases page.
2. Download the archive matching your architecture (x86_64 or arm64).
3. Extract and move the bakepkg binary to a directory in your $PATH (e.g., /usr/local/bin).

From Source

Requires Go 1.24 or later.

go install al.essio.dev/cmd/bakepkg@latest

To build from a local checkout:

make build

🚀 Usage

bakepkg [OPTION...]

bakepkg reads its configuration from bakepkg.json in the current directory by default.

# Use default config (bakepkg.json)
bakepkg

# Specify a custom config file
bakepkg -config custom.json

# Verbose output
bakepkg -verbose

⚙️ Options

📄 JSON Configuration

All build settings are defined in bakepkg.json.

Example bakepkg.json

{
  "id": "com.example.mytool",
  "name": "MyTool",
  "version": "1.2.0",
  "output": "MyTool-1.2.0.pkg",
  "symlink_binaries": true,

  "files": {
    "bin":             ["./build/mytool"],
    "share/man/man1":  ["./docs/mytool.1"],
    "etc":             ["./config/defaults.yaml"]
  },

  "distribution": {
    "readme":           "./docs/README.txt",
    "license":          "./docs/LICENSE.txt",
    "welcome":          "./docs/WELCOME.txt",
    "background":       "./assets/bg.png",
    "background_dark":  "./assets/bg-dark.png"
  },

  "signing": {
    "identity":         "Developer ID Installer: Your Name (XYZ)",
    "notarize":         true,
    "issuer_id":        "...",
    "key_id":           "...",
    "private_key_b64":  "..."
  }
}

Files are always installed under /Library/<Name>/<Version>/. The files object maps destination subdirectories (relative to the install prefix) to lists of source paths. For example, "bin": ["./build/mytool"] installs to /Library/MyTool/1.2.0/bin/mytool.

Configuration Reference

Notarization credentials can also be supplied via environment variables — the config fields take precedence if both are set.

📚 Library Usage

import "al.essio.dev/cmd/bakepkg/pkg/pkginstaller"

builder := pkginstaller.New().
    WithIdentifier("com.example.mytool").
    WithName("MyTool").
    WithVersion("1.2.0").
    AddFile("build/mytool", "bin/mytool").
    WithSymlinkBinaries(true).
    WithDistributionUI(pkginstaller.Distribution{
        Readme:  "docs/README.md",
        License: "docs/LICENSE.txt",
    }).
    WithSigning(pkginstaller.Signing{
        Identity:      "Developer ID Installer: Example (XYZ)",
        Notarize:      true,
        IssuerID:      os.Getenv("MACOSNOTARYLIB_ISSUER_ID"),
        KeyID:         os.Getenv("MACOSNOTARYLIB_KID"),
        PrivateKeyB64: os.Getenv("MACOSNOTARYLIB_PRIVATE_KEY"),
    })

err := builder.Build("MyTool-1.2.0.pkg")

See the pkg/pkginstaller package documentation and the examples/ directory for more.

🔧 Requirements

The following native macOS tools must be available in $PATH:

• pkgbuild
• productbuild
• productsign
• codesign
• stapler