---

name: github-cli description: "GitHub CLI (gh) patterns for PRs, workflow runs, repos, and raw API calls. Read this first before using gh"

Skill: github-cli

GitHub CLI (gh) reference. Plain git + gh is the default workflow.

---

GitHub CLI (gh)

Pull Requests

View

gh pr list [--author @me] [--state open|closed|merged]
gh pr view <num> [--comments]
gh pr view <num> --json number,title,state,body,mergeable,reviews,statusCheckRollup
gh pr diff <num>
gh pr checks <num> [--watch]

Review

gh pr review <num> --approve [--body "..."]
gh pr review <num> --request-changes --body "..."
gh pr comment <num> --body "..."
gh api repos/{owner}/{repo}/pulls/<num>/comments  # view inline comments

Inline review comments

Use the PR head SHA, not a branch name or stale commit. An inline comment can only target a line that is present in the PR diff; unchanged context lines cannot be resolved by the API.

head_sha="$(gh pr view <num> -R owner/repo --json headRefOid --jq .headRefOid)"

gh api repos/owner/repo/pulls/<num>/comments -X POST \
  -f commit_id="$head_sha" \
  -f path=path/to/file.kt \
  -F line=123 \
  -f side=RIGHT \
  -f body="Review comment"

• Use -F for numeric fields such as line; -f line=123 sends a string and is rejected.
• Use side=RIGHT for added or modified lines and side=LEFT for deleted lines.
• First confirm the target line is part of the current PR diff. Do not guess a line number from the complete file.
• If the finding applies to unchanged context or the API cannot resolve the line, post a file-level comment instead. Do not retry with a fabricated position.

gh api repos/owner/repo/pulls/<num>/comments -X POST \
  -f commit_id="$head_sha" \
  -f path=path/to/file.kt \
  -f subject_type=file \
  -f body="Review comment"

Edit

gh pr edit <num> --add-reviewer user --add-label label
gh pr ready <num>  # draft → ready for review

Merge (non-stacked PRs only)

gh pr merge <num> --squash --delete-branch
gh pr merge <num> --auto --squash  # auto-merge when checks pass

Always confirm with the user before merging.

Workflow Runs / CI

# List runs
gh run list [--workflow ci.yml] [--branch main] [--status failure]
gh run list --json status,conclusion,headBranch,workflowName

# View run details
gh run view <run-id> [--verbose]

# Debug failures
gh run view <run-id> --log-failed

# Re-run
gh run rerun <run-id> --failed  # only re-run failed jobs

# Watch in real-time
gh run watch <run-id> --exit-status

# Trigger manually
gh workflow run <workflow.yml> --ref <branch> [-f key=value]

Repos

gh repo view [owner/repo] [--json name,description,defaultBranchRef]
gh repo create duneanalytics/<name> --private [--clone]
gh auth status  # verify authentication

Raw API Access

# Auto-resolves :owner/:repo from current repo context
gh api repos/:owner/:repo/<endpoint> [--jq 'filter']

# Pagination
gh api repos/:owner/:repo/pulls --paginate --jq '.[].number'

# POST/PATCH
gh api repos/:owner/:repo/<endpoint> -X POST -f key=value

Best Practices

• Always use --json for structured output -- don't parse human-readable tables
• Use -R owner/repo when not inside a repo directory
• Use HEREDOC for multi-line bodies: --body "$(cat <<'EOF' ... EOF)"
• Use --exit-status when chaining commands that need to fail on error
• Confirm before destructive operations (merge, delete, cancel)