gh-cli

GitHub CLI Operations

Practical reference for gh — the GitHub CLI. Covers repos, issues, PRs, releases, Actions, and automation.

Prerequisites

# Install
brew install gh          # macOS
winget install GitHub.cli # Windows
sudo apt install gh       # Linux

# Authenticate and verify
gh auth login
gh auth status

Phase 1: Repositories

# Create and clone
gh repo create my-project --public --description "My project" --clone
gh repo clone owner/repo
gh repo fork owner/repo --clone

# View and edit
gh repo view owner/repo
gh repo edit --description "Updated desc"
gh browse                  # Open in browser

# Sync fork
gh repo sync

Phase 2: Issues

# Create
gh issue create --title "Bug: login broken" --labels bug --assignee @me

# List and search
gh issue list
gh issue list --labels bug --assignee @me
gh issue list --search "is:open label:bug sort:updated-desc"
gh issue list --json number,title --jq '.[].title'

# Manage
gh issue view 42
gh issue close 42 --comment "Fixed in PR #55"
gh issue edit 42 --add-label priority-high
gh issue develop 42 --branch fix/issue-42

Phase 3: Pull Requests

# Create
gh pr create --title "feat: add dark mode" --body "Closes #42" --reviewer user
gh pr create --draft --title "WIP: new feature"

# List and view
gh pr list
gh pr list --author @me
gh pr view 55
gh pr diff 55

# Review and merge
gh pr checkout 55
gh pr review 55 --approve --body "LGTM!"
gh pr review 55 --request-changes --body "Please fix error handling"
gh pr merge 55 --squash --delete-branch

# Manage
gh pr ready 55             # Mark draft as ready
gh pr checks 55 --watch    # Watch CI
gh pr edit 55 --add-label reviewed
gh pr update-branch 55     # Rebase with base

Phase 4: Releases

# Create
gh release create v1.2.0 --generate-notes --title "v1.2.0"
gh release create v1.2.0 --notes-file CHANGELOG.md
gh release create v1.2.0 ./dist/*.tar.gz   # With assets

# Manage
gh release list
gh release view v1.2.0
gh release download v1.2.0 --pattern "*.tar.gz" --dir ./downloads
gh release upload v1.2.0 ./dist/checksums.txt
gh release delete v1.2.0 --yes

Phase 5: GitHub Actions

# Monitor
gh run list
gh run list --workflow ci.yml
gh run view 123456 --log
gh run watch 123456
gh run download 123456 --dir ./artifacts

# Trigger
gh workflow run deploy.yml
gh workflow run deploy.yml --raw-field environment=staging

# Manage
gh run rerun 123456
gh run cancel 123456

# Secrets and variables
gh secret list
echo "value" | gh secret set API_KEY
gh secret set DB_PASS --env production
gh variable set DEPLOY_ENV --body "staging"

Phase 6: Advanced

API Requests

gh api /repos/owner/repo/contributors --jq '.[].login'
gh api --method POST /repos/owner/repo/issues \
  --field title="API issue" --field body="Created via gh api"

Bulk Operations

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

# Label all open PRs
gh pr list --json number --jq '.[].number' | \
  xargs -I {} gh pr edit {} --add-label needs-review

Search

gh search repos "topic:fastapi stars:>100" --json name,url
gh search code "def authenticate" --repo owner/repo
gh search issues "label:bug state:open" --limit 20

Aliases

gh alias set co 'pr checkout'
gh alias set myissues 'issue list --assignee @me'
gh alias set review 'pr list --search "review-requested:@me"'

Common Workflows

Issue to PR (Full Cycle)

gh issue develop 42 --branch fix/issue-42
git add . && git commit -m "fix: resolve login bug" && git push -u origin HEAD
gh pr create --title "fix: resolve login bug" --body "Closes #42"
gh pr checks --watch
gh pr merge --squash --delete-branch

Release Workflow

git tag v1.3.0 && git push origin v1.3.0
gh release create v1.3.0 --generate-notes --title "v1.3.0"
gh release upload v1.3.0 ./dist/*.tar.gz

Quick Reference

Task	Command
Create repo	gh repo create name --public
Create issue	gh issue create --title "..." --labels bug
Create PR	gh pr create --title "..." --reviewer user
Merge PR	gh pr merge 55 --squash --delete-branch
Create release	gh release create v1.0.0 --generate-notes
Watch CI	gh run watch
Set secret	echo "val" | gh secret set KEY
API call	gh api /repos/o/r --jq '.description'