GitHub CLI & API

The GitHub CLI (`gh`) brings GitHub workflows into the terminal. The REST and GraphQL APIs enable automation, scripts, and integrations. Together they eliminate context-switching to the browser.

GitHub CLI Installation & Auth

# Install
brew install gh                     # macOS
winget install GitHub.cli            # Windows
sudo apt install gh                  # Ubuntu/Debian

# Authenticate
gh auth login                        # Interactive (browser or token)
gh auth login --with-token < token.txt
gh auth status                       # Check current auth
gh auth refresh -s write:packages   # Add extra scopes
gh auth logout

# Config
gh config set editor nvim
gh config set git_protocol ssh
gh config list

CLI: PRs, Issues, Repos

# --- Pull Requests ---
gh pr list --state open --base main
gh pr create --fill                  # Use commit info for title/body
gh pr diff 42
gh pr checks 42                      # Show CI status
gh pr comment 42 --body "LGTM! Merging tomorrow"
gh pr edit 42 --add-label "urgent" --add-reviewer carol
gh pr merge 42 --auto --squash       # Auto-merge when checks pass
gh pr close 42

# --- Issues ---
gh issue create --template bug_report.md
gh issue list --label "bug" --assignee "@me" --limit 20
gh issue edit 15 --title "Updated title" --add-assignee dave
gh issue transfer 15 owner/other-repo
gh issue lock 15 --reason resolved

# --- Repos ---
gh repo list --limit 30 --source     # Only non-forks
gh repo clone owner/repo
gh repo create --template owner/template-repo my-new-project
gh repo rename my-new-name
gh repo archive
gh repo delete owner/old-repo --yes
gh repo set-default owner/repo      # Set default repo for directory

# --- Releases ---
gh release list
gh release download v2.0.0 --pattern "*.tar.gz"
gh release delete v1.0.0-beta --yes

REST API with curl

# Base URL: https://api.github.com
# Auth header: -H "Authorization: Bearer TOKEN"

TOKEN=$(gh auth token)   # Get current token

# Get repo info
curl -s -H "Authorization: Bearer $TOKEN" \
  https://api.github.com/repos/owner/repo | jq .full_name

# List open PRs
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://api.github.com/repos/owner/repo/pulls?state=open&per_page=20" \
  | jq '.[].title'

# Create an issue
curl -s -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Bug: login fails","body":"Steps...","labels":["bug"]}' \
  https://api.github.com/repos/owner/repo/issues

# Get workflow run logs
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://api.github.com/repos/owner/repo/actions/runs?status=failure" \
  | jq '.workflow_runs[0] | {id, name, conclusion, head_branch}'

# Trigger a workflow dispatch
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ref":"main","inputs":{"environment":"staging"}}' \
  https://api.github.com/repos/owner/repo/actions/workflows/deploy.yml/dispatches

# Pagination with Link header
curl -s -I -H "Authorization: Bearer $TOKEN" \
  "https://api.github.com/repos/owner/repo/issues?per_page=100" \
  | grep -i link   # Shows next/last page URLs

GraphQL API

# GitHub GraphQL endpoint: https://api.github.com/graphql
# Use gh api graphql for convenience

# Query PR details with reviews
gh api graphql -f query='
  query($owner: String!, $repo: String!, $number: Int!) {
    repository(owner: $owner, name: $repo) {
      pullRequest(number: $number) {
        title
        state
        additions
        deletions
        reviewDecision
        reviews(last: 5) {
          nodes {
            author { login }
            state
            body
          }
        }
        commits(last: 1) {
          nodes {
            commit {
              statusCheckRollup {
                state
              }
            }
          }
        }
      }
    }
  }
' -F owner=myorg -F repo=myrepo -F number=42

# Get all repos in org with stars
gh api graphql --paginate -f query='
  query($endCursor: String) {
    organization(login: "myorg") {
      repositories(first: 100, after: $endCursor) {
        nodes { name stargazerCount }
        pageInfo { hasNextPage endCursor }
      }
    }
  }
' | jq '.data.organization.repositories.nodes[] | select(.stargazerCount > 10)'

Useful CLI Aliases & Scripts

# Create gh aliases
gh alias set prc 'pr create --fill'
gh alias set prl 'pr list --state open'
gh alias set cleanup '!git branch --merged | grep -v main | xargs git branch -d'

# Run aliases
gh prc
gh prl
gh cleanup

# List all aliases
gh alias list

# Useful one-liners
# Open current branch's PR in browser
gh pr view --web

# Show CI status for current branch
gh pr checks

# Watch Actions run in real time
gh run watch

# Download artifact from latest run
gh run download --name coverage-report

# List failed runs for a workflow
gh run list --workflow ci.yml --status failure --limit 5