gh cli
- Repo stars 16
- License MIT
- Author repo wave
- Domain
- Other
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 94 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @re-cinq · MIT
- Token usage
- Lean
- Setup complexity
- Plug-and-play
- External API key
- Not required
- Operating systems
- Unspecified (assume cross-platform)
- Runtime requirements
- No explicit requirements detected
- Detected file/system behavior
-
- Read-only
- Write / modify
- Network behavior
- Local-only
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
# JSON Output Examples
# List PR numbers and titles
gh pr list --json number,title --jq '.[] | "\(.number): \(.title)"'
# Get issue labels
gh issue view 123 --json labels --jq '.labels[].name'
# Filter open PRs by author
gh pr list --json number,title,author \
--jq '.[] | select(.author.login == "alice")'
# GitHub CLI (gh)
Work seamlessly with GitHub from the command line. For the complete command reference see [`references/full-reference.md`](references/full-reference.md).
## Authentication
```bash
# Interactive login
gh auth login
# Login with token
gh auth login --with-token < token.txt
# Check status
gh auth status
# Switch accounts
gh auth switch --hostname github.com --user username
# Setup git credential helper
gh auth setup-git
# Print active token
gh auth token
```
## Pull Requests
```bash
# Create PR (interactive)
gh pr create
# Create with title, body, base, draft, reviewer
gh pr create --title "Feature: X" --body "Details..." --base main --draft --reviewer alice
# List open PRs
gh pr list
# List with filters
gh pr list --author @me --labels bug --state all --limit 50
# View a PR
gh pr view 123
gh pr view 123 --comments --web
# Merge a PR
gh pr merge 123 --squash --delete-branch
# Check CI status
gh pr checks 123
gh pr checks 123 --watch
```
## Issues
```bash
# Create issue (interactive)
gh issue create
# Create with title and labels
gh issue create --title "Bug: X" --body "Steps..." --labels bug,high-priority --assignee @me
# List open issues
gh issue list
# List with filters
gh issue list --assignee @me --labels bug --state all --search "is:open label:bug"
# View an issue
gh issue view 123
gh issue view 123 --comments --web
# Close / reopen
gh issue close 123 --comment "Fixed in PR #456"
gh issue reopen 123
```
## Common Flags
| Flag | Description |
|---|---|
| `--repo OWNER/REPO` | Target a specific repository |
| `--json FIELDS` | Output JSON for given fields |
| `--jq EXPRESSION` | Filter JSON output with jq |
| `--web` | Open result in browser |
| `--paginate` | Follow pagination for large result sets |
| `--limit N` | Cap result count |
## API Requests
```bash
# REST GET
gh api /user --jq '.login'
# REST POST with fields
gh api --method POST /repos/owner/repo/issues \
--field title="Issue title" --field body="Body"
# Paginate all results
gh api /user/repos --paginate
# GraphQL query
gh api graphql -f query='{ viewer { login } }'
```
## JSON Output Examples
```bash
# List PR numbers and titles
gh pr list --json number,title --jq '.[] | "\(.number): \(.title)"'
# Get issue labels
gh issue view 123 --json labels --jq '.labels[].name'
# Filter open PRs by author
gh pr list --json number,title,author \
--jq '.[] | select(.author.login == "alice")'
```
## Complete Reference
For all commands including repos, releases, Actions, projects, gists, codespaces, search, secrets, extensions, and more, see:
**[`references/full-reference.md`](references/full-reference.md)**
Sections and files
Listed in source order.
sections -> Authentication → Pull Requests → Issues → Common Flags → API Requests → JSON Output Examples
terms -> [references/full-reference.md](references/full-reference.md) · Work seamlessly with GitHub from the command line.
files/cmd -> references/full-reference.md · --repo OWNER/REPO · --json FIELDS · --jq EXPRESSION · --web · --paginate · --limit N
body sha256 -> 73a0b950b18b
Common Flags
Flag · Description
--repo OWNER/REPO· Target a specific repository--json FIELDS· Output JSON for given fields--jq EXPRESSION· Filter JSON output with jq--web· Open result in browserComplete Reference
For all commands including repos, releases, Actions, projects, gists, codespaces, search, secrets, extensions, and more, see:
references/full-reference.md