# 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):

```bash
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](https://github.com/cli/cli/releases) and drop `bin/gh` into
`~/.local/bin`. Pin a version there if you need reproducibility across machines.

## Authenticate

```bash
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](tea.md)). Use `gh` only for the public GitHub mirrors.

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

```bash
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.

```bash
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.md):

```bash
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

```bash
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.