GitHub CLI (gh)

Name: gh-cli
Rating: 92
Author: zhongjis

Work seamlessly with GitHub from the command line.

Quick Reference

Task	Command
Create PR	`gh pr create --title "..." --body "..."`
List open PRs	`gh pr list`
View PR	`gh pr view 123`
Merge PR	`gh pr merge 123 --squash --delete-branch`
Checkout PR	`gh pr checkout 123`
Create issue	`gh issue create --title "..." --body "..."`
List issues	`gh issue list`
Close issue	`gh issue close 123 --comment "Fixed in #456"`
Clone repo	`gh repo clone owner/repo`
Create repo	`gh repo create my-repo --public`
List workflow runs	`gh run list`
Watch workflow	`gh run watch 123456789`
Run workflow	`gh workflow run ci.yml`
Download artifacts	`gh run download 123456789`
Create release	`gh release create v1.0.0 --notes "..."`
Set secret	`gh secret set MY_SECRET`
API request	`gh api /user`

CLI Structure

code

gh                          # Root command
├── auth                    # Authentication
├── browse                  # Open in browser
├── repo                    # Repositories
├── issue                   # Issues
├── pr                      # Pull Requests
├── run                     # Workflow runs
├── workflow                # Workflows
├── release                 # Releases
├── project                 # Projects
├── codespace               # Codespaces
├── gist                    # Gists
├── cache                   # Actions caches
├── secret                  # Secrets
├── variable                # Variables
├── api                     # API requests
├── search                  # Search
├── label                   # Labels
├── org                     # Organizations
├── ssh-key                 # SSH keys
├── gpg-key                 # GPG keys
├── extension               # Extensions
├── alias                   # Aliases
├── config                  # Configuration
├── ruleset                 # Rulesets
├── attestation             # Attestations
├── status                  # Status overview
└── completion              # Shell completion

Detailed References

For comprehensive command documentation:

•Authentication - Login, tokens, credentials, environment variables
•Repositories - Create, clone, fork, sync, browse, edit
•Issues - Create, list, edit, close, comment, labels
•Pull Requests - Create, review, merge, checkout, diff
•Actions - Workflows, runs, caches, secrets, variables
•Releases - Create, upload, download, verify
•Projects - Create, manage items, fields
•Codespaces - Create, connect, manage
•API - REST and GraphQL requests
•Misc - Gists, orgs, search, labels, keys, extensions, aliases

Global Flags

Flag	Description
`--help` / `-h`	Show help for command
`--repo [HOST/]OWNER/REPO`	Select another repository
`--hostname HOST`	GitHub hostname
`--jq EXPRESSION`	Filter JSON output
`--json FIELDS`	Output JSON with specified fields
`--template STRING`	Format JSON using Go template
`--web`	Open in browser
`--paginate`	Make additional API calls

Output Formatting

JSON Output

bash

# Basic JSON
gh repo view --json name,description

# Nested fields
gh repo view --json owner,name --jq '.owner.login + "/" + .name'

# Array operations
gh pr list --json number,title --jq '.[] | select(.number > 100)'

# Complex queries
gh issue list --json number,title,labels \
  --jq '.[] | {number, title: .title, tags: [.labels[].name]}'

Template Output

bash

# Custom template
gh repo view --template '{{.name}}: {{.description}}'

# Multiline template
gh pr view 123 --template 'Title: {{.title}}
Author: {{.author.login}}
State: {{.state}}'

Common Workflows

Create PR from Issue

bash

# Create branch from issue
gh issue develop 123 --branch feature/issue-123

# Make changes, commit, push
git add . && git commit -m "Fix issue #123" && git push

# Create PR linking to issue
gh pr create --title "Fix #123" --body "Closes #123"

Bulk Operations

bash

# Close multiple issues
gh issue list --search "label:stale" --json number --jq '.[].number' | \
  xargs -I {} gh issue close {} --comment "Closing as stale"

# Add label to multiple PRs
gh pr list --search "review:required" --json number --jq '.[].number' | \
  xargs -I {} gh pr edit {} --add-label needs-review

Repository Setup

bash

# Create repository with initial setup
gh repo create my-project --public \
  --description "My awesome project" \
  --clone --gitignore python --license mit

cd my-project

# Create labels
gh label create bug --color "d73a4a" --description "Bug report"
gh label create enhancement --color "a2eeef" --description "Feature request"

CI/CD Workflow

bash

# Run workflow
gh workflow run ci.yml --ref main

# Get latest run
RUN_ID=$(gh run list --workflow ci.yml --limit 1 --json databaseId --jq '.[0].databaseId')

# Watch the run
gh run watch "$RUN_ID"

# Download artifacts on completion
gh run download "$RUN_ID" --dir ./artifacts

Fork and Sync

bash

# Fork repository
gh repo fork original/repo --clone
cd repo

# Sync fork with upstream
gh repo sync

Environment Variables

bash

export GH_TOKEN=ghp_xxxxxxxxxxxx    # Token for automation
export GH_HOST=github.com           # GitHub hostname
export GH_PROMPT_DISABLED=true      # Disable prompts
export GH_REPO=owner/repo           # Override default repo

Best Practices

•
Set default repository to avoid repetition:
bash
```
gh repo set-default owner/repo
```

•

Use JSON + jq for complex data extraction:

bash

gh pr list --json number,title --jq '.[] | select(.title | contains("fix"))'

•
Use --paginate for large result sets:
bash
```
gh issue list --state all --paginate
```
•
Use environment variables for automation:
bash
```
export GH_TOKEN=$(gh auth token)
```

Getting Help

bash

gh --help              # General help
gh pr --help           # Command help
gh issue create --help # Subcommand help
gh help formatting     # Help topics
gh help environment

References

•Official Manual: https://cli.github.com/manual/
•GitHub Docs: https://docs.github.com/en/github-cli
•REST API: https://docs.github.com/en/rest
•GraphQL API: https://docs.github.com/en/graphql