GitHub CLI (`gh`) — install and auth¶

Use before running GitHub policy scans in diagnostic-prompt.md. Official docs: cli.github.com

Verify¶

gh --version
gh auth status

Windows (PowerShell, CMD, Windows Terminal)¶

Pick one install method.

winget (recommended)¶

winget install --id GitHub.cli

Close and reopen the terminal, then:

gh --version
gh auth login

Scoop¶

scoop install gh
gh auth login

Chocolatey¶

choco install gh
gh auth login

MSI installer (manual)¶

Download the latest .msi from GitHub CLI releases.
Run the installer (default adds gh to PATH).
Open a new terminal window.
Run gh auth login.

Git Bash on Windows¶

Git Bash does not ship with gh. Install gh using one of the Windows methods above (winget is usually simplest), then use Git Bash as the shell for audit commands.

After installing via winget / MSI¶

Restart Git Bash (or open a new tab) so PATH picks up the install.
Confirm:

gh --version

If gh: command not found, add the install directory to your user PATH. Typical location:

C:\Program Files\GitHub CLI\

System settings → Environment variables → Path → New → paste that path → OK → restart Git Bash.

Authenticate:

gh auth login

Choose:

GitHub.com
HTTPS (simplest) or SSH if the user already uses SSH keys with GitHub
Login with a web browser (recommended) or paste a token
For org-wide ruleset scans that need org admin APIs:

gh auth refresh -h github.com -s admin:org

Git Bash notes¶

Use the same gh repo view, gh api, and gh repo edit commands as Linux/macOS.
Paths in git commands use forward slashes; gh repo slugs use OWNER/REPO.
If browser login fails in Git Bash, run gh auth login from PowerShell once, then return to Git Bash — credentials are shared per user profile.

macOS¶

brew install gh
gh auth login

Linux / WSL¶

Debian / Ubuntu¶

sudo apt update
sudo apt install gh
gh auth login

Or follow official Linux install docs for newer versions via package repository.

Fedora¶

sudo dnf install gh
gh auth login

Auth scopes (policy audit)¶

Task	Scope
Single repo scan	Default auth (repo read)
Edit repo merge settings	Repo admin on target repo
List org rulesets	Often `admin:org`

Refresh scopes when API returns 403:

gh auth refresh -h github.com -s admin:org

No CLI — UI fallback¶

If install is not possible (locked-down machine, no admin):

Tell the user to open the repo on GitHub.com.
Collect screenshots or values from Settings → Rules → Rulesets and Settings → General → Pull Requests.
Continue the audit using github-controls.md UI paths.

Troubleshooting¶

Symptom	Cause	Fix
`gh: command not found` in Git Bash after install	Stale PATH in open session	Close Git Bash; reopen. Add `C:\Program Files\GitHub CLI\` to PATH if needed.
`winget` not found	Older Windows or App Installer missing	Use MSI, Scoop, or Chocolatey.
Browser login hangs in Git Bash	Limited browser handoff	Run `gh auth login` in PowerShell or use token paste option.
403 on org rulesets API	Missing org admin scope	`gh auth refresh -h github.com -s admin:org`
`gh auth status` shows logged out	Token expired	`gh auth login` again

GitHub CLI (gh) — install and auth¶