Installation

The binary’s called gr.

Install link

  brew install d0ugal/tap/graith
  

  # add the signing key
curl -fsSL https://d0ugal.github.io/graith-repo/gpg/graith.gpg \
  | sudo tee /usr/share/keyrings/graith.gpg > /dev/null

# add the repo (signed-by pins it to our key only)
echo "deb [signed-by=/usr/share/keyrings/graith.gpg] \
https://d0ugal.github.io/graith-repo/deb stable main" \
  | sudo tee /etc/apt/sources.list.d/graith.list

sudo apt-get update
sudo apt-get install graith
  

  sudo tee /etc/yum.repos.d/graith.repo <<'EOF'
[graith]
name=graith
baseurl=https://d0ugal.github.io/graith-repo/rpm
enabled=1
gpgcheck=1
repo_gpgcheck=1
gpgkey=https://d0ugal.github.io/graith-repo/gpg/graith.asc
EOF

sudo dnf install graith
  

  # Debian / Ubuntu
sudo dpkg -i graith_*_linux_amd64.deb

# Fedora / RHEL
sudo rpm -i graith_*_linux_amd64.rpm

# Alpine
sudo apk add --allow-untrusted graith_*_linux_amd64.apk
  

  go install github.com/d0ugal/graith/cmd/graith@latest
  

  git clone https://github.com/d0ugal/graith
cd graith
make build    # produces ./gr
  

macOS upgrade and uninstall link

Normal Homebrew and tarball upgrades preserve service registrations. The new CLI validates and caches its matching signed app before a preserved restart; registration moves to that generation only while the job is down. If an older release cannot read newer persisted state, the existing state-version guard stops the downgrade and gr doctor lists the state backup to restore.

Before uninstalling, remove all per-user registrations while the signed package is still available:

  gr daemon service status --all-profiles
gr daemon service remove --all-profiles
brew uninstall graith            # or remove the tarball files
  

Removal preserves all user data. Homebrew has no supported pre-uninstall hook, so it cannot do the logged-in user’s Service Management cleanup automatically. If the package was removed first, reinstall the same or a newer signed release and run gr daemon service repair, then remove --all-profiles. Do not use a wildcard launchctl command: named profiles are independent exact jobs and an unknown live job is intentionally quarantined.

Native stable and graith-dev releases link

The normal stable release and moving dev release use the isolated libghostty backend on macOS arm64 and Linux amd64/arm64. Intel macOS is unsupported: new stable and dev releases do not publish a Darwin amd64 archive, and Homebrew stops with an unsupported-platform error instead of selecting another backend. Assets attached to historical releases remain unchanged.

For stable installations, Homebrew and the package repositories select the matching graith_<version>_darwin_arm64.tar.gz or Linux tar/deb/rpm/apk asset. For the moving channel, Homebrew selects versioned dev assets such as graith-dev_<dev-version>_darwin_arm64.tar.gz, graith-dev_<dev-version>_linux_amd64.tar.gz, or graith-dev_<dev-version>_linux_arm64.tar.gz for those native targets. Each native archive contains its final executable, normal release metadata, executable-bound libghostty-native.spdx.json, and THIRD_PARTY_NOTICES.libghostty.md. Stable Linux deb/rpm/apk packages carry the same executable bytes and native evidence. The matching checksum file binds every archive/package, and GitHub build provenance can be verified after download:

  archive=graith-dev_<dev-version>_linux_amd64.tar.gz
checksums=graith-dev_<dev-version>_checksums.txt
gh attestation verify "$archive" --repo d0ugal/graith
grep "  ${archive}$" "$checksums" > archive-checksum.txt
test "$(wc -l < archive-checksum.txt)" -eq 1
sha256sum --check archive-checksum.txt
  

For a stable download, substitute its exact filename, for example graith_0.70.0_linux_amd64.tar.gz, and use the stable checksums.txt; the same attestation and checksum commands apply. Verify a downloaded deb/rpm/apk by selecting its exact line from the same stable checksums.txt.

Use graith-dev_<dev-version>_linux_arm64.tar.gz on arm64. The release workflow builds each Linux artifact from the exact pinned Ghostty/Zig dependency unit on Linux, compares the executable across tar/deb/rpm/apk, and executes those final bytes on the target architecture before publication. Stable releases remain drafts until the complete same-revision set, checksums, provenance, configured signing, and downstream metadata have been prepared and validated. The complete GitHub release is exposed before that metadata is pushed, so its URLs never point at private draft assets; interrupted channel pushes are safe to retry.

After restarting the dev daemon, verify the selected canary without relying on a live helper process:

  gr-dev doctor
gr-dev doctor --json | jq -r .terminal_backend
  

Every supported stable/dev artifact reports libghostty-helper. See Troubleshooting for the matching startup and failure log records.

The dev and stable releases do not publish separately named rollback archives. Persistent scrollback remains backend-neutral, so a fresh native start, upgrade from an older release, or native-to-native upgrade needs no state conversion. On macOS, remove the relevant service registration before uninstalling its package as described above.

Shell completion link

  # bash
source <(gr completion bash)

# zsh
gr completion zsh > "${fpath[1]}/_gr"

# fish
gr completion fish | source

# powershell
gr completion powershell | Out-String | Invoke-Expression
  

Verify link

  gr version
gr doctor      # health checks, verifies dependencies