GitHub gh CLI

Overview

Use gh for GitHub operations with explicit repo targeting, JSON output, and command help-driven discovery of flags/fields. Avoid scraping human-readable output and avoid raw REST calls unless you must (use gh api as the controlled fallback).

Quick start

1. Verify gh is installed and authenticated:

gh --version
gh auth status

2. Set explicit repo context (preferred patterns):

# One-off: target a repo explicitly
gh issue list -R OWNER/REPO --json number,title,url -q '.[] | "\(.number)\t\(.title)\t\(.url)"'

# Repeated work: set a default repo for this shell + directory context
gh repo set-default OWNER/REPO

Operating rules (do not skip)

1. Prefer first-class commands over APIs.

   • Use gh issue, gh pr, gh repo, gh run, gh workflow, gh release, etc.
   • Use gh api only when the CLI lacks a dedicated command (document the endpoint and why).

2. Avoid guessing flags/fields; discover them.

   • Use gh <command> --help to find flags and supported --json fields.
   • Use gh help formatting for --json, --jq, and --template patterns.

3. Prefer machine-readable output.

   • Use --json <fields> -q '<jq>' instead of parsing table output.
   • When you need just one value, return only that value (not the full blob).

4. Make repo targeting explicit.

   • Prefer -R OWNER/REPO when not operating in a known local checkout.
   • If you infer repo from the current directory, confirm it via gh repo view --json nameWithOwner -q .nameWithOwner.

5. Treat state changes as production-impacting.

   • Ask for confirmation before creating/closing/merging/deleting.
   • When modifying settings (branch protections, permissions), make changes small and reversible.

Common tasks (command-first)

Use skills/gh-cli/references/gh-commands.md for a categorized command reference with examples for:

• Repos (view/clone/fork/create, defaults, settings)
• Issues (list/view/create/edit/comment/close/reopen)
• PRs (list/view/create/checkout/review/merge/status/checks, review threads/comments, reply workflows)
• Actions (workflows/runs: list/view/watch/rerun/cancel)
• Releases (list/view/create/download)
• Search patterns and deterministic selection
• gh api fallback patterns (REST + GraphQL) when required

Tooling

Run a quick environment/context capture when debugging auth/repo targeting problems:

./skills/gh-cli/scripts/gh_context.sh

This prints gh version/auth status and tries to identify the active repo (when run inside a checkout).

Fetch a PR’s review feedback (reviews + PR comments + inline review comments + review threads) as JSON:

./skills/gh-cli/scripts/pr_feedback.sh -R OWNER/REPO 123

Reply back to review feedback:

# Reply to an inline review comment (REST)
./skills/gh-cli/scripts/pr_review_comment_reply.sh -R OWNER/REPO 123 987654321 --body "Thanks — fixed in 8c0ffee."

# Reply to a review thread (GraphQL)
./skills/gh-cli/scripts/pr_review_thread_reply.sh PRRT_kwDO... --body "Good catch — updated to handle nil."