GitHub CLI (gh) — GitHub Official Command Line Tool

What it is

GitHub CLI (gh) is the official command-line tool for GitHub. It brings pull requests, issues, code review, Actions workflows, releases, and repository management to your terminal. Written in Go, gh works on macOS, Linux, and Windows.

gh targets developers who prefer the terminal over the GitHub web interface. It integrates with Git workflows so you can create PRs, review diffs, manage issues, and trigger CI/CD without opening a browser.

How it saves time or tokens

gh eliminates context switching between your terminal and the GitHub web interface. Creating a pull request is a single command instead of navigating to the web UI. Viewing CI status, approving reviews, and merging PRs all happen from the terminal. For scripting and automation, gh provides structured JSON output and a powerful gh api command for any GitHub API endpoint.

How to use

1. Install gh:

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

1. Authenticate:

gh auth login

1. Common workflows:

gh pr create --title 'Add feature' --body 'Description here'
gh pr list
gh pr checkout 42
gh pr merge 42 --squash
gh issue create --title 'Bug report' --body 'Details'
gh run list
gh run watch

Example

# Create a repo and push
gh repo create my-project --public --source=. --push

# Create PR with reviewers
gh pr create --title 'Refactor auth module' \
  --body 'Simplified OAuth flow' \
  --reviewer alice,bob \
  --label enhancement

# View PR diff and approve
gh pr diff 42
gh pr review 42 --approve

# Scripting with JSON output
gh pr list --json number,title,state | jq '.[] | select(.state=="OPEN")'

# Call any GitHub API endpoint
gh api repos/{owner}/{repo}/actions/runs --jq '.workflow_runs[0].status'

Related on TokRepo

• AI Tools for Coding — Developer productivity tools
• DevOps Tools — CI/CD and automation

This tool integrates with standard development workflows and requires minimal configuration to get started. It is available as open-source software with documentation and community support through the official repository. The project follows semantic versioning for stable releases.

For teams evaluating this tool, the key advantage is reducing manual work in repetitive tasks. The automation provided by the built-in features means less custom code to maintain and fewer integration points to manage. This translates directly to lower maintenance costs and faster iteration cycles.

Common pitfalls

• gh auth login stores credentials in the system keychain; on headless servers, use gh auth login --with-token to authenticate with a personal access token via stdin.
• The gh api command provides direct GitHub API access but requires understanding REST/GraphQL endpoints; use --jq for filtering JSON responses.
• gh uses the current Git remote to determine the repository; if you have multiple remotes, specify the repo with --repo owner/name.