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
| Instead of |
Use |
WebFetch on github.com/owner/repo |
gh repo view owner/repo |
WebFetch on api.github.com/... |
gh api <endpoint> |
WebFetch on raw.githubusercontent.com/... |
gh api repos/owner/repo/contents/path |
curl https://api.github.com/... |
gh api <endpoint> |
curl with -H "Authorization: token ..." |
gh api <endpoint> (auth is automatic) |
wget to download a release asset |
gh release download --repo owner/repo |
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
1---2name: using-gh-cli3description: Guides usage of the GitHub CLI (gh) for interacting with GitHub repositories, PRs, issues, and API. Use when working with GitHub resources instead of WebFetch or curl.4---5
6# Using the GitHub CLI (`gh`)
7
8## When to Use
9
10- Viewing or creating pull requests, issues, releases, or gists
11- Fetching file contents, repo metadata, or any GitHub API data
12- Interacting with GitHub Actions (runs, workflows)
13- Any task involving GitHub that you might otherwise use `curl`, `wget`, or `WebFetch` for
14
15## When NOT to Use
16
17- Non-GitHub URLs (use `WebFetch` or `curl` for those)
18- Public web content that happens to be hosted on GitHub Pages (`*.github.io`) — those are regular websites
19- Local git operations (`git commit`, `git push`) — use `git` directly
20
21## Key Principle
22
23**Always use `gh` instead of `curl`, `wget`, or `WebFetch` for GitHub URLs.** The `gh` CLI uses the user's authenticated token automatically, so it:
24
25- Works with private repositories
26- Avoids GitHub API rate limits (unauthenticated: 60 req/hr; authenticated: 5,000 req/hr)
27- Handles pagination correctly
28- Provides structured output and filtering
29
30## Quick Start
31
32```bash
33# View a repo
34gh repo view owner/repo
35
36# List and view PRs
37gh pr list --repo owner/repo
38gh pr view 123 --repo owner/repo
39
40# List and view issues
41gh issue list --repo owner/repo
42gh issue view 456 --repo owner/repo
43
44# Call any REST API endpoint
45gh api repos/owner/repo/contents/README.md
46
47# Call with pagination and jq filtering
48gh api repos/owner/repo/pulls --paginate --jq '.[].title'
49```
50
51## Common Patterns
52
53| Instead of | Use |
54|------------|-----|
55| `WebFetch` on `github.com/owner/repo` | `gh repo view owner/repo` |
56| `WebFetch` on `api.github.com/...` | `gh api <endpoint>` |
57| `WebFetch` on `raw.githubusercontent.com/...` | `gh api repos/owner/repo/contents/path` |
58| `curl https://api.github.com/...` | `gh api <endpoint>` |
59| `curl` with `-H "Authorization: token ..."` | `gh api <endpoint>` (auth is automatic) |
60| `wget` to download a release asset | `gh release download --repo owner/repo` |
61
62## Decoding File Contents
63
64`gh api repos/.../contents/...` returns base64-encoded content. Decode it:
65
66```bash
67gh api repos/owner/repo/contents/path/to/file --jq '.content' | base64 -d
68```
69
70Or for binary files / large files, use the raw media type:
71
72```bash
73gh api repos/owner/repo/contents/path/to/file -H "Accept: application/vnd.github.raw+json"
74```
75
76## References
77
78- [Pull Requests](references/pull-requests.md) — list, view, create, merge, review PRs
79- [Issues](references/issues.md) — list, view, create, close, comment on issues
80- [Repos and Files](references/repos-and-files.md) — view repos, browse files, clone
81- [API](references/api.md) — raw REST/GraphQL access, pagination, jq filtering
82- [Releases](references/releases.md) — list, create, download releases
83- [Actions](references/actions.md) — view runs, trigger workflows, check logs
tools-only