gh

GitHub CLI (gh) — Setup and Usage

Purpose

Ensures the GitHub CLI (gh) is available and provides correct usage patterns for AI agents operating in environments where gh may not be pre-installed and where git remotes point to local proxies instead of github.com.

When to Use

• gh command not found or shutil.which("gh") returns None
• Need to interact with GitHub API (issues, PRs, releases, workflows)
• Repository remote does not point to github.com (proxy environments)
• Need authenticated GitHub operations with GITHUB_TOKEN
• Managing GitHub Issues, Projects V2, Milestones, or Labels

---

Installation

If gh is not installed, run the setup script:

uv run .claude/skills/gh/scripts/setup_gh.py

The script:

1. Checks if gh is already installed via shutil.which
2. Detects platform (Linux, macOS, Windows) and architecture
3. Fetches the latest release from https://github.com/cli/cli/releases/latest
4. Downloads the correct archive with SHA256 verification from checksums file
5. Extracts and installs the binary to a writable PATH directory
6. Uses GITHUB_TOKEN for authenticated requests; falls back to anonymous if auth fails (401/403)

CLI options:

--force          Reinstall even if already at latest version
--dry-run        Show what would happen without installing
--bin-dir        Override install directory (default: auto-detect from PATH)
--detect-only    Detect owner/repo, refresh .dh/config.yaml and gh-examples.md, print examples to stdout. No network calls.

---

Authentication

GITHUB_TOKEN environment variable provides automatic authentication. No manual gh auth login needed.

# Verify authentication
gh auth status

If GITHUB_TOKEN is set, gh authenticates automatically for all API calls.

---

Repository Detection

<repo_detection>

Git remote points to a local proxy (127.0.0.1), NOT github.com. Every gh command fails without explicit repo specification:

failed to determine base repo: none of the git remotes configured for this
repository point to a known GitHub host.