GitHub CLI (gh)

gh is the official command-line tool from GitHub. Unlike git, which works with the local .git/ directory and pushes commits, gh talks to the GitHub API: it creates PRs, lists issues, views Actions runs, and downloads releases. These things live in GitHub's database, not in Git objects.

Installation

# macOS

brew install gh

# Ubuntu/Debian

sudo apt install gh

# Windows

winget install GitHub.cli

scoop install gh

# verify

gh --version

The full list of installers is at cli.github.com.

Authentication

gh auth login

The command asks a few questions (GitHub.com or Enterprise, HTTPS or SSH, browser or token) and stores an OAuth token in the OS keychain. After that:

gh auth status      # which account is active, which scopes

gh auth switch      # switch between multiple accounts

gh auth logout      # revoke

Main commands

# repositories

gh repo clone owner/repo

gh repo fork owner/repo --clone   # fork + clone + remote setup

gh repo create my-project --public --source=. --push

# pull requests

gh pr create -t "fix login" -b "Fixes #142"

gh pr list --author "@me"

gh pr view 123

gh pr checkout 123             # check out any PR branch locally

gh pr review --approve

gh pr merge --squash --delete-branch

gh pr checks --watch           # watch CI status in real time

# issues

gh issue create -t "Bug: ..." -b "..."

gh issue list --label bug

# actions

gh workflow run ci.yml

gh run list --workflow ci.yml

gh run view 12345 --log

gh run rerun --failed

JSON output for scripts

Almost every command accepts --json with a field list:

gh pr list --json number,title,author \

  | jq -r '.[] | "\(.number) - \(.title) by \(.author.login)"'

To see the valid field names, pass --json with no argument; the error message lists all available fields.

Aliases

gh alias set co 'pr checkout'

gh alias set prs 'pr list --author "@me"'

Aliases are stored in ~/.config/gh/config.yml. They accept $1, $2 for argument substitution.

Escape hatch: gh api

When there is no native command, you have raw access to REST or GraphQL:

gh api repos/cli/cli/contributors --jq '.[].login'

gh api graphql -f query='query { viewer { login } }'

gh handles authentication, pagination, and retries for you.

When gh is faster than the browser

• Creating a PR from the current branch (gh pr create).
• Checking out someone else's PR for testing (gh pr checkout).
• Viewing CI logs with grep.
• Batch operations and scripts.
• Creating an issue without leaving the terminal.

When the browser is more convenient

• Inline code review (selecting lines with the mouse).
• Long discussions with multiple participants.
• Large diffs spanning many files.
• Repository settings and organization management.

Both tools coexist. The terminal for speed, the browser for visual review. Details are in chapter 16.