gh-cli

GitHub CLI (gh)

Index for working with GitHub from the command line via gh. This file is a thin guide — the bulk of the command flags/examples live in references/<topic>.md. Read the relevant references/ file when you need detail for that topic.

Version: 2.85.0 (current as of January 2026)

When to use

Reach for gh whenever the task is a GitHub operation from the terminal: opening/viewing/merging PRs, filing or triaging issues, inspecting CI runs, cutting releases, managing repos/labels/secrets, or hitting the REST/GraphQL API. Prefer dedicated gh <noun> <verb> commands over raw gh api when one exists.

Decision tree

• Working with a PR? → see common workflows below, then references/pr.md.
• Filing/triaging an issue? → common workflows below, then references/issue.md.
• Logging in, tokens, scopes, config, SSH/GPG keys? → references/auth.md.
• Creating/cloning/forking/editing repos, labels, rulesets, orgs, browse? → references/repo.md.
• CI: runs, workflows, caches, secrets, variables? → references/actions.md.
• Posting a structured PR review with inline comments + suggestions? → references/pr.md (the gh api .../reviews section) and the orc-inline-review skill.

Common orc workflows (inline)

PR: create / view / diff / checkout

# Create a PR (interactive, or with title/body/base/draft)
gh pr create --title "Feature: X" --body "..." --base main
gh pr create --draft
gh pr create --body-file .github/PULL_REQUEST_TEMPLATE.md

# View a PR (add --comments / --web; --json for fields)
gh pr view 123
gh pr view 123 --json title,body,state,author,commits,files

# Diff a PR
gh pr diff 123
gh pr diff 123 --name-only
gh pr diff 123 > pr-123.patch

# Check out a PR branch locally
gh pr checkout 123

# Checks, merge, ready
gh pr checks 123 --watch
gh pr merge 123 --squash --delete-branch
gh pr ready 123

→ Full flags, edit/comment/review/lock/revert/status, and the inline-review API: references/pr.md.

Issue ops

# Create / list / view
gh issue create --title "Bug: ..." --body "..." --labels bug
gh issue list --state open --assignee @me --labels bug
gh issue view 123 --comments

# Edit / comment / close / reopen
gh issue edit 123 --add-label high-priority --add-assignee user1
gh issue comment 123 --body "Fixed in #456"
gh issue close 123 --comment "Done"
gh issue reopen 123

# Spin a branch/draft-PR off an issue
gh issue develop 123 --branch feature/issue-123

→ Full flags, status/pin/lock/transfer/delete, and bulk operations: references/issue.md.

Topic index

Read the matching file on demand for full flags and examples.

Topic	File	Covers
Auth & config	references/auth.md	Install, gh auth (login/status/switch/token/refresh/setup-git), gh config, env vars, SSH/GPG keys, git integration
Repositories	references/repo.md	gh repo (create/clone/list/view/edit/delete/fork/sync/set-default/autolink/deploy-key/gitignore/license), gh browse, gh label, gh ruleset, gh org, repo-setup & fork-sync workflows
Issues	references/issue.md	gh issue (create/list/view/edit/close/comment/status/pin/lock/transfer/delete/develop), create-PR-from-issue, bulk ops
Pull requests	references/pr.md	gh pr (create/list/view/checkout/diff/merge/close/reopen/edit/ready/checks/comment/review/update-branch/lock/revert/status) + inline-review REST API (POST .../reviews, suggestion blocks)
GitHub Actions	references/actions.md	gh run, gh workflow, gh cache, gh secret, gh variable, CI/CD workflow
Releases	references/release.md	gh release (create/list/view/upload/download/edit/delete/verify), gh attestation
Gists	references/gist.md	gh gist (list/view/create/edit/delete/rename/clone)
Projects	references/project.md	gh project (list/view/create/edit/delete/copy/fields/items/link)
Codespaces	references/codespace.md	gh codespace (list/create/view/ssh/code/stop/delete/logs/ports/rebuild/edit/jupyter/cp)
API, search & extensions	references/api-and-extensions.md	gh api (REST + GraphQL), gh search, gh extension, gh alias, gh status, gh completion, gh preview, gh agent-task, global flags, JSON/template output, best practices, full CLI command tree, external docs

Quick global reference

• --repo OWNER/REPO targets another repo; --json FIELDS --jq EXPR for machine output; --web opens in browser; --paginate for large result sets.
• Set a default repo once: gh repo set-default owner/repo.
• For automation, export a token: export GH_TOKEN=$(gh auth token).
• See references/api-and-extensions.md for the full global-flags table and the complete gh command tree.