If you work with GitHub repositories and you’re not using the GitHub CLI (gh), you’re doing more context-switching than you need to. The web interface is fine for some things, but it’s painfully slow for the workflows that happen dozens of times a day: checking PR status, reviewing diffs, running workflows, creating issues. The GitHub CLI collapses all of that into your terminal and pairs with your existing git workflow in ways the browser simply can’t.

This guide covers the commands that make a real difference to daily workflow — not a reproduction of the docs, but the subset that consistently saves time.

Installation

# macOS
brew install gh

# Ubuntu/Debian
sudo apt install gh

# Windows
winget install GitHub.cli

# Verify
gh --version

After installing, authenticate once:

gh auth login

This opens a browser for OAuth or prompts for a personal access token. The auth state persists in your system keyring.

Pull Requests

Pull requests are where gh earns its keep most visibly.

Create a PR from the current branch:

gh pr create

This opens an interactive prompt for title, description, and labels. Add --fill to pre-fill from commit messages and skip the editor, or --web to open the PR creation form in the browser if you prefer.

gh pr create --title "Fix cache invalidation bug" --body "Closes #142" --assignee @me

List open PRs:

gh pr list

Filter by author, label, or status:

gh pr list --author @me --state open
gh pr list --label "needs-review" --limit 20

Check the status of a PR (CI checks, approvals, review comments):

gh pr status

This shows your current branch’s PR status plus any PRs where you’re assigned as reviewer. It’s the fastest way to see if your PR is blocked on something.

Check out a PR locally:

gh pr checkout 142

This creates a local branch tracking the PR branch. Faster than copying branch names from the browser.

Review and approve from the terminal:

gh pr review 142 --approve
gh pr review 142 --comment --body "Needs tests for the error path"
gh pr review 142 --request-changes --body "See inline comments"

Merge a PR:

gh pr merge 142 --squash --delete-branch

The --delete-branch flag removes the remote branch on merge. Use --squash, --rebase, or --merge to match your repo’s preferred merge strategy.

Watch PR checks in real time:

gh pr checks 142 --watch

This streams CI status updates. Useful when you’ve just pushed and want to know immediately when checks pass without refreshing the browser.

Issues

Create an issue:

gh issue create --title "Login form doesn't clear on error" --body "Steps to reproduce..." --label "bug"

List issues:

gh issue list --assignee @me
gh issue list --label "P0" --state open

View an issue (renders markdown in terminal):

gh issue view 88

Close an issue with a comment:

gh issue close 88 --comment "Fixed in #142"

GitHub Actions Workflows

The gh workflow and gh run commands make workflow management significantly less painful than the Actions web interface.

List workflows:

gh workflow list

Trigger a workflow manually (for workflows with workflow_dispatch):

gh workflow run deploy.yml --field environment=staging

This is particularly useful for deployments and maintenance workflows that you want to trigger from the CLI without navigating the Actions tab.

List recent workflow runs:

gh run list --workflow=ci.yml --limit 10

View run details and logs:

gh run view 12345678
gh run view 12345678 --log

Watch a run in real time:

gh run watch 12345678

This streams the run status and finishes when the run completes. Combine with && to chain actions on success:

gh run watch $(gh run list --limit 1 --json databaseId -q '.[0].databaseId') && echo "CI passed"

Re-run failed jobs:

gh run rerun 12345678 --failed-only

Repository Operations

Clone a repo (shorter than git clone https://github.com/...):

gh repo clone owner/repo

Fork and clone in one command:

gh repo fork owner/repo --clone

View repo info:

gh repo view
gh repo view owner/repo --web  # open in browser

Create a new repo:

gh repo create my-new-project --private --clone

Code Search and Browsing

Search for code across GitHub:

gh search code "TODO: remove before launch" --repo myorg/myrepo

Search for repos:

gh search repos "topic:typescript stars:>1000" --limit 10

Gists

Create a gist from a file:

gh gist create config.json --description "Webpack dev config"

Create a gist from stdin:

cat output.txt | gh gist create - --filename results.txt

List your gists:

gh gist list

Scripting with --json and jq

Every gh command that lists data supports --json for machine-readable output. This makes gh composable with shell scripting.

Get the PR number for the current branch:

gh pr view --json number -q '.number'

List all open PRs with their check status:

gh pr list --json number,title,statusCheckRollup --jq '.[] | "\(.number) \(.title) - \(.statusCheckRollup // "no checks")"'

Get all workflow run IDs that failed in the last week:

gh run list --json databaseId,status,createdAt \
  --jq '[.[] | select(.status == "failure")] | .[].databaseId'

The --jq flag applies a jq expression directly to the JSON output without requiring a separate jq call. If you don’t have jq installed, use --json and pipe to jq separately.

Aliases for Repetitive Commands

gh alias set lets you create shortcuts for commands you use repeatedly:

# Create alias 'prs' for your open PRs
gh alias set prs 'pr list --author @me --state open'

# Now just type:
gh prs

# Alias for merging with standard flags
gh alias set merge-squash 'pr merge --squash --delete-branch'

Aliases are stored in ~/.config/gh/config.yml.

The gh dash Extension

gh extension install dlvhdr/gh-dash installs a terminal dashboard that shows your PRs, issues, and reviews in a navigable TUI. If you review PRs regularly, it’s worth the one-time install. Navigate with arrow keys, open PRs with o, check out locally with c, and diff with d.

Extensions are the main mechanism for community additions to gh — browse available ones with gh extension browse.

Integrating with Your Shell

A few additions that make gh feel native:

Tab completion:

# bash
eval "$(gh completion -s bash)"

# zsh
eval "$(gh completion -s zsh)"

# fish
gh completion -s fish | source

Open the current repo’s GitHub page:

gh repo view --web

Map this to an alias or shell function if you want a quick open-gh command.

What gh Doesn’t Replace

The GitHub CLI is excellent for operations you do repeatedly and want to script or automate. It doesn’t replace the web interface for tasks that benefit from the visual context of the full GitHub UI: complex diff reviews with inline comments from multiple reviewers, project board management, and settings changes that aren’t exposed via the CLI.

For most of the daily PR/issue/CI workflow, though, staying in the terminal and avoiding the context switch to the browser adds up to a meaningful improvement in flow. The key commands — gh pr create, gh pr checkout, gh pr status, gh run watch — cover the majority of the use cases. Start there and expand as the need arises.