Installing in detail

This page expands Install: checking a binary you downloaded yourself, and what ghostbranch doctor shows right after an install.

Check the download

If you downloaded a binary from the Install page or the releases page, fetch checksums.txt from the same release and compare. If you have cosign, check that checksums.txt itself was signed by our release workflow too:

TerminalCopy

$ shasum -a 256 --ignore-missing -c checksums.txt

ghostbranch_0.3.0_darwin_arm64.tar.gz: OK

$ cosign verify-blob \

--bundle checksums.txt.sigstore.json \

--certificate-identity "https://github.com/ghostbranch-labs/ghostbranch/.github/workflows/release.yml@refs/tags/v0.3.0" \

--certificate-oidc-issuer https://token.actions.githubusercontent.com \

checksums.txt

Verified OK

On Windows, Get-FileHash .\ghostbranch_0.3.0_windows_amd64.zip prints the SHA-256 to compare with its line in checksums.txt.

Your system may block the download

The binaries aren’t signed with an Apple or Microsoft certificate yet, so a file downloaded in a browser gets flagged. After you’ve checked the download, clear the flag in the folder you unpacked it to:

macOS

xattr -d com.apple.quarantine ./ghostbranch

Windows

Unblock-File .\ghostbranch.exe (in PowerShell)

The install routes don’t get flagged.

Signing needs a paid certificate for each platform, renewed every year. Sponsoring Ghostbranch helps pay for it.

Sponsor (opens in a new tab)

Check that it works

Run ghostbranch doctor. It checks your setup, names the fix for anything that’s wrong, and changes nothing. Right after you install, it looks like this:

TerminalCopy

$ ghostbranch doctor

✓ tools git 2.43.0; ghostbranch v0.3.0, commit d4fb792f8a0f

✗ token no GitHub token: run `ghostbranch login`, or set GHOSTBRANCH_TOKEN or GH_TOKEN, or run `gh auth login`

fix: ghostbranch login

– app not an app login, so there is no Ghostbranch app to check

– pair not in a checkout of a registered public repo; pass --repo <owner/repo> to check a pair

– guard no pair, so no public repo to guard (see pair)

✓ state workspace "default"; the records are readable, none is newer than this binary, and no gate job has been pending for over an hour (features not checked: no readable pair); its state directories are private to you

– ci no readable pair to audit (see pair)

update check: on · last looked just now · up to date

error: 1 check(s) failed: token [DOCTOR_FAILED]

Next:

ghostbranch login (a person must run this)

token: no GitHub token: run `ghostbranch login`, or set GHOSTBRANCH_TOKEN or GH_TOKEN, or run `gh auth login`

Each line is one check. The mark in front says how it went:

Mark	Meaning
check mark	Passed.
exclamation mark	A warning: things work, but read the message.
cross	Failed. The fix: line below it is the command that fixes it.
–	Skipped: there’s nothing to check yet.

The token check fails because you haven’t logged in yet. The app check waits for a login with the Ghostbranch app. The pair, guard and CI checks wait until you set up a repo. Then doctor checks it from inside its clone, or from outside any clone if it’s your only pair.

The last line of doctor says how the update check stands: see Updates, and no telemetry. ghostbranch doctor explains each check.