GitHub CLI

Git Tools•

•Go

Official GitHub command-line tool.

Official Website

Features

PR ManagementIssue ManagementGitHub ActionsRepository Management

Installation

Homebrew

brew install gh

APT (Debian/Ubuntu)

apt install gh

Pacman (Arch)

pacman -S github-cli

Chocolatey

choco install gh

Why use gh?

gh is GitHub's official command-line interface. You can perform GitHub operations (PR creation, issue management, repository operations, etc.) directly from the terminal without opening a browser.

PR Management

Create, review, and merge pull requests from the command line. Speeds up development flow.

Issue Management

Create, search, and close issues from the terminal. Handle bug reports and feature requests quickly.

GitHub Actions

Manage workflows, check logs, and manage cache from CLI. Streamline CI/CD management.

Repository Operations

Clone, create, fork, and archive repositories with commands.

Installation

# macOS (Homebrew)
brew install gh

# Ubuntu/Debian
type -p curl >/dev/null || sudo apt install curl -y
curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
sudo chmod go+r /usr/share/keyrings/githubcli-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null
sudo apt update
sudo apt install gh

# Fedora
sudo dnf install gh

# Arch Linux
sudo pacman -S github-cli

# Windows (Chocolatey)
choco install gh

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

Authentication

Authentication with your GitHub account is required on first use.

Authentication

# Authenticate interactively (recommended)
gh auth login

# Check authentication status
gh auth status

# Authenticate with token
gh auth login --with-token < token.txt

# Authenticate to GitHub Enterprise Server
gh auth login --hostname enterprise.example.com

# Refresh authentication
gh auth refresh

# Logout
gh auth logout

Repository Operations

Clone & Create

# Clone repository (auto-select HTTPS/SSH)
gh repo clone owner/repo
gh repo clone https://github.com/owner/repo

# Create new repository
gh repo create my-new-repo --public
gh repo create my-new-repo --private --description "My awesome project"

# Create current directory as repository
gh repo create --source=. --public

# Fork existing repository
gh repo fork owner/repo
gh repo fork owner/repo --clone  # Clone after fork

Repository Info

# Show repository information
gh repo view
gh repo view owner/repo

# Open repository in browser
gh repo view --web

# List repositories
gh repo list
gh repo list --limit 50
gh repo list owner --source  # Exclude forks

# Search repositories
gh repo list --json name,description --jq '.[] | select(.description | contains("api"))'

Pull Request Operations

Create PR

# Create PR interactively
gh pr create

# Create with title and body
gh pr create --title "Add new feature" --body "This PR adds..."

# Create draft PR
gh pr create --draft

# Specify base branch
gh pr create --base main

# Specify reviewers
gh pr create --reviewer user1,user2

# Add labels
gh pr create --label "bug,priority:high"

# Auto-close issue
gh pr create --body "Fixes #123"

List & Review PRs

# List PRs in current repository
gh pr list
gh pr list --state open
gh pr list --state closed
gh pr list --state merged

# PRs I'm involved in
gh pr list --author @me
gh pr list --assignee @me
gh pr list --reviewer @me

# Show PR details
gh pr view 123
gh pr view --web  # Open in browser

# Show PR diff
gh pr diff 123

# Check PR status
gh pr checks 123

Checkout & Merge PRs

Checkout & Merge

# Checkout PR locally
gh pr checkout 123
gh pr checkout feature-branch

# Merge PR
gh pr merge 123
gh pr merge 123 --squash  # Squash merge
gh pr merge 123 --rebase  # Rebase merge
gh pr merge 123 --delete-branch  # Delete branch after merge

# Approve PR
gh pr review 123 --approve
gh pr review 123 --approve --body "LGTM!"

# Request changes on PR
gh pr review 123 --request-changes --body "Please fix..."

# Close PR
gh pr close 123

Issue Operations

Create Issue

# Create issue interactively
gh issue create

# Create with title and body
gh issue create --title "Bug report" --body "Description..."

# Add labels and assign
gh issue create --label "bug" --assignee @me

# Use template
gh issue create --template bug_report.md

List & Manage Issues

Manage Issues

# List issues
gh issue list
gh issue list --state open
gh issue list --state closed
gh issue list --label "bug"

# Issues assigned to me
gh issue list --assignee @me

# Show issue details
gh issue view 123
gh issue view 123 --web

# Close issue
gh issue close 123
gh issue close 123 --comment "Fixed in PR #456"

# Reopen issue
gh issue reopen 123

# Edit issue
gh issue edit 123 --add-label "priority:high"
gh issue edit 123 --add-assignee user1

GitHub Actions Operations

GitHub Actions

# List workflows
gh workflow list

# Manually run workflow
gh workflow run deploy.yml
gh workflow run deploy.yml --ref main
gh workflow run deploy.yml -f environment=production

# List workflow runs
gh run list
gh run list --workflow=deploy.yml
gh run list --status failure

# Show run details
gh run view 123456789
gh run view 123456789 --web

# Show run logs
gh run view 123456789 --log
gh run view 123456789 --log-failed  # Only failed jobs

# Cancel run
gh run cancel 123456789

# Rerun
gh run rerun 123456789
gh run rerun 123456789 --failed  # Only failed jobs

# Download artifacts
gh run download 123456789

Gist Operations

# Create gist
gh gist create file.txt
gh gist create file1.txt file2.txt  # Multiple files
gh gist create --public file.txt  # Public gist
gh gist create -d "Description" file.txt

# Create gist from stdin
echo "Hello World" | gh gist create -

# List gists
gh gist list

# View gist
gh gist view <gist-id>

# Edit gist
gh gist edit <gist-id>

# Delete gist
gh gist delete <gist-id>

# Clone gist
gh gist clone <gist-id>

API Access

Call GitHub API directly with gh api command.

API Access

# Get user information
gh api user

# Get repository information
gh api repos/owner/repo

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

# Filter with jq
gh api repos/owner/repo/issues --jq '.[].title'

# POST request
gh api repos/owner/repo/issues -f title="New issue" -f body="Description"

# Pagination
gh api repos/owner/repo/issues --paginate --jq '.[].title'

Configuration & Customization

Config Commands

Configuration

# List configuration
gh config list

# Set default editor
gh config set editor vim

# Set default browser
gh config set browser firefox

# Set default PR merge behavior
gh config set git_protocol ssh  # Use SSH

# Set alias
gh alias set pv 'pr view'
gh alias set co 'pr checkout'

# List aliases
gh alias list

# Delete alias
gh alias delete pv

Useful Alias Examples

Alias Examples

# Common aliases
gh alias set prc 'pr create --fill'  # Auto-fill title/body
gh alias set prm 'pr merge --squash --delete-branch'
gh alias set mypr 'pr list --author @me'
gh alias set review 'pr list --reviewer @me'
gh alias set web 'repo view --web'

# Complex alias (shell command)
gh alias set clone-org 'api orgs/$1/repos --paginate --jq ".[].ssh_url" | xargs -n1 git clone'

Collaboration Features

Collaboration

# Create codespace
gh codespace create
gh codespace create --repo owner/repo --branch main

# List codespaces
gh codespace list

# Connect to codespace
gh codespace ssh
gh codespace code  # Open in VS Code

# Project operations
gh project list
gh project view 1

# Release operations
gh release create v1.0.0
gh release create v1.0.0 --generate-notes
gh release create v1.0.0 ./dist/*  # Attach files
gh release list
gh release download v1.0.0

Tips & Tricks

*Use --help flag to show command help. Example: gh pr create --help
*--json flag for JSON output, --jq for filtering
*Many commands support --web flag to open in browser
*Use gh browse to open current repository in browser
*@me is a shortcut for the currently logged-in user
*gh supports extensions. Use gh extension browse to explore community extensions

lazygit - Terminal UI for Git

Simple terminal UI for git commands

tools10 min read

gitui - Fast Git TUI

Blazing fast terminal-ui for git in Rust

tools8 min read

Explore More

Browse Git Tools

See all tools in this category

All CLI Tools

Explore all tool categories

Features

Installation

Why use gh?

PR Management

Issue Management

GitHub Actions

Repository Operations

Installation

Authentication

Repository Operations

Clone & Create

Repository Info

Pull Request Operations

Create PR

List & Review PRs

Checkout & Merge PRs

Issue Operations

Create Issue

List & Manage Issues

GitHub Actions Operations

Gist Operations

API Access

Configuration & Customization

Config Commands

Useful Alias Examples

Collaboration Features

Tips & Tricks

Related Articles

lazygit - Terminal UI for Git

gitui - Fast Git TUI

Explore More