GitHub CLI (gh)

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

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

# 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

# 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

# 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

# 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

# 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

# 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

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

# Sync fork with upstream
gh repo sync

Environment Variables

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

1. Set default repository to avoid repetition:

   gh repo set-default owner/repo

2. Use JSON + jq for complex data extraction:

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

3. Use --paginate for large result sets:

   gh issue list --state all --paginate

4. Use environment variables for automation:

   export GH_TOKEN=$(gh auth token)

Getting Help

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