gh-cli

name	gh-cli
description	Manage GitHub Issues and Pull Request review threads from the command line using the gh CLI. Use when the user asks about GitHub issues, labels, milestones, PR review comments, resolving review threads, or needs to manage project work items via the command line.

GitHub Issues & PR Review CLI

Interact with GitHub Issues from the command line using gh.

When to Use

• User asks to create, view, edit, or search GitHub Issues
• User needs to manage labels, milestones, or assignees
• User wants to close, reopen, or comment on issues
• User needs to resolve or reply to PR review comments/threads
• User needs to submit a PR review (approve, request changes, comment)
• MCP tools (mcp_github_*) are unavailable or failing
• User needs scripted/batch issue operations

Prerequisites

1. Install gh CLI: brew install gh (macOS) or see install instructions
2. Authenticate: gh auth login
3. Verify: gh auth status

Issue Commands

List Issues

# List open issues
gh issue list

# List issues with filters
gh issue list --state open --label "bug"
gh issue list --assignee @me
gh issue list --milestone "v1.0"

# List with search query
gh issue list --search "is:open label:epic sort:created-desc"

# Limit results
gh issue list --limit 20

# JSON output for scripting
gh issue list --json number,title,state,labels --limit 50

Create Issues

# Interactive creation
gh issue create

# Create with all options
gh issue create --title "Bug: Login fails" --body "Description here" --label "bug" --assignee @me

# Create with milestone
gh issue create --title "Add feature" --body "Details" --label "enhancement" --milestone "v1.0"

# Create with body from file
gh issue create --title "Feature request" --body-file ./description.md

# Create and assign to multiple people
gh issue create --title "Review needed" --assignee user1,user2

View Issues

# View issue details
gh issue view 123

# View in terminal (no browser)
gh issue view 123 --comments

# JSON output
gh issue view 123 --json title,body,state,labels,assignees,milestone

# Open in browser
gh issue view 123 --web

Edit Issues

# Edit title
gh issue edit 123 --title "Updated title"

# Add labels
gh issue edit 123 --add-label "priority:high,needs-review"

# Remove labels
gh issue edit 123 --remove-label "needs-triage"

# Set milestone
gh issue edit 123 --milestone "v1.0"

# Add assignees
gh issue edit 123 --add-assignee @me,teammate

# Remove assignees
gh issue edit 123 --remove-assignee old-owner

Close & Reopen Issues

# Close issue
gh issue close 123

# Close with comment
gh issue close 123 --comment "Fixed in PR #456"

# Close as not planned
gh issue close 123 --reason "not planned"

# Reopen issue
gh issue reopen 123

# Reopen with comment
gh issue reopen 123 --comment "Reopening — needs more work"

Comments

# Add comment
gh issue comment 123 --body "Working on this"

# Add comment from file
gh issue comment 123 --body-file ./comment.md

# Edit last comment (interactive)
gh issue comment 123 --edit-last

Pin & Lock Issues

# Pin issue
gh issue pin 123

# Unpin issue
gh issue unpin 123

# Lock issue
gh issue lock 123 --reason "resolved"

# Unlock issue
gh issue unlock 123

Search

# Search issues across repo
gh search issues "authentication bug" --repo owner/repo

# Search with qualifiers
gh search issues "label:bug state:open" --repo owner/repo --limit 20

# Search issues assigned to me
gh issue list --search "assignee:@me is:open"

Labels

# List labels
gh label list

# Create label
gh label create "priority:high" --color FF0000 --description "High priority"

# Edit label
gh label edit "priority:high" --new-name "priority:critical" --color CC0000

# Delete label
gh label delete "old-label" --yes

Milestones

# List milestones
gh api repos/{{REPO_OWNER}}/{{PROJECT_NAME}}/milestones --jq '.[].title'

# Create milestone
gh api repos/{{REPO_OWNER}}/{{PROJECT_NAME}}/milestones -f title="v1.0" -f description="First release" -f due_on="2025-06-01T00:00:00Z"

Common Workflows

Triage New Issues

# List untriaged issues
gh issue list --search "is:open no:label no:assignee sort:created-asc"

# Assign and label
gh issue edit 123 --add-label "bug,priority:high" --add-assignee @me

Epic Pattern (using labels)

# List epics
gh issue list --label "epic" --state open

# Create epic
cat > /tmp/epic-body.md <<'EOF'
## Scope
- Login
- Registration
- Password reset
EOF
gh issue create --title "Epic: User Authentication" --label "epic" --body-file /tmp/epic-body.md

# Find stories for an epic (by reference in body)
gh issue list --search "is:open label:story \"Authentication\""

Close with PR Reference

# Close and reference the fixing PR
gh issue close 123 --comment "Fixed in #456"

Batch Operations

# Close multiple issues
for id in 10 11 12; do gh issue close "$id" --comment "Superseded by #20"; done

# Add label to multiple issues
for id in 10 11 12; do gh issue edit "$id" --add-label "backlog"; done

Common Flags

Flag	Description
--json	JSON output with field selection
--jq	Filter JSON output with jq expressions
--web	Open in browser
--limit	Max results to return
--search	Search query with GitHub qualifiers
--state	Filter by state (open, closed, all)
--label	Filter by label
--assignee	Filter by assignee
--milestone	Filter by milestone

Output Formatting

Command	Use Case
gh issue list --json number,title	JSON for scripting
gh issue list --json number,title --jq '.[].title'	Extract specific fields
gh issue view 123 --json body --jq '.body'	Get issue body only

Pull Request Review Threads

Manage PR review comments and resolve threads.

List Review Threads

# List ALL unresolved review threads — paginate through every page.
cursor=""
while :; do
  after=$([ -z "$cursor" ] && echo "" || echo ", after: \"$cursor\"")
  resp=$(gh api graphql -f query="{
    repository(owner: \"OWNER\", name: \"REPO\") {
      pullRequest(number: 123) {
        reviewThreads(first: 100$after) {
          pageInfo { hasNextPage endCursor }
          nodes {
            id
            isResolved
            comments(first: 1) {
              nodes { databaseId body path line }
            }
          }
        }
      }
    }
  }")
  # Emit unresolved threads from this page: <threadId> <commentDatabaseId> <file>
  echo "$resp" | jq -r '.data.repository.pullRequest.reviewThreads.nodes[]
    | select(.isResolved == false)
    | "\(.id)\t\(.comments.nodes[0].databaseId)\t\(.comments.nodes[0].path)"'
  has_next=$(echo "$resp" | jq -r '.data.repository.pullRequest.reviewThreads.pageInfo.hasNextPage')
  cursor=$(echo "$resp" | jq -r '.data.repository.pullRequest.reviewThreads.pageInfo.endCursor')
  [ "$has_next" = true ] || break
done

Reply to a Review Comment

# Reply to a specific comment thread (REST API — requires integer databaseId, not GraphQL node ID)
gh api repos/OWNER/REPO/pulls/PR_NUMBER/comments/COMMENT_DATABASE_ID/replies -X POST -f body="Fixed in commit abc123."

Resolve a Review Thread

Threads are resolved via the GraphQL API. You need the thread node ID (starts with PRRT_).

# Resolve a single thread
gh api graphql -f query='
mutation {
  resolveReviewThread(input: {threadId: "PRRT_kwDOQlyQTc6IWPxG"}) {
    thread { id isResolved }
  }
}'

# Resolve multiple threads
for thread_id in PRRT_xxx PRRT_yyy PRRT_zzz; do
  gh api graphql -f query="mutation { resolveReviewThread(input: {threadId: \"$thread_id\"}) { thread { id isResolved } } }"
done

Unresolve a Review Thread

gh api graphql -f query='
mutation {
  unresolveReviewThread(input: {threadId: "PRRT_kwDOQlyQTc6IWPxG"}) {
    thread { id isResolved }
  }
}'

Submit a PR Review

# Comment review (no approval/request changes)
gh api repos/OWNER/REPO/pulls/123/reviews -X POST \
  -f body="All comments addressed in commit abc123." \
  -f event="COMMENT"

# Approve
gh api repos/OWNER/REPO/pulls/123/reviews -X POST \
  -f body="LGTM" \
  -f event="APPROVE"

# Request changes
gh api repos/OWNER/REPO/pulls/123/reviews -X POST \
  -f body="Needs fixes" \
  -f event="REQUEST_CHANGES"

Full Workflow: Fix Comments and Resolve Threads

# 1. List unresolved threads (paginate through all pages — see "List Review Threads" above).
#    Capture each thread's id (for resolveReviewThread) and comments[0].databaseId (for REST replies).

# 2. Make fixes, commit, push
git add -A && git commit -m "fix: address review comments" && git push

# 3. Reply to each comment (REST — needs integer databaseId from step 1)
gh api repos/OWNER/REPO/pulls/PR_NUMBER/comments/COMMENT_DATABASE_ID/replies -X POST -f body="Fixed in commit abc123."

# 4. Resolve each thread
gh api graphql -f query='mutation { resolveReviewThread(input: {threadId: "THREAD_ID"}) { thread { id isResolved } } }'

# 5. Post review confirming all addressed
gh api repos/OWNER/REPO/pulls/123/reviews -X POST \
  -f body="All review comments addressed." \
  -f event="COMMENT"

Troubleshooting

Permission Errors (FORBIDDEN)

Symptom: <GITHUB_USERNAME> does not have the correct permissions to execute ResolveReviewThread

Cause: Multiple GitHub accounts configured; the active account lacks write access.

Diagnosis:

# Check which accounts are configured
gh auth status

# Check which account is active (Active account: true)
gh auth status 2>&1 | grep -A2 "Active account: true"

Fix — switch to the correct account:

# Switch active account
gh auth switch

# Or set the active account explicitly
gh auth switch -u <GITHUB_USERNAME>

# Verify the switch
gh auth status

Fix — if the active account genuinely lacks permissions:

# Check repo access
gh api repos/OWNER/REPO --jq '.permissions'

# Required scopes for thread resolution: repo, read:org
gh auth refresh -s repo,read:org

Prevention: Always verify gh auth status shows the correct active account before batch operations. The resolveReviewThread GraphQL mutation requires write access to the repository.

Thread Resolution Fails Silently

Symptom: resolveReviewThread returns {"data":{"resolveReviewThread":null}} with no error.

Cause: Thread ID is invalid or already resolved.

Fix:

# Re-list threads to confirm IDs
gh api graphql -f query='...' --jq '.data.repository.pullRequest.reviewThreads.nodes[] | {id, isResolved}'

# Thread IDs start with PRRT_ — verify format
echo "$THREAD_ID" | grep -q "^PRRT_" || echo "Invalid thread ID format"

Rate Limiting on Batch Operations

Symptom: 403 rate limit exceeded or 429 errors during bulk thread resolution.

Fix:

# Check remaining rate limit
gh api rate_limit --jq '.rate.remaining'

# Add delays between batch operations
# ponytail: array literal, pipe from prior query if list is dynamic
for thread_id in PRRT_xxx PRRT_yyy PRRT_zzz; do
  gh api graphql -f query="mutation { resolveReviewThread(input: {threadId: \"$thread_id\"}) { thread { id isResolved } } }"
  sleep 0.5  # 500ms between calls
done

Limitations

• Requires gh auth login before first use
• GitHub Projects (v2) require separate gh project commands
• Rate limits: 5000 requests/hour for authenticated users
• Sub-issues require GitHub's sub-issues feature (beta)
• Epic patterns rely on label conventions, not native epics
• PR thread resolution requires the GraphQL API (REST does not support it)
• Thread node IDs start with PRRT_ (GraphQL), comment node IDs start with PRRC_ (GraphQL); REST endpoints use integer databaseId