gh-reference

GitHub CLI (gh) Complete Reference

You have access to the gh CLI for all GitHub operations. This skill provides a comprehensive reference for every command, flag, and common usage pattern.

Quick Command Map

Task	Command
Create PR	gh pr create --title "..." --body "..."
List PRs	gh pr list
View PR	gh pr view <number>
Merge PR	gh pr merge <number> --squash --delete-branch
Checkout PR	gh pr checkout <number>
PR diff	gh pr diff <number>
PR checks	gh pr checks <number>
Create issue	gh issue create --title "..." --body "..."
List issues	gh issue list
View issue	gh issue view <number>
Close issue	gh issue close <number>
Create release	gh release create <tag> --generate-notes
View repo	gh repo view
Clone repo	gh repo clone <owner/repo>
Raw API call	gh api <endpoint>
Search code	gh search code <query>
Search issues	gh search issues <query>
List runs	gh run list
View run	gh run view <run-id>
Trigger workflow	gh workflow run <workflow>
List labels	gh label list
Create gist	gh gist create <file>
Set secret	gh secret set <name>
Set variable	gh variable set <name>
Auth status	gh auth status
API-Only Operations
Create/edit/delete files	gh api repos/{owner}/{repo}/contents/path -X PUT ...
Create branch	gh api repos/{owner}/{repo}/git/refs -f ref="refs/heads/name" ...
Delete branch	gh api repos/{owner}/{repo}/git/refs/heads/name -X DELETE
Create tag	gh api repos/{owner}/{repo}/git/refs -f ref="refs/tags/v1.0" ...
Add reaction	gh api repos/{owner}/{repo}/issues/123/reactions -f content="+1"
Manage milestones	gh api repos/{owner}/{repo}/milestones ...
Manage webhooks	gh api repos/{owner}/{repo}/hooks ...
Branch protection	gh api repos/{owner}/{repo}/branches/main/protection ...
Manage collaborators	gh api repos/{owner}/{repo}/collaborators/user ...
Notifications	gh api notifications ...
Compare branches	gh api repos/{owner}/{repo}/compare/main...feature
Repo statistics	gh api repos/{owner}/{repo}/stats/contributors
Deployments	gh api repos/{owner}/{repo}/deployments ...
Star/unstar repo	gh api user/starred/owner/repo -X PUT
Repository dispatch	gh api repos/{owner}/{repo}/dispatches -f event_type="..." ...
Org management	gh api orgs/{org}/members ...

Inherited Flags (Available on Most Commands)

--help                          Show help for command
-R, --repo [HOST/]OWNER/REPO   Select another repository

JSON Output (Available on list/view/status Commands)

--json <fields>       Output JSON with specified fields
-q, --jq <expr>       Filter JSON output using jq expression
-t, --template <str>  Format JSON output using Go template

Detailed References

For complete flags and parameters for each command group, see:

• pr-reference.md - Pull request commands (create, list, view, merge, checkout, diff, review, edit, close, reopen, comment, checks, status, ready, revert, lock, unlock, update-branch)
• issue-reference.md - Issue commands (create, list, view, edit, close, reopen, comment, delete, develop, lock, unlock, pin, unpin, transfer, status)
• repo-reference.md - Repository commands (create, clone, fork, view, list, edit, delete, sync, rename, archive, unarchive, deploy-key, set-default)
• advanced-reference.md - API calls, search, releases, workflow runs, Actions, secrets, variables, labels, gists, auth, and more. Also includes API-only recipes for: file operations, branch/tag management, reactions, milestones, webhooks, branch protection, collaborators, notifications, commit comments/comparisons, repo statistics, deployments, starring/watching, repository dispatch events, and organization management

Important Patterns

HEREDOC for Multi-line Bodies

Always use HEREDOC for multi-line body text to preserve formatting:

gh pr create --title "Title" --body "$(cat <<'EOF'
## Summary
- Change 1
- Change 2

## Test plan
- [ ] Test A
EOF
)"

JSON Filtering with jq

# Get PR titles
gh pr list --json title -q '.[].title'

# Get issue URLs
gh issue list --json url,number -q '.[] | "\(.number): \(.url)"'

# Get failed workflow runs
gh run list --json conclusion,name -q '.[] | select(.conclusion=="failure")'

Working with the API Directly

# GET endpoint with placeholders
gh api repos/{owner}/{repo}/pulls

# POST with fields
gh api repos/{owner}/{repo}/issues/123/comments -f body='comment text'

# GraphQL queries
gh api graphql -f query='{ viewer { login } }'

# Paginate results
gh api repos/{owner}/{repo}/issues --paginate

Cross-Repository Operations

# Any command can target a different repo with -R
gh pr list -R owner/other-repo
gh issue view 42 -R owner/other-repo

PR Review Comments via API

# View comments on a PR
gh api repos/{owner}/{repo}/pulls/123/comments

# View review comments
gh api repos/{owner}/{repo}/pulls/123/reviews