GitHub CLI (gh) comprehensive reference for repositories, issues, pull requests, Actions, projects, releases, gists, codespaces, organizations, extensions, and all GitHub operations from the command line. Use when creating PRs, managing issues, running workflows, checking CI status, managing releases, or making GitHub API calls. Triggers on "create PR", "list issues", "gh command", "merge PR", "run workflow", "check status", "create release", "download artifacts", "set secret".
Work seamlessly with GitHub from the command line.
| 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 |
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
For comprehensive command documentation:
| 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 |
# 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]}'
# Custom template
gh repo view --template '{{.name}}: {{.description}}'
# Multiline template
gh pr view 123 --template 'Title: {{.title}}
Author: {{.author.login}}
State: {{.state}}'
# 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"
# 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
# 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"
# 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 repository
gh repo fork original/repo --clone
cd repo
# Sync fork with upstream
gh repo sync
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
Set default repository to avoid repetition:
gh repo set-default owner/repo
Use JSON + jq for complex data extraction:
gh pr list --json number,title --jq '.[] | select(.title | contains("fix"))'
Use --paginate for large result sets:
gh issue list --state all --paginate
Use environment variables for automation:
export GH_TOKEN=$(gh auth token)
gh --help # General help
gh pr --help # Command help
gh issue create --help # Subcommand help
gh help formatting # Help topics
gh help environment