GitHub CLI (gh) Reference

Use gh CLI for all GitHub operations. Anthropic recommends gh CLI over GitHub MCP servers for Claude Code since you already have shell access.

Common Pitfalls

Invalid JSON fields cause errors

--json only accepts specific fields per command. Using invalid fields (e.g., stateReason) causes the command to fail and may cancel sibling tool calls.

Always use fields from the valid lists below. When in doubt, run gh <command> --json with no field names to see the valid list.

Non-interactive mode

gh commands that prompt for input will hang in automated contexts. Always provide all required flags explicitly:

• gh pr create needs --title and --body
• gh issue create needs --title
• gh pr merge needs a merge strategy flag (--merge, --squash, or --rebase)

Issue Commands

gh issue list

gh issue list --state open --limit 50
gh issue list --label "bug" --assignee "@me"
gh issue list --search "error sort:created-asc"
gh issue list --json number,title,state,labels

Flags: -s/--state {open|closed|all}, -l/--label, -a/--assignee, -A/--author, -m/--milestone, -S/--search, -L/--limit, --json, -R/--repo

Valid --json fields:
assignees, author, body, closed, closedAt, comments, createdAt, id, labels, milestone, number, projectCards, projectItems, reactionGroups, state, title, updatedAt, url

gh issue view

gh issue view 123
gh issue view 123 --json number,title,state,body
gh issue view 123 --comments

Valid --json fields: Same as gh issue list.

NOT valid: stateReason, closedBy, reactions, timeline

gh issue create

gh issue create --title "Bug: X" --body "Description"
gh issue create --title "Feature" --label "enhancement" --assignee "@me"

Flags: -t/--title, -b/--body, -F/--body-file, -l/--label, -a/--assignee, -m/--milestone, -p/--project

gh issue close

gh issue close 123
gh issue close 123 --reason "completed"
gh issue close 123 --comment "Fixed in PR #456"

Flags: -r/--reason {completed|not planned}, -c/--comment

gh issue edit

gh issue edit 123 --title "New title"
gh issue edit 123 --add-label "bug" --remove-label "triage"
gh issue edit 123 --add-assignee "@me"

Pull Request Commands

gh pr list

gh pr list --state open
gh pr list --json number,title,state,headRefName
gh pr list --head feature/pan-123

Flags: -s/--state {open|closed|merged|all}, -B/--base, -H/--head, -l/--label, -a/--assignee, -A/--author, -S/--search, -L/--limit, --json

Valid --json fields:
additions, assignees, author, autoMergeRequest, baseRefName, body, changedFiles, closed, closedAt, comments, commits, createdAt, deletions, files, headRefName, headRefOid, headRepository, headRepositoryOwner, id, isCrossRepository, isDraft, labels, latestReviews, maintainerCanModify, mergeCommit, mergeStateStatus, mergeable, mergedAt, mergedBy, milestone, number, potentialMergeCommit, projectCards, projectItems, reactionGroups, reviewDecision, reviewRequests, reviews, state, statusCheckRollup, title, updatedAt, url

gh pr view

gh pr view 456
gh pr view 456 --json number,title,state,mergeStateStatus,reviews

Valid --json fields: Same as gh pr list.

gh pr create

gh pr create --title "feat: Add X" --body "## Summary\n- Added X\n\n## Test plan\n- [ ] Test Y"
gh pr create --title "fix: Bug" --body "Fixes #123" --label "bug"
gh pr create --fill  # auto-fill from commit messages

Flags: -t/--title, -b/--body, -F/--body-file, -B/--base, -H/--head, -l/--label, -r/--reviewer, -a/--assignee, -m/--milestone, -d/--draft, -f/--fill

Use HEREDOC for multi-line body:

gh pr create --title "feat: X" --body "$(cat <<'EOF'
## Summary
- Change 1

## Test plan
- [ ] Verify X
EOF
)"

gh pr merge

gh pr merge 456 --squash --delete-branch
gh pr merge 456 --merge
gh pr merge 456 --rebase

Flags: -m/--merge, -s/--squash, -r/--rebase, -d/--delete-branch, --auto, -b/--body, -t/--subject

Must specify one of: --merge, --squash, or --rebase

gh pr close

gh pr close 456
gh pr close 456 --delete-branch

gh pr checkout

gh pr checkout 456

API Commands

gh api

For operations not covered by gh issue or gh pr, use the REST API directly:

# Get PR comments
gh api repos/{owner}/{repo}/pulls/123/comments

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

# Get issue timeline events
gh api repos/{owner}/{repo}/issues/123/timeline

# Add a comment
gh api repos/{owner}/{repo}/issues/123/comments -f body="Comment text"

# Get repo info
gh api repos/{owner}/{repo}

{owner} and {repo} are auto-filled from the current repo context.

Flags: -X/--method {GET|POST|PUT|PATCH|DELETE}, -f/--raw-field key=value, -F/--field key=value, --paginate, -q/--jq

Filtering with jq

gh issue list --json number,title,labels --jq '.[] | select(.labels[].name == "bug")'
gh pr list --json number,title,headRefName --jq '.[] | select(.headRefName | startswith("feature/"))'

Repo-Scoped Operations

When not in a git repo or targeting a different repo, use -R:

gh issue list -R eltmon/overdeck
gh pr view 456 -R eltmon/overdeck