v1.0 to v1.0

---

name: github

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.

## Quick Reference

| Category | Command | Details |

|---|---|---|

| 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) |

| 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) |

## Authentication

```bash

# Interactive login (browser or token)

gh auth login

# Login with token (non-interactive, CI)

echo "$TOKEN" | gh auth login --with-token

# 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

# 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:`.

Full qualifier reference: [references/search.md](references/search.md)

## 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