GitHub CLI Quick Reference
The gh CLI is GitHub's official command-line tool. This is a quick reference for common workflows—for comprehensive docs, see https://cli.github.com/manual
Getting Help
gh --help # List all commands gh <command> --help # Help for specific command gh auth status # Check authentication
Discovery Patterns
gh <command> --web # Open in browser gh <command> --json FIELDS # JSON output for scripting gh <command> <subcommand> -h # Quick help for any command gh <command> list --limit N # Limit results to avoid large output (default: 20-30)
Use tab completion to explore available commands and flags.
Important: Always use --limit when querying lists to avoid overwhelming output, especially with pr list , issue list , run list , etc.
Common Workflows
PR Workflow
Create PR
gh pr create --fill # Use commit messages for title/body gh pr create --web # Open browser to create PR
View and checkout
gh pr list # List PRs gh pr view [NUMBER] # View PR details gh pr checkout NUMBER # Checkout PR locally
Review (simple, no line comments)
gh pr review NUMBER --approve gh pr review NUMBER --comment -b "feedback" gh pr review NUMBER --request-changes -b "needs work"
Merge
gh pr merge --squash --delete-branch
Review Workflow
When reviewing a PR, follow this process:
-
Inspect the PR diff and understand the changes
-
Submit the review with line-level comments and an overall summary
Always ask the user whether to submit the review as "approve", "request changes", or "comment" (default to "comment").
Step 1: Inspect the PR
Find PRs needing your review
gh pr list --search "review-requested:@me"
View PR details and diff
gh pr view NUMBER gh pr diff NUMBER
Step 2: Submit the review with line-level comments
Use gh api to submit a review with inline comments and an overall summary in a single call. Set event to COMMENT , APPROVE , or REQUEST_CHANGES .
gh api repos/{owner}/{repo}/pulls/NUMBER/reviews
--input - <<'EOF'
{
"commit_id": "LATEST_COMMIT_SHA",
"event": "COMMENT",
"body": "Overall: solid changes with a few suggestions.",
"comments": [
{
"path": "src/example.go",
"line": 42,
"side": "RIGHT",
"body": "This variable is unused."
},
{
"path": "src/example.go",
"line": 55,
"side": "RIGHT",
"body": "Consider using a constant here:\n\nsuggestion\nconst maxRetries = 3\n"
}
]
}
EOF
Comment field reference:
Field Description
path
Relative file path in the repo
line
Line number in the file (for single-line comments)
side
RIGHT (additions) or LEFT (deletions)
start_line
Starting line (for multi-line comments)
start_side
Starting side (for multi-line comments)
body
Comment text (supports markdown and code suggestions)
Code suggestions use GitHub's suggestion syntax inside the body:
replacement code here
CI/CD Debugging
Check recent runs
gh run list --limit 5 gh run list --status failure
View logs
gh run view RUN_ID --log-failed
Rerun after fix
gh run rerun RUN_ID --failed
Issue Triage
gh issue list gh issue list --assignee @me gh issue create --title "Title" --body "Description" gh issue view NUMBER gh issue comment NUMBER -b "Comment" gh issue close NUMBER
Core Commands Quick Reference
Pull Requests
gh pr list [--state open|closed|merged] [--author @me] gh pr create [--draft] [--title "..."] [--body "..."] gh pr view [NUMBER] [--web] gh pr checkout NUMBER gh pr diff [NUMBER] gh pr merge [NUMBER] [--squash|--merge|--rebase]
Issues
gh issue list [--assignee @me] [--label "bug"] gh issue create [--title "..."] [--body "..."] gh issue view NUMBER [--web] gh issue close NUMBER
Workflows & Runs
gh run list [--workflow "CI"] [--status failure] gh run view RUN_ID [--log] [--log-failed] gh run watch RUN_ID gh workflow run WORKFLOW_FILE [--ref branch]
Repositories
gh repo clone OWNER/REPO gh repo view [--web] gh repo fork OWNER/REPO gh repo create NAME [--public|--private]
Power User Tips
JSON Output
Get structured data
gh pr list --json number,title,author
Filter with jq
gh pr list --json number,title | jq '.[] | select(.number > 100)'
API Access
Direct API calls
gh api repos/OWNER/REPO gh api repos/OWNER/REPO/pulls -f title="PR Title" -f head=branch -f base=main
GraphQL
gh api graphql -f query='{ viewer { login } }'
Aliases
gh alias set pv 'pr view' gh alias set co 'pr checkout' gh alias list
Environment Variables
-
GH_TOKEN : Authentication token
-
GH_REPO : Default repository (OWNER/REPO format)
-
GH_EDITOR : Preferred editor for interactive commands
-
GH_PAGER : Pager for output (e.g., less )
Finding Your Work
gh pr list --author @me gh issue list --assignee @me gh search prs "author:username is:open" gh search issues "assignee:username is:open"