GitHub CLI

GitHub CLI cheatsheet — create PRs, issues, releases, trigger workflows. gh pr create, gh pr merge, gh issue list, gh workflow run. Full GitHub CLI reference.

8 min read

What it is

The GitHub CLI (gh) is a command-line tool for interacting with GitHub, allowing you to manage repositories, pull requests, issues, releases, and more directly from your terminal.

Installation

Linux

# For Debian/Ubuntu based systems
sudo apt update
sudo apt install gh

# For Fedora/RHEL/CentOS based systems
sudo dnf install gh
# or
sudo yum install gh

# Using Homebrew (if installed)
brew install gh

macOS

# Using Homebrew
brew install gh

Windows

# Using Chocolatey
choco install gh

# Using Scoop
scoop install gh

# Using Homebrew (if installed via Linuxbrew/macOS Homebrew on Windows)
brew install gh

Core Concepts

Authentication: gh uses OAuth tokens to authenticate with GitHub. You’ll typically do this once when you first run gh auth login.
Repository Context: Many commands operate within the context of a Git repository. gh can often infer the current repository from your local Git configuration. If not, you can specify it using the -R flag.

Commands / Usage

Authentication

# Log in to GitHub, prompts for protocol (HTTPS/SSH) and authentication method
gh auth login

# List authenticated accounts and their scopes
gh auth status

# Log out of GitHub
gh auth logout

Repository Management

# Clone a repository
gh repo clone cli/cli

# Create a new repository
# Creates a public repository named 'my-new-project' in your default organization/user
gh repo create my-new-project --public

# Create a private repository
gh repo create my-private-project --private

# Create a repository from a local directory
# Creates a repository named 'my-local-repo' from the current directory
gh repo create my-local-repo --source=. --private

# View information about a repository
gh repo view cli/cli

# List your repositories
gh repo list

# List repositories you've starred
gh repo list --starred

# Fork a repository
gh repo fork cli/cli

# View a repository's collaborators
gh repo list-collaborators cli/cli

# Add a collaborator to a repository
gh repo deploy-key add deploy.pub --repository cli/cli --title "My Deploy Key"

# Remove a collaborator from a repository
gh repo remove-collaborator cli/cli --username octocat

# Star a repository
gh repo star cli/cli

# Unstar a repository
gh repo unstar cli/cli

# Watch a repository
gh repo watch cli/cli

# Unwatch a repository
gh repo unwatch cli/cli

Pull Requests

# List pull requests for the current repository
gh pr list

# List open pull requests for a specific repository
gh pr list --state open --repo cli/cli

# View a pull request
gh pr view 123

# View a pull request with its diff
gh pr view 123 --web

# Create a pull request from the current branch to the default branch
# Prompts for title and body
gh pr create

# Create a pull request with a specific base branch
gh pr create --base main --head feature/new-thing

# Create a pull request with a title and body
gh pr create --title "Add new feature" --body "This PR adds the amazing new feature."

# Checkout a pull request locally
gh pr checkout 123

# Merge a pull request
gh pr merge 123

# Merge a pull request with a squash merge
gh pr merge 123 --squash

# Close a pull request
gh pr close 123

# Reopen a closed pull request
gh pr reopen 123

# Assign users to a pull request
gh pr edit 123 --assignee @me,monalisa

# Add labels to a pull request
gh pr edit 123 --add-label "bug", "documentation"

# Remove labels from a pull request
gh pr edit 123 --remove-label "enhancement"

# Request reviews for a pull request
gh pr review --request octocat,monalisa 123

# Approve a pull request
gh pr review --approve 123

# Comment on a pull request
gh pr comment 123 --body "Looks good, but one small change needed."

Issues

# List issues for the current repository
gh issue list

# List open issues for a specific repository
gh issue list --state open --repo cli/cli

# View an issue
gh issue view 456

# View an issue with its comments in the web browser
gh issue view 456 --web

# Create a new issue
# Prompts for title and body
gh issue create

# Create an issue with a specific title and body
gh issue create --title "Fix broken link" --body "The link on the homepage is broken."

# Create an issue and assign yourself
gh issue create --title "Investigate performance" --body "High latency observed." --assignee @me

# Close an issue
gh issue close 456

# Reopen a closed issue
gh issue reopen 456

# Assign users to an issue
gh issue edit 456 --assignee @me,monalisa

# Add labels to an issue
gh issue edit 456 --add-label "bug", "priority"

# Remove labels from an issue
gh issue edit 456 --remove-label "enhancement"

# Comment on an issue
gh issue comment 456 --body "I'll take a look at this."

Releases

# List releases for the current repository
gh release list

# View a specific release
gh release view v1.0.0

# Create a new release
# Prompts for tag name, title, and body
gh release create

# Create a release with a specific tag name and body
gh release create v1.1.0 --title "Version 1.1.0" --notes "Added new features and fixed bugs."

# Create a release from an existing tag
gh release create v1.2.0 --notes "Minor bug fixes."

# Upload assets to a release
gh release upload v1.0.0 my-asset.zip

# Upload assets to a release with a specific content type
gh release upload v1.0.0 my-app.exe --contentType application/octet-stream

# Edit a release
gh release edit v1.0.0 --title "Updated Release Title"

# Delete a release
gh release delete v1.0.0

Workflows (GitHub Actions)

# List workflows for the current repository
gh workflow list

# View details of a specific workflow
gh workflow view ci.yml

# Enable a workflow
gh workflow enable ci.yml

# Disable a workflow
gh workflow disable ci.yml

# Run a workflow dispatch
gh workflow run ci.yml --ref main --inputs "key=value"

# List workflow runs
gh run list

# View a specific workflow run
gh run view <run-id>

# View the logs for a workflow run
gh run watch <run-id>

Gists

# List your gists
gh gist list

# View a gist
gh gist view abc123def456

# Create a gist from a file
gh gist create my-file.txt

# Create a gist from multiple files
gh gist create file1.txt file2.md

# Create a public gist
gh gist create --public my-public-file.txt

# Delete a gist
gh gist delete abc123def456

Aliases

# List configured aliases
gh alias list

# Set a new alias
gh alias set list-prs 'pr list --state open'

# Remove an alias
gh alias delete list-prs

Configuration

# View gh configuration
gh config list

# Set a configuration value
gh config set git_protocol ssh

# Unset a configuration value
gh config unset git_protocol

Other Useful Commands

# Display version information
gh --version

# Show help for gh
gh --help

# Show help for a specific command
gh pr --help

# Open the current repository in the browser
gh repo browse

# Open the current issue in the browser
gh issue browse

# Open the current pull request in the browser
gh pr browse

Common Patterns

Working with Pull Requests from the Command Line

View all open PRs and their status:
```
gh pr list --state open
```

Checkout and view the diff of the latest PR:

gh pr checkout $(gh pr list --state open --limit 1 --json number | jq -r '.[0].number')
gh pr diff

Merge a PR and clean up the branch:
```
gh pr merge 123 --delete-branch
```

Assign yourself to all open PRs:

gh pr list --state open --json number | jq -r '.[].number' | xargs -I {} gh pr edit {} --assignee @me

Working with Issues from the Command Line

Create an issue and assign it to yourself:

gh issue create --title "Bug in login flow" --body "Users cannot log in using Google OAuth." --assignee @me

List all issues assigned to you:
```
gh issue list --assignee @me
```

Automating with `jq`

gh often outputs JSON, which is powerful when combined with jq for advanced filtering and processing.

Get the number of the latest open PR:

gh pr list --state open --json number --limit 1 | jq '.[0].number'

Get titles of all open PRs:

gh pr list --state open --json title | jq '.[].title'

Working with Remote Repositories

List all remotes configured for the current repo:

gh repo list --json name,owner,fork,parent | jq '.[] | select(.fork == false) | .name'

Clone a fork of a repository:

OWNER="octocat"
REPO="Spoon-Knife"
gh repo clone "$OWNER/$REPO"

Gotchas

Repository Context: If you’re not in a Git repository directory, gh might not be able to infer the repository. Use the -R owner/repo flag explicitly in such cases.
Authentication Scopes: Ensure your token has the necessary scopes for the actions you want to perform. If a command fails with a permission error, check your scopes via gh auth status.
--web Flag: Many commands have a --web flag that opens the corresponding page in your browser. This is incredibly useful for quickly navigating to review or edit.
jq Dependency: While gh can output JSON, you’ll need jq installed separately for advanced JSON processing.
Default Branch vs. Current Branch: gh pr create by default creates a PR from your current branch to the default branch of the repository. If you need to target a different base branch, use --base.