GitHub CLI (gh)

Website: https://cli.github.com CLI Tool: gh Authentication: GitHub account, tokens

Description

GitHub CLI (gh) brings GitHub to your terminal. Work with issues, pull requests, repositories, and other GitHub features from the command line. Essential for developers who prefer terminal workflows and automation scripts.

Commands

Authentication

gh auth login
gh auth login --web
gh auth login --with-token < token.txt

Authenticate with GitHub.

Logout

gh auth logout

Log out of GitHub.

Status

gh auth status

Show authentication status.

Setup Git

gh auth setup-git

Configure git to use gh for authentication.

Repository Management

Create Repository

gh repo create <name>
gh repo create my-project --public
gh repo create my-project --private
gh repo create my-project --clone

Create new GitHub repository.

Clone Repository

gh repo clone <repo>
gh repo clone owner/repo
gh repo clone https://github.com/owner/repo

Clone repository.

Fork Repository

gh repo fork
gh repo fork owner/repo
gh repo fork owner/repo --clone

Fork repository.

View Repository

gh repo view
gh repo view owner/repo
gh repo view owner/repo --web

View repository details.

List Repositories

gh repo list
gh repo list owner
gh repo list --limit 50

List repositories.

Archive Repository

gh repo archive <repo>
gh repo archive owner/repo

Archive repository.

Delete Repository

gh repo delete <repo>
gh repo delete owner/repo --confirm

Delete repository.

Issues

Create Issue

gh issue create
gh issue create --title "Bug report" --body "Description"
gh issue create -t "Title" -b "Body" -l bug,urgent

Create new issue.

List Issues

gh issue list
gh issue list --state open
gh issue list --label bug
gh issue list --author username
gh issue list --assignee @me

List issues.

View Issue

gh issue view <number>
gh issue view 123
gh issue view 123 --web

View issue details.

Close Issue

gh issue close <number>
gh issue close 123 --comment "Fixed in v1.2"

Close issue.

Reopen Issue

gh issue reopen <number>

Reopen closed issue.

Edit Issue

gh issue edit <number>
gh issue edit 123 --title "New title"
gh issue edit 123 --add-label enhancement
gh issue edit 123 --remove-label bug

Edit issue.

Comment on Issue

gh issue comment <number>
gh issue comment 123 --body "Thanks for reporting!"

Add comment to issue.

Pull Requests

Create PR

gh pr create
gh pr create --title "Add feature" --body "Description"
gh pr create -t "Title" -b "Body" -B main
gh pr create --fill

Create pull request.

List PRs

gh pr list
gh pr list --state open
gh pr list --author username
gh pr list --base main

List pull requests.

View PR

gh pr view <number>
gh pr view 456
gh pr view 456 --web

View PR details.

Checkout PR

gh pr checkout <number>
gh pr checkout 456

Check out PR branch locally.

Review PR

gh pr review <number>
gh pr review 456 --approve
gh pr review 456 --request-changes -b "Needs tests"
gh pr review 456 --comment -b "Looks good"

Review pull request.

Merge PR

gh pr merge <number>
gh pr merge 456 --merge
gh pr merge 456 --squash
gh pr merge 456 --rebase
gh pr merge 456 --delete-branch

Merge pull request.

Close PR

gh pr close <number>
gh pr close 456 --comment "Not ready"

Close pull request.

Reopen PR

gh pr reopen <number>

Reopen closed PR.

PR Status

gh pr status

Show status of relevant PRs.

PR Checks

gh pr checks <number>
gh pr checks 456 --watch

View CI checks status.

PR Diff

gh pr diff <number>
gh pr diff 456 --patch

View PR diff.

Comment on PR

gh pr comment <number>
gh pr comment 456 --body "LGTM!"

Add comment to PR.

Ready for Review

gh pr ready <number>

Mark draft PR as ready for review.

Releases

Create Release

gh release create <tag>
gh release create v1.0.0
gh release create v1.0.0 --title "Version 1.0" --notes "Release notes"
gh release create v1.0.0 dist/*.zip

Create release with assets.

List Releases

gh release list
gh release list --limit 10

List releases.

View Release

gh release view <tag>
gh release view v1.0.0
gh release view v1.0.0 --web

View release details.

Download Assets

gh release download <tag>
gh release download v1.0.0
gh release download v1.0.0 --pattern '*.zip'

Download release assets.

Delete Release

gh release delete <tag>
gh release delete v1.0.0 --yes

Delete release.

Upload Assets

gh release upload <tag> <files>
gh release upload v1.0.0 dist/*.zip

Upload assets to existing release.

Gists

Create Gist

gh gist create <file>
gh gist create file.txt --public
gh gist create file.txt --desc "Description"

Create gist from file.

List Gists

gh gist list
gh gist list --public
gh gist list --secret

List your gists.

View Gist

gh gist view <id>
gh gist view abc123def456
gh gist view abc123def456 --web

View gist content.

Edit Gist

gh gist edit <id>
gh gist edit abc123def456 --add file.txt

Edit gist.

Delete Gist

gh gist delete <id>

Delete gist.

Workflows (Actions)

List Workflows

gh workflow list

List GitHub Actions workflows.

View Workflow

gh workflow view <workflow>
gh workflow view ci.yml
gh workflow view ci.yml --web

View workflow details.

Run Workflow

gh workflow run <workflow>
gh workflow run ci.yml
gh workflow run ci.yml --ref branch-name

Trigger workflow run.

List Runs

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

List workflow runs.

View Run

gh run view <run-id>
gh run view 123456789
gh run view 123456789 --web
gh run view 123456789 --log

View run details and logs.

Watch Run

gh run watch <run-id>

Watch run in real-time.

Rerun

gh run rerun <run-id>
gh run rerun 123456789 --failed

Rerun workflow.

Cancel Run

gh run cancel <run-id>

Cancel workflow run.

Download Artifacts

gh run download <run-id>
gh run download 123456789 --name artifact-name

Download run artifacts.

API

Make API Request

gh api <endpoint>
gh api /user
gh api /repos/{owner}/{repo}/issues
gh api /repos/owner/repo/issues -X POST -f title="Bug" -f body="Description"

Make authenticated API requests.

GraphQL Query

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

Execute GraphQL query.

Aliases

Create Alias

gh alias set <alias> <command>
gh alias set pv 'pr view'
gh alias set issues 'issue list --assignee @me'

Create command alias.

List Aliases

gh alias list

List all aliases.

Delete Alias

gh alias delete <alias>

Delete alias.

Configuration

Set Config

gh config set <key> <value>
gh config set editor vim
gh config set git_protocol ssh
gh config set prompt enabled

Set configuration value.

Get Config

gh config get <key>
gh config get editor

Get configuration value.

List Config

gh config list

List all configuration.

Extensions

Install Extension

gh extension install <repo>
gh extension install owner/gh-extension

Install gh extension.

List Extensions

gh extension list

List installed extensions.

Upgrade Extensions

gh extension upgrade <extension>
gh extension upgrade --all

Upgrade extensions.

Remove Extension

gh extension remove <extension>

Remove extension.

Search

Search Repositories

gh search repos <query>
gh search repos "machine learning" --language python
gh search repos "web framework" --stars ">1000"

Search GitHub repositories.

Search Issues

gh search issues <query>
gh search issues "bug" --repo owner/repo
gh search issues "feature request" --state open

Search issues.

Search PRs

gh search prs <query>
gh search prs "fix" --author username
gh search prs "update" --state merged

Search pull requests.

Search Code

gh search code <query>
gh search code "function" --repo owner/repo
gh search code "TODO" --language javascript

Search code.

Examples

Daily Workflow

# Check status
gh auth status
gh pr status

# View assigned issues
gh issue list --assignee @me

# Create branch and PR
git checkout -b feature-branch
# ... make changes ...
git commit -am "Add feature"
git push -u origin feature-branch
gh pr create --fill

# Review PR
gh pr checkout 123
gh pr review 123 --approve

Issue Management

# Create issue with labels
gh issue create \
  --title "Add dark mode" \
  --body "We need dark mode support" \
  --label enhancement,ui \
  --assignee @me

# List open bugs
gh issue list --label bug --state open

# Close issue with comment
gh issue close 42 --comment "Fixed in #43"

# Search issues
gh search issues "performance" --repo owner/repo --state open

PR Workflows

# Create PR with reviewers
gh pr create \
  --title "Fix authentication bug" \
  --body "Fixes #123" \
  --base main \
  --reviewer alice,bob \
  --label bug

# Check PR status and CI
gh pr status
gh pr checks 456 --watch

# Review and merge
gh pr review 456 --approve --body "LGTM"
gh pr merge 456 --squash --delete-branch

# List your PRs
gh pr list --author @me --state open

Release Management

# Create release with assets
gh release create v2.0.0 \
  --title "Version 2.0.0" \
  --notes "Major release with new features" \
  dist/*.tar.gz \
  dist/*.zip

# View latest release
gh release view --web

# Download release assets
gh release download v2.0.0 --pattern "*.zip" --dir ./downloads

# Update release notes
gh release edit v2.0.0 --notes "Updated release notes"

CI/CD Automation

# Trigger workflow
gh workflow run deploy.yml --ref main

# Watch workflow run
gh run list --workflow=deploy.yml --limit 1
gh run watch $(gh run list --workflow=deploy.yml --limit 1 --json databaseId --jq '.[0].databaseId')

# Download artifacts
gh run download --name build-artifacts

# Rerun failed jobs
gh run rerun $(gh run list --workflow=test.yml --limit 1 --json databaseId --jq '.[0].databaseId') --failed

Repository Setup

# Create and setup new repo
gh repo create my-project --public --clone
cd my-project
echo "# My Project" > README.md
git add README.md
git commit -m "Initial commit"
git push -u origin main

# Fork and clone
gh repo fork popular-project/repo --clone
cd repo
git remote -v

# View repo in browser
gh repo view --web

API Usage

# Get user info
gh api /user | jq .

# List repo issues
gh api /repos/owner/repo/issues --paginate | jq '.[] | {number, title, state}'

# Create issue via API
gh api /repos/owner/repo/issues -X POST \
  -f title="Bug report" \
  -f body="Description of bug" \
  -f labels='["bug","urgent"]'

# GraphQL query
gh api graphql -f query='
  query {
    viewer {
      repositories(first: 5) {
        nodes { name stargazerCount }
      }
    }
  }
'

Bulk Operations

# Close multiple issues
for issue in 1 2 3 4 5; do
  gh issue close $issue --comment "Closing old issues"
done

# Add label to multiple PRs
for pr in $(gh pr list --json number -q '.[].number'); do
  gh pr edit $pr --add-label reviewed
done

# Download all release assets
for tag in $(gh release list --json tagName -q '.[].tagName'); do
  gh release download $tag --dir ./releases/$tag
done

Notes

Authentication: OAuth token stored securely
Default Repo: Commands work in git repo context
Aliases: Create shortcuts for common commands
Output Format: Supports JSON output with --json flag
JQ Template: Use --jq for JSON parsing
Pagination: Use --paginate for API requests
Web Mode: Use --web to open in browser
Interactive: Most commands have interactive mode
Extensions: Extend functionality with community extensions
API Access: Full GitHub API v3/v4 access via gh api
GraphQL: Native GraphQL support
Draft PRs: Create with --draft flag
PR Templates: Respects .github templates
Issue Templates: Supports issue templates
Workflow Triggers: Can trigger workflow_dispatch events
Artifacts: Download workflow artifacts
Secrets: Cannot read secrets (security)
Caching: Caches API responses for performance
Rate Limiting: Respects GitHub API rate limits
Enterprise: Works with GitHub Enterprise Server
SSH vs HTTPS: Respects git protocol preference
Best Practices:
Use aliases for frequent commands
Leverage JSON output for scripting
Use --web to open in browser quickly
Create PRs with meaningful templates
Review PRs with gh pr checkout
Use extensions for extra features
Authenticate with SSH for better security

gh