| name | github-cli |
| description | Operate GitHub from terminal with `gh` for repositories, pull requests, issues, releases, actions, and API calls. Use for any GitHub task. For template-compliant PR or issue creation, load reference workflows under references/. |
GitHub CLI
Execution Policy
For GitHub tasks, use gh as the primary interface.
Rules:
- Always run
gh commands before falling back to raw APIs.
- Use
gh api instead of curl for GitHub REST/GraphQL.
- Do not hardcode tokens in commands or scripts.
- Confirm destructive operations (merge/close/delete/release delete).
Preflight
- Verify CLI and auth:
gh --version
gh auth status
- Resolve repository context:
- In repo: use current remote context.
- Outside repo: require
-R owner/repo.
- Prefer machine-readable output when summarizing:
Conditional References
Load detailed flows only when needed:
- PR creation with template compliance:
- read
references/create-pr.md
- Issue creation with template compliance:
- read
references/create-issue.md
Keep this file focused on common gh operations and routing.
High-Value Commands
gh repo view
gh repo clone owner/repo
gh repo create my-repo --public --description "My new repo"
gh repo fork owner/repo
gh repo list owner --limit 20
gh browse
gh pr list
gh pr list --state all
gh pr view 42
gh pr view 42 --json title,state,body,reviews
gh pr diff 42
gh pr checkout 42
gh pr review 42 --approve
gh pr merge 42 --squash
gh pr merge 42 --squash --delete-branch
gh pr close 42
gh issue list
gh issue view 123
gh issue view 123 --json title,state,body,comments
gh issue close 123
gh issue reopen 123
gh issue comment 123 --body "I can reproduce this"
gh search code "functionName" --repo owner/repo
gh search issues "memory leak" --repo owner/repo
gh search prs "fix auth" --state merged --author username
gh release list
gh release view v1.2.3
gh release create v1.2.3 --title "Release v1.2.3" --notes "Changelog..."
gh release create v1.2.3 --generate-notes
gh release upload v1.2.3 ./dist/app.zip
gh release delete v1.2.3 --yes
gh workflow list
gh workflow view "CI"
gh workflow run "CI" --ref main
gh run list
gh run view 12345
gh run watch 12345
gh run view 12345 --log
gh run rerun 12345
gh run cancel 12345
Common Workflows
Review and merge a PR
- Inspect:
gh pr view <number> --json title,author,mergeStateStatus,url
gh pr diff <number>
- Approve/comment:
gh pr review <number> --approve
- Merge (confirm strategy with user if not specified):
gh pr merge <number> --squash --delete-branch
Investigate an issue
- Read issue:
gh issue view <number> --json title,body,labels,assignees,url
- Search related PR/code:
gh search prs "<keyword>" --repo owner/repo --state all
gh search code "<keyword>" --repo owner/repo
Monitor CI
gh run list --limit 10
gh run watch <run-id>
gh run view <run-id> --log-failed
Troubleshooting
gh: command not found -> install gh.
not logged in -> gh auth login.
- Wrong repo context -> use
-R owner/repo.
- Missing scopes ->
gh auth refresh -s <scope>.