gh-cli

name	gh-cli
description	GitHub CLI (gh) command reference. Use when working with GitHub repositories, PRs, issues, actions, `gh api`, or any GitHub operations from the command line.

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:

1. Inspect the PR diff and understand the changes
2. 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\n```suggestion\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:

```suggestion
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"