GitHub CLI (gh)

Installation

# macOS
brew install gh

# Ubuntu / Debian
sudo apt install gh

# Fedora / RHEL
sudo dnf install gh

# Windows (winget)
winget install --id GitHub.cli

# Windows (scoop)
scoop install gh

# From releases
# https://github.com/cli/cli/releases

Verify:

gh --version

Configuration

Authentication

# Interactive login (browser-based)
gh auth login

# Login to GitHub Enterprise
gh auth login --hostname github.yourcompany.com

# Login with a token (CI environments)
echo $GITHUB_TOKEN | gh auth login --with-token

# Check auth status
gh auth status

# Logout
gh auth logout

# Refresh token scopes
gh auth refresh --scopes repo,workflow,read:org

Global Settings

# Set default editor
gh config set editor nvim

# Set default git protocol
gh config set git_protocol ssh

# Enable/disable telemetry
gh config set telemetry false

# View all config
gh config list

# Set per-host config
gh config set -h github.com editor vim

# Set default browser
gh config set browser firefox

Aliases

# Create an alias
gh alias set prc 'pr create --fill'
gh alias set co 'pr checkout'
gh alias set prw 'pr view --web'

# List aliases
gh alias list

# Delete an alias
gh alias delete prc

Core Commands

Repository

Command	Description
gh repo create	Create a new repository
gh repo clone owner/repo	Clone a repository
gh repo fork owner/repo	Fork a repository
gh repo view	View repo details
gh repo view --web	Open repo in browser
gh repo list	List your repositories
gh repo list --org myorg	List org repositories
gh repo sync	Sync fork with upstream
gh repo archive	Archive a repository
gh repo rename new-name	Rename repository
gh repo delete owner/repo	Delete repository
gh repo edit	Edit repo settings

Pull Requests

Command	Description
gh pr create	Create a pull request
gh pr create --fill	Create PR using commit info
gh pr create --draft	Create draft PR
gh pr list	List open PRs
gh pr list --state all	List all PRs
gh pr view 123	View PR details
gh pr view --web	Open PR in browser
gh pr checkout 123	Checkout PR branch locally
gh pr diff 123	Show PR diff
gh pr review 123	Add review
gh pr review --approve	Approve PR
gh pr review --request-changes	Request changes
gh pr merge 123	Merge a PR
gh pr merge --squash	Merge with squash
gh pr merge --rebase	Merge with rebase
gh pr close 123	Close a PR
gh pr reopen 123	Reopen a PR
gh pr edit 123	Edit PR metadata
gh pr status	Show your PR status
gh pr checks	Show CI check statuses
gh pr ready	Mark draft PR as ready

Issues

Command	Description
gh issue create	Create an issue
gh issue list	List open issues
gh issue list --label bug	Filter by label
gh issue view 42	View issue
gh issue view 42 --web	Open issue in browser
gh issue close 42	Close an issue
gh issue reopen 42	Reopen an issue
gh issue edit 42	Edit issue
gh issue comment 42	Add a comment
gh issue pin 42	Pin an issue
gh issue transfer 42 owner/repo	Transfer to another repo
gh issue develop 42	Create branch from issue
gh issue status	Show your issue status

GitHub Actions

Command	Description
gh workflow list	List workflows
gh workflow run deploy.yml	Trigger a workflow
gh workflow enable workflow.yml	Enable a workflow
gh workflow disable workflow.yml	Disable a workflow
gh run list	List workflow runs
gh run list --workflow deploy.yml	Runs for a workflow
gh run view 12345	View a run
gh run watch 12345	Watch a run live
gh run rerun 12345	Re-run a workflow
gh run download 12345	Download run artifacts
gh run cancel 12345	Cancel a run
gh run delete 12345	Delete a run

Releases

Command	Description
gh release create v1.0.0	Create a release
gh release list	List releases
gh release view v1.0.0	View release details
gh release download v1.0.0	Download release assets
gh release upload v1.0.0 dist/*	Upload assets to release
gh release delete v1.0.0	Delete a release
gh release edit v1.0.0	Edit release metadata

Gists

Command	Description
gh gist create file.txt	Create a gist
gh gist create --public file.txt	Create a public gist
gh gist list	List your gists
gh gist view abc123	View a gist
gh gist edit abc123	Edit a gist
gh gist delete abc123	Delete a gist
gh gist clone abc123	Clone a gist

Codespaces

Command	Description
gh codespace create	Create a codespace
gh codespace list	List codespaces
gh codespace ssh	SSH into a codespace
gh codespace code	Open codespace in VS Code
gh codespace delete	Delete a codespace
gh codespace ports	View forwarded ports
gh codespace stop	Stop a codespace

Advanced Usage

API Calls

# GET request
gh api repos/owner/repo

# GET with query params
gh api 'repos/owner/repo/issues?state=closed&per_page=5'

# POST request
gh api repos/owner/repo/labels \
  --method POST \
  --field name='priority:high' \
  --field color='e11d48'

# PATCH request
gh api repos/owner/repo/issues/42 \
  --method PATCH \
  --field state='closed'

# Paginate through all results
gh api repos/owner/repo/issues --paginate

# Use GraphQL
gh api graphql -f query='
  query {
    viewer {
      login
      repositories(first: 5) {
        nodes { name }
      }
    }
  }
'

# JQ filtering
gh api repos/owner/repo/issues \
  --jq '.[].title'

Extensions

# Install an extension
gh extension install dlvhdr/gh-dash

# List installed extensions
gh extension list

# Upgrade all extensions
gh extension upgrade --all

# Remove an extension
gh extension remove dlvhdr/gh-dash

# Browse extensions
gh extension browse

# Create your own extension
gh extension create my-ext

Search

# Search repositories
gh search repos "language:go stars:>1000"

# Search issues
gh search issues "label:bug is:open repo:owner/repo"

# Search pull requests
gh search prs "review:required is:open author:@me"

# Search commits
gh search commits "fix bug repo:owner/repo"

# Search code
gh search code "function authenticate" --extension py

Environment Variables

# Set GH_TOKEN for CI
export GH_TOKEN=ghp_xxxxxxxxxxxx

# Override default host
export GH_HOST=github.yourcompany.com

# Override editor
export GH_EDITOR=code

# Override browser
export GH_BROWSER=firefox

# Disable prompts (scripting)
export GH_NO_PROMPT=1

Scripting with --json and --jq

# Get PR numbers as JSON
gh pr list --json number,title,state

# Extract just PR numbers
gh pr list --json number --jq '.[].number'

# Get latest release tag
gh release list --json tagName --jq '.[0].tagName'

# Count open issues by label
gh issue list --label bug --json number --jq 'length'

# Format output as table
gh pr list --json number,title,headRefName \
  --template '{{range .}}{{.number}}\t{{.title}}\t{{.headRefName}}{{"\n"}}{{end}}'

PR Create with Full Options

gh pr create \
  --title "feat: add dark mode" \
  --body "Closes #42" \
  --base main \
  --head feature/dark-mode \
  --reviewer alice,bob \
  --assignee @me \
  --label enhancement \
  --milestone "v2.0" \
  --draft

Workflow Dispatch with Inputs

gh workflow run deploy.yml \
  --field environment=production \
  --field version=v1.2.3 \
  --ref main

Common Workflows

Fork, Clone, and PR Workflow

# Fork and clone
gh repo fork owner/repo --clone --remote

# Create feature branch
git checkout -b feature/my-change

# Make changes, commit...

# Push and create PR in one step
gh pr create --fill --web

Monitor CI on a PR

# View checks on current branch's PR
gh pr checks

# Watch a specific run
gh run list --limit 1 --json databaseId --jq '.[0].databaseId' | xargs gh run watch

Bulk Close Stale Issues

gh issue list --state open --label stale --json number --jq '.[].number' | \
  xargs -I {} gh issue close {} --comment "Closing as stale."

Create Release with Changelog

gh release create v1.2.0 \
  --generate-notes \
  --title "v1.2.0 — Dark Mode & Performance" \
  dist/app-linux-amd64 \
  dist/app-darwin-arm64

Set Up Repo from Scratch

gh repo create my-project \
  --public \
  --description "My awesome project" \
  --add-readme \
  --gitignore Node \
  --license MIT \
  --clone

Tips and Best Practices

• gh pr create --fill auto-populates the PR title and body from your commit messages — great for fast PRs.
• gh pr checkout checks out a PR branch and sets up the remote tracking so you can push back to it directly.
• Use --json + --jq for scripting — avoids parsing human-readable output and is stable across versions.
• Aliases shorten repeat commands — gh alias set co 'pr checkout' saves keystrokes dozens of times per day.
• GH_TOKEN in CI — set this environment variable in your CI system; gh picks it up automatically without interactive auth.
• gh run watch streams live logs from a running Action — better than reloading the browser.
• Extensions add missing features — gh-dash gives a TUI dashboard, gh-copilot adds AI suggestions.
• gh api --paginate automatically fetches all pages of a paginated endpoint — essential for repos with many issues.
• gh search works without being inside a git repo — useful for cross-repo searches in scripts.
• gh codespace ssh lets you use any local terminal config with cloud development environments.
• gh issue develop 42 creates a properly-named branch linked to an issue and switches to it immediately.
• gh pr merge --delete-branch merges and cleans up the remote branch atomically.