Using the GitHub CLI (gh)

When to Use

• Viewing or creating pull requests, issues, releases, or gists
• Fetching file contents, repo metadata, or any GitHub API data
• Interacting with GitHub Actions (runs, workflows)
• Any task involving GitHub that you might otherwise use curl, wget, or WebFetch for

When NOT to Use

• Non-GitHub URLs (use WebFetch or curl for those)
• Public web content that happens to be hosted on GitHub Pages (*.github.io) — those are regular websites
• Local git operations (git commit, git push) — use git directly

Key Principle

Always use gh instead of curl, wget, or WebFetch for GitHub URLs. The gh CLI uses the user’s authenticated token automatically, so it:

• Works with private repositories
• Avoids GitHub API rate limits (unauthenticated: 60 req/hr; authenticated: 5,000 req/hr)
• Handles pagination correctly
• Provides structured output and filtering

Quick Start

# View a repo
gh repo view owner/repo

# List and view PRs
gh pr list --repo owner/repo
gh pr view 123 --repo owner/repo

# List and view issues
gh issue list --repo owner/repo
gh issue view 456 --repo owner/repo

# Call any REST API endpoint
gh api repos/owner/repo/contents/README.md

# Call with pagination and jq filtering
gh api repos/owner/repo/pulls --paginate --jq '.[].title'

Common Patterns

Decoding File Contents

gh api repos/.../contents/... returns base64-encoded content. Decode it:

gh api repos/owner/repo/contents/path/to/file --jq '.content' | base64 -d

Or for binary files / large files, use the raw media type:

gh api repos/owner/repo/contents/path/to/file -H "Accept: application/vnd.github.raw+json"

References

• Pull Requests — list, view, create, merge, review PRs
• Issues — list, view, create, close, comment on issues
• Repos and Files — view repos, browse files, clone
• API — raw REST/GraphQL access, pagination, jq filtering
• Releases — list, create, download releases
• Actions — view runs, trigger workflows, check logs