Using the GitHub CLI (gh )

When to Use

• Browsing or reading code from a GitHub repository — clone it and use Read/Glob/Grep

• Viewing or creating pull requests, issues, releases, or gists

• Fetching 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

Browsing Repository Code

To read or browse files from a GitHub repo, clone it locally and use normal file tools (Read, Glob, Grep). This is much faster and more natural than fetching files one-by-one via the API.

Clone to a session-scoped temp directory (cleaned up automatically on session end)

clonedir="$TMPDIR/gh-clones-${CLAUDE_SESSION_ID}" mkdir -p "$clonedir" gh repo clone owner/repo "$clonedir/repo" -- --depth 1

After cloning, use the Explore agent (via the Task tool with subagent_type=Explore ) to investigate the cloned repo. The Explore agent can use Read, Glob, and Grep across the clone efficiently — much better than calling them one at a time:

Task(subagent_type="Explore", prompt="In $clonedir/repo/, find how authentication is implemented")

For targeted lookups on a clone you already understand, use Read/Glob/Grep directly.

• gh repo clone uses the user's authenticated token — works with private repos

• --depth 1 keeps the clone fast (only latest commit)

• No cleanup needed — a SessionEnd hook removes the clone directory automatically

• Use gh api only when you need a quick single-file lookup without cloning

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 a blob/tree URL Clone with gh repo clone and use Read/Glob/Grep

WebFetch on raw.githubusercontent.com/...

Clone with gh repo clone and use Read

WebFetch on api.github.com/...

gh api <endpoint>

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

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