GitHub CLI (gh)

Use gh for all GitHub tasks from the terminal. Prefer gh over raw curl to GitHub API when a subcommand exists.

Install

Windows (preferred)

winget install --id GitHub.cli --source winget

Open a new terminal after install, then verify:

gh --version

Other platforms

Authentication

gh auth login is interactive — the user must complete prompts in the terminal. Do not run it unattended expecting full automation.

When to authenticate

1. gh auth status fails or shows "not logged in"
2. User wants a different account or extra token scopes
3. First-time setup after install

Login workflow

Run and let the user answer prompts:

gh auth login

Recommended choices for most development work:

For GitHub Enterprise:

gh auth login --hostname <hostname>

Verify auth

gh auth status

Expected: logged-in account, active token, and scopes (repo minimum for private repos and PRs).

Add scopes later

gh auth refresh -s workflow,read:org

Common scopes: repo, read:org, workflow, gist, project.

Environment / CI (no interactive login)

Set GITHUB_TOKEN (or GH_TOKEN) with a PAT or Actions token. gh uses it automatically.

Dynamic context (required)

Never hardcode GitHub usernames, orgs, or repo names. Resolve them at runtime for whoever is authenticated.

Resolve before GitHub work

Run at the start of any GitHub task (or use the helper script):

powershell -File scripts/get-context.ps1

Or manually:

gh auth status
gh api user --jq '{login: .login, name: .name}'
gh repo view --json nameWithOwner,defaultBranchRef -q '.nameWithOwner'   # inside a git repo
git remote get-url origin                                                 # fallback for owner/repo

Dynamic patterns

If not in a git repo, ask the user for owner/repo or pass -R owner/repo on every command.

Agent rules

1. Resolve context first — auth user and repo via commands above; never assume a fixed account
2. Check auth before PR/issue/API work: gh auth status
3. Use gh for GitHub tasks — PRs, issues, checks, releases, repo info
4. Interactive login — run gh auth login, then tell the user to complete browser/token steps
5. Never commit or log tokens — warn if .env or credentials would be committed
6. Use --json + --jq for scriptable output when parsing is needed

Pull requests

Align with the user's PR workflow: gather git state, then use gh.

Inspect branch before PR

Run in parallel when possible:

git status
git diff
git branch -vv
git log --oneline -10
git diff main...HEAD

Create PR

git push -u origin HEAD

gh pr create --title "Title" --body "$( @'
## Summary
- Change 1

## Test plan
- [ ] Step 1
'@ )"

Return the PR URL from command output.

Common PR commands

gh pr list
gh pr view 123
gh pr view --web
gh pr checkout 123
gh pr diff 123
gh pr merge 123 --squash
gh pr checks 123
gh pr review 123 --approve

Issues

gh issue list
gh issue view 42
gh issue create --title "Bug" --body "Description"
gh issue close 42

Repositories

gh repo view
gh repo view owner/repo --web
gh repo clone owner/repo
gh repo fork owner/repo --clone
gh repo create my-repo --public --source=. --remote=origin --push

GitHub Actions

Requires workflow scope for some operations.

gh run list
gh run view 123456789
gh run watch 123456789
gh run rerun 123456789 --failed
gh workflow list
gh workflow run ci.yml

Search and API

gh search repos "topic:nextjs stars:>100"
gh search prs "is:open author:@me"
gh search repos "user:$(gh api user -q .login)"
gh api "repos/$(gh repo view -q .nameWithOwner)/pulls" --jq '.[].title'

Use gh api when no dedicated subcommand exists. See gh api --help.

JSON output

gh pr list --json number,title,url --jq '.[] | "\(.number): \(.title)"'
gh issue list --json number,title,state

Troubleshooting

gh auth logout
gh auth login
gh config set editor "code --wait"

Quick reference

Full reference: gh help or cli.github.com/manual

Additional resources

• For API patterns, JSON fields, merge flags, and env vars, see reference.md