github · diff
git:20260308.ae0a2f8 to v1.0
350 added, 21 removed. Audit A to A.
---
name: github
- description: Interact with GitHub via the gh CLI. Use when the user asks about issues, pull requests, releases, repos, gists, workflows, search, or any GitHub operation.
- compatibility: Requires gh (GitHub CLI)
+ description: >-
+ GitHub CLI (gh) for repository management, issues, pull requests, releases,
+ workflows, search, gists, and API access. Use when the user asks about any
+ GitHub operation — creating repos, forking, cloning, PR workflows, issue
+ triage, CI/CD runs, code search, release management, or direct API calls.
+ Keywords: github, gh, pull request, issue, repository, release, workflow,
+ actions, search, gist, fork, clone, label, milestone, project.
+ license: MIT
+ compatibility: Requires gh (GitHub CLI) v2.0+. Install via brew install gh (macOS), winget install GitHub.cli (Windows), or apt install gh (Linux).
+ metadata:
+ author: zeph
+ version: "1.0"
---
# GitHub CLI Operations
- IMPORTANT: Always use `gh` CLI for ALL GitHub interactions. Never use `curl` with GitHub API directly — `gh api` handles authentication, pagination, and rate limiting automatically.
+ IMPORTANT: Always use `gh` CLI for ALL GitHub interactions. Never use `curl` with GitHub API
+ directly — `gh api` handles authentication, pagination, and rate limiting automatically.
- ## Quick reference
+ ## Quick Reference
- | Operation | Quick command | Details |
+ | Category | Command | Details |
|---|---|---|
- | Auth | `gh auth status` | — |
+ | Auth | `gh auth status` | Check login state |
+ | Auth | `gh auth login` | Interactive login |
+ | Repos | `gh repo view` | View current repo |
+ | Repos | `gh repo create NAME` | Create new repo |
+ | Repos | `gh repo clone OWNER/REPO` | Clone a repo |
+ | Repos | `gh repo fork OWNER/REPO` | Fork a repo |
| Issues | `gh issue list --limit 10` | [references/issues.md](references/issues.md) |
- | Pull Requests | `gh pr list --limit 10` | [references/pull-requests.md](references/pull-requests.md) |
- | Search | `gh search repos "QUERY" --limit 10` | [references/search.md](references/search.md) |
- | Repositories | `gh repo view` | [references/repos.md](references/repos.md) |
+ | Issues | `gh issue create --title T --body B` | Create issue |
+ | PRs | `gh pr list --limit 10` | [references/pull-requests.md](references/pull-requests.md) |
+ | PRs | `gh pr create --title T --body B` | Create PR |
+ | PRs | `gh pr merge N` | Merge PR |
+ | Search | `gh search repos "QUERY"` | [references/search.md](references/search.md) |
| Releases | `gh release list --limit 5` | [references/releases.md](references/releases.md) |
| Workflows | `gh run list --limit 10` | [references/workflows.md](references/workflows.md) |
| API | `gh api repos/OWNER/REPO` | [references/api.md](references/api.md) |
| Gists | `gh gist list --limit 10` | [references/gists.md](references/gists.md) |
+ | Labels | `gh label list` | List repo labels |
| Install | `brew install gh` | [references/install.md](references/install.md) |
- ## Search
+ ## Authentication
- Never use `curl` or browser for GitHub search. Use `gh search` subcommands:
+ ```bash
+ # Interactive login (browser or token)
+ gh auth login
- - `gh search repos` — repositories by name, language, stars, topic
- - `gh search code` — code across GitHub by content, filename, path, extension
- - `gh search issues` — issues by state, label, assignee, date
- - `gh search prs` — pull requests by state, author, review status
- - `gh search commits` — commits by message, author, date
+ # Login with token (non-interactive, CI)
+ echo "$TOKEN" | gh auth login --with-token
- Queries combine free-text keywords with qualifiers inside the quoted string:
+ # Check auth status
+ gh auth status
+ # Switch between accounts
+ gh auth switch
+
+ # Refresh token scopes
+ gh auth refresh --scopes read:project
+
+ # Logout
+ gh auth logout
+ ```
+
+ Environment variable auth (overrides stored credentials):
+
+ | Variable | Purpose |
+ |---|---|
+ | `GH_TOKEN` / `GITHUB_TOKEN` | Auth token for github.com |
+ | `GH_ENTERPRISE_TOKEN` | Auth token for GitHub Enterprise |
+
+ ## Repository Workflows
+
```bash
+ # Create a new repo (interactive)
+ gh repo create my-project --public --clone
+
+ # Create from template
+ gh repo create my-project --template OWNER/TEMPLATE --clone --public
+
+ # Fork and clone
+ gh repo fork OWNER/REPO --clone
+
+ # Clone
+ gh repo clone OWNER/REPO
+
+ # View repo details
+ gh repo view OWNER/REPO
+ gh repo view OWNER/REPO --json name,description,stargazerCount
+
+ # Archive / delete
+ gh repo archive OWNER/REPO
+ gh repo delete OWNER/REPO --yes
+
+ # Set default repo (for commands outside a git directory)
+ gh repo set-default OWNER/REPO
+
+ # Rename
+ gh repo rename NEW-NAME
+ ```
+
+ ## Pull Request Workflow
+
+ ```bash
+ # Create PR (current branch -> default branch)
+ gh pr create --title "Title" --body "Description"
+
+ # Create PR with specific base
+ gh pr create --base develop --title "Title" --body "Body"
+
+ # Create draft PR
+ gh pr create --draft --title "WIP: Feature" --body "Body"
+
+ # List open PRs
+ gh pr list --limit 20
+
+ # View PR details
+ gh pr view 123
+ gh pr view 123 --json state,reviews,checks
+
+ # Check PR status (checks, reviews)
+ gh pr checks 123
+
+ # Review a PR
+ gh pr review 123 --approve
+ gh pr review 123 --request-changes --body "Fix X"
+ gh pr review 123 --comment --body "Looks good"
+
+ # Merge PR
+ gh pr merge 123 --squash --delete-branch
+ gh pr merge 123 --rebase
+ gh pr merge 123 --merge
+
+ # Close without merging
+ gh pr close 123
+
+ # View PR diff
+ gh pr diff 123
+
+ # Checkout a PR locally
+ gh pr checkout 123
+
+ # Edit PR metadata
+ gh pr edit 123 --add-label "bug" --add-reviewer "user"
+ gh pr edit 123 --milestone "v1.0"
+
+ # View PR comments
+ gh api repos/OWNER/REPO/pulls/123/comments
+ ```
+
+ ## Issue Triage
+
+ ```bash
+ # List open issues
+ gh issue list --limit 20
+ gh issue list --label "bug" --assignee "@me"
+ gh issue list --state closed --limit 10
+
+ # Create issue
+ gh issue create --title "Bug: X" --body "Steps to reproduce..."
+ gh issue create --label "bug,critical" --assignee "@me"
+
+ # View issue
+ gh issue view 456
+ gh issue view 456 --json title,body,labels,comments
+
+ # Close / reopen
+ gh issue close 456 --reason "completed"
+ gh issue reopen 456
+
+ # Edit issue
+ gh issue edit 456 --add-label "priority:high" --milestone "v2.0"
+
+ # Transfer issue to another repo
+ gh issue transfer 456 OWNER/OTHER-REPO
+
+ # Pin / unpin
+ gh issue pin 456
+ gh issue unpin 456
+
+ # Comment on issue
+ gh issue comment 456 --body "Working on this"
+
+ # List issue comments
+ gh api repos/OWNER/REPO/issues/456/comments
+ ```
+
+ ## Search
+
+ Never use `curl` or browser for GitHub search. Use `gh search` subcommands:
+
+ ```bash
+ # Search repositories
gh search repos "cli language:rust stars:>100" --limit 10 --sort stars
- gh search issues "repo:OWNER/REPO is:open label:bug" --limit 10
+
+ # Search code
gh search code "fn parse language:rust repo:OWNER/REPO" --limit 10
gh search code "filename:Cargo.toml org:ORG" --limit 10
+
+ # Search issues
+ gh search issues "repo:OWNER/REPO is:open label:bug" --limit 10
+
+ # Search pull requests
gh search prs "is:merged author:USER" --limit 10 --sort updated
+
+ # Search commits
gh search commits "fix memory repo:OWNER/REPO" --limit 10 --sort committer-date
```
- Key qualifiers: `repo:`, `org:`, `language:`, `filename:`, `path:`, `extension:`, `is:`, `label:`, `author:`, `stars:`, `created:`, `in:`.
+ Key qualifiers: `repo:`, `org:`, `language:`, `filename:`, `path:`, `extension:`, `is:`,
+ `label:`, `author:`, `stars:`, `created:`, `in:`.
- Full qualifier reference and sorting options: [references/search.md](references/search.md)
+ Full qualifier reference: [references/search.md](references/search.md)
- ## Token-saving patterns
+ ## Output Formatting
+ ### JSON output (`--json`)
+
+ Select specific fields to reduce output size:
+
+ ```bash
+ gh pr list --json number,title,state
+ gh issue list --json number,title,labels,assignees
+ gh repo view --json name,description,stargazerCount
+ gh pr view 123 --json commits,files,reviews
+ ```
+
+ ### JQ filtering (`--jq`)
+
+ Filter and transform JSON output:
+
+ ```bash
+ # Get just PR titles
+ gh pr list --json title --jq '.[].title'
+
+ # Filter issues by label
+ gh issue list --json number,title,labels \
+ --jq '.[] | select(.labels | any(.name == "bug"))'
+
+ # Count open PRs by author
+ gh pr list --json author --jq '[.[].author.login] | group_by(.) | map({(.[0]): length}) | add'
+
+ # Extract specific nested fields
+ gh pr view 123 --json reviews --jq '.reviews[].state'
+ ```
+
+ ### Go templates (`--template`)
+
+ ```bash
+ gh issue list --template '{{range .}}#{{.number}} {{.title}}{{"\n"}}{{end}}'
+ gh pr list --template '{{range .}}{{.number}}\t{{.state}}\t{{.title}}{{"\n"}}{{end}}'
+ ```
+
+ ## API Access
+
+ Use `gh api` for any GitHub REST or GraphQL endpoint not covered by built-in commands:
+
+ ```bash
+ # REST API (automatically authenticated)
+ gh api repos/OWNER/REPO
+ gh api repos/OWNER/REPO/contributors --paginate
+
+ # POST with JSON body
+ gh api repos/OWNER/REPO/issues -f title="Bug" -f body="Description"
+
+ # GraphQL
+ gh api graphql -f query='{ viewer { login } }'
+
+ # With JQ filtering
+ gh api repos/OWNER/REPO/releases --jq '.[0].tag_name'
+
+ # Paginate automatically
+ gh api repos/OWNER/REPO/issues --paginate --jq '.[].title'
+ ```
+
+ Full API reference: [references/api.md](references/api.md)
+
+ ## CI/CD and Workflows
+
+ ```bash
+ # List workflow runs
+ gh run list --limit 10
+ gh run list --workflow build.yml --limit 5
+
+ # View run details
+ gh run view RUN_ID
+ gh run view RUN_ID --log
+
+ # Watch a run in progress
+ gh run watch RUN_ID
+
+ # Rerun a failed run
+ gh run rerun RUN_ID
+ gh run rerun RUN_ID --failed
+
+ # Trigger a workflow dispatch
+ gh workflow run build.yml --ref main
+
+ # List workflows
+ gh workflow list
+
+ # Manage repo secrets
+ gh secret set SECRET_NAME --body "value"
+ gh secret list
+
+ # Manage repo variables
+ gh variable set VAR_NAME --body "value"
+ gh variable list
+
+ # View action cache
+ gh cache list
+ gh cache delete KEY
+ ```
+
+ Full workflows reference: [references/workflows.md](references/workflows.md)
+
+ ## Environment Variables
+
+ | Variable | Description |
+ |---|---|
+ | `GH_TOKEN` | Auth token (overrides stored credentials) |
+ | `GITHUB_TOKEN` | Alternative to `GH_TOKEN` |
+ | `GH_ENTERPRISE_TOKEN` | Token for GitHub Enterprise |
+ | `GH_HOST` | Default GitHub hostname |
+ | `GH_REPO` | Default repo in `[HOST/]OWNER/REPO` format |
+ | `GH_EDITOR` | Editor for interactive commands |
+ | `GH_BROWSER` | Browser for `gh browse` |
+ | `GH_PAGER` | Pager for output (default: system pager) |
+ | `GH_DEBUG` | Set to `1` or `api` for debug output |
+ | `GH_NO_UPDATE_NOTIFIER` | Set to `1` to disable update notifications |
+ | `GH_CONFIG_DIR` | Config directory (default: `~/.config/gh`) |
+ | `NO_COLOR` | Disable color output |
+
+ ## Configuration
+
+ ```bash
+ # View current config
+ gh config list
+
+ # Set default editor
+ gh config set editor vim
+
+ # Set default git protocol
+ gh config set git_protocol ssh
+
+ # Set default browser
+ gh config set browser "firefox"
+
+ # Set prompt (disable interactive prompts)
+ gh config set prompt disabled
+
+ # Per-host config
+ gh config set git_protocol ssh --host github.example.com
+ ```
+
+ ## Extensions
+
+ ```bash
+ # Browse available extensions
+ gh ext browse
+
+ # Install an extension
+ gh ext install OWNER/gh-EXTENSION
+
+ # List installed extensions
+ gh ext list
+
+ # Upgrade extensions
+ gh ext upgrade --all
+ gh ext upgrade OWNER/gh-EXTENSION
+
+ # Remove an extension
+ gh ext remove OWNER/gh-EXTENSION
+ ```
+
+ ## Token-Saving Patterns
+
- Always use `--limit N` or `| head -N` to cap output
- Use `--json FIELD1,FIELD2` to select only needed fields
- Use `--jq 'EXPRESSION'` to filter JSON responses
- Combine `--json` and `--jq` to get minimal output in one call
- Use `gh api --paginate` instead of manual pagination loops
+ - Use `--web` to open in browser instead of fetching large content
+ - Prefer `gh pr checks` over `gh run list` when checking a specific PR