Get Started

This tutorial uses meigma/ghd/ghd-example@1.1.1, the first-party example release published from this repository. It is a small direct-binary package used to validate ghd against real GitHub releases, release attestations, and SLSA provenance.

Install ghd

On macOS, install ghd from the Homebrew tap:

brew install --cask meigma/tap/ghd

You can also download the asset for your operating system and architecture from GitHub Releases, place the ghd binary somewhere on your PATH, and confirm it runs:

ghd --help

For GitHub API rate limits, authenticated requests are more reliable:

export GITHUB_TOKEN="$(gh auth token)"

Download a Verified Asset

Start with a standalone download. This writes the verified release asset and its verification evidence to the output directory, but it does not install anything.

ghd download "meigma/ghd/ghd-example@1.1.1" \
  --output "$HOME/Downloads/ghd-example"

After the command succeeds, the output directory contains the verified artifact and its verification evidence:

$HOME/Downloads/ghd-example/ghd-example_1.1.1_<os>_<arch>
$HOME/Downloads/ghd-example/verification.json

The verification.json file records the package, version, selected release asset, accepted immutable release attestation, and accepted SLSA provenance attestation.

Index the Example Repository

Add the repository to the local package index:

ghd repo add meigma/ghd

List indexed packages:

ghd list

Show details for the example package:

ghd info ghd-example

Install the Example Package

Install verifies the release first, then asks for approval before exposing binaries:

ghd install "ghd-example@1.1.1"

The installed binary is linked from the managed binary directory, which defaults to $HOME/.local/bin on Unix-like systems.

Confirm that the managed command works:

ghd-example version
ghd-example

Check and Verify the Install

Check for available updates:

ghd check ghd-example

Re-verify the installed package:

ghd verify ghd-example

List installed packages:

ghd installed

Clean Up

Remove the installed example package:

ghd uninstall ghd-example

Removing a repository from the index is separate from uninstalling packages:

ghd repo remove meigma/ghd