gh (GitHub CLI)

What it is

GitHub's official CLI for pull requests, issues, releases, Actions runs, and repo management against github.com and GitHub Enterprise hosts.

Install

Debian/Ubuntu, official apt repo (recommended — tracks the stable channel):

sudo mkdir -p -m 755 /etc/apt/keyrings
curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \
  | sudo tee /etc/apt/keyrings/githubcli-archive-keyring.gpg > /dev/null
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] \
  https://cli.github.com/packages stable main" \
  | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null
sudo apt update && sudo apt install gh

Alternative: download the linux_amd64 tarball from the releases page and drop bin/gh into ~/.local/bin. Pin a version there if you need reproducibility across machines.

Authenticate

gh auth login

Choose GitHub.com → HTTPS → browser flow. The token is stored in ~/.config/gh/hosts.yml (mode 600). Keep a copy of a fine-grained PAT in Vaultwarden (https://vault.portugalfuturista.org) as the recovery secret; prefer GH_TOKEN env var in CI instead of the interactive login.

Configure for this environment

github.com is not the default forge here — Forgejo is (see tea.md). Use gh only for the public GitHub mirrors.

If you ever point gh at a GHE-style host:

export GH_HOST=git.example.com          # per-shell default host
gh auth login --hostname git.example.com

Note: GH_HOST assumes a GitHub Enterprise API layout. Forgejo speaks the Gitea API, so gh will not work against it — use tea instead.

gh config set git_protocol https
gh config set editor nvim

Self-hosted equivalent

Forgejo at https://code.portugalfuturista.org (LAN 192.168.0.9:3001) is our default forge. The equivalent CLI is tea:

tea login add --url https://code.portugalfuturista.org

Everything you'd do with gh pr create maps to tea pr create against the Forgejo remote.

Aurélio integration

The cli-forge skill drives gh/tea for PR and issue workflows. The connector registry (.aurelio/connectors/registry.yaml) covers github.com under id github; the Forgejo instance is id forgejo.

Verify

gh --version
# gh version 2.x.x (YYYY-MM-DD)
gh auth status
# github.com
#   ✓ Logged in to github.com account <user> (...)
gh repo list --limit 3
# <owner>/<repo>  <description>  ...

Troubleshooting

gh talks to the wrong host — check echo $GH_HOST; unset it or pass --hostname github.com explicitly.
Auth prompts in headless shells — use GH_TOKEN=<pat> gh ... (token from Vaultwarden) instead of the browser flow.
error connecting to code.portugalfuturista.org — you used gh against Forgejo; switch to tea.
Old version from distro repo — Debian's gh package lags; use the official apt repo above.

3 KiB Raw Blame History