GitHub CLI (gh)

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

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