GitHub CLI (gh)

GitHub CLI (gh) enables terminal-based interaction with GitHub for managing repositories, issues, pull requests, and releases.

Quick Start

Authentication:

gh auth login          # First-time setup
gh auth status         # Check authentication

Basic operations:

gh repo view                    # View current repository
gh pr list                      # List pull requests
gh issue list                   # List issues
gh pr create                    # Create pull request

Core Workflows

Repository Operations

View repository:

gh repo view OWNER/REPO
gh repo view --web              # Open in browser

Clone and create:

gh repo clone OWNER/REPO
gh repo create my-repo --public
gh repo create my-repo --private --clone

List repositories:

gh repo list                    # Your repos
gh repo list USERNAME           # User's repos
gh repo list --limit 10

Pull Request Workflow

Create PR:

# Interactive
gh pr create

# Direct
gh pr create --title "feat: feature" --body "description"
gh pr create --draft            # Draft PR
gh pr create --base main --head feature-branch

Manage PRs:

gh pr list                      # List PRs
gh pr view PR_NUMBER            # View PR
gh pr checkout PR_NUMBER        # Checkout locally
gh pr merge PR_NUMBER           # Merge PR
gh pr close PR_NUMBER           # Close PR
gh pr review PR_NUMBER --approve # Review

PR status and diff:

gh pr checks PR_NUMBER          # Check status
gh pr diff PR_NUMBER            # View diff
gh pr view PR_NUMBER --web      # Open in browser

Issue Management

Create and list:

gh issue create --title "Bug: title" --body "description"
gh issue list                   # List open issues
gh issue list --state all       # All issues
gh issue list --label "bug"     # Filter by label

Manage issues:

gh issue view ISSUE_NUMBER
gh issue close ISSUE_NUMBER --comment "Fixed"
gh issue reopen ISSUE_NUMBER
gh issue edit ISSUE_NUMBER --title "New title"

Release Management

Create release:

gh release create v1.0.0 --title "v1.0.0" --notes "Release notes"
gh release create v1.0.0 --notes-file CHANGELOG.md
gh release create v1.0.0 --prerelease  # Pre-release
gh release create v1.0.0 dist/*.zip    # With assets

Manage releases:

gh release list
gh release view TAG_NAME
gh release download TAG_NAME
gh release delete TAG_NAME

Configuration

Set editor:

gh config set editor "code -w"  # VS Code
gh config set editor "vim"

Create aliases:

gh alias set prl "pr list"
gh alias set prd "pr create --draft"
gh alias set il "issue list"
gh alias list                  # View aliases

Git credentials:

gh auth setup-git

Advanced Usage

JSON Output and Filtering

JSON output:

gh pr list --json number,title,author
gh repo view --json name,stargazerCount,url
gh issue view ISSUE_NUMBER --json title,body,comments

With jq filtering:

gh pr list --json number,title,author --jq '.[] | select(.author.login == "username")'

Automation Scripts

Create PR script:

#!/bin/bash
BRANCH=$(git branch --show-current)
gh pr create --title "feat: feature" --body "Description" --base main --head "$BRANCH"

Check PR status:

#!/bin/bash
STATUS=$(gh pr view $1 --json state --jq '.state')
echo "PR #$1 status: $STATUS"

Search

gh search repos "language:python stars:>1000"
gh search issues "is:open label:bug"
gh search code "function_name"

Common Patterns

Daily development:

git checkout -b feature/new-feature
git push -u origin feature/new-feature
gh pr create --title "feat: new feature" --body "Description"
# After merge:
git checkout main && git pull && git branch -d feature/new-feature

Review PR:

gh pr list
gh pr view PR_NUMBER
gh pr checkout PR_NUMBER        # Test locally
gh pr review PR_NUMBER --approve

Batch operations:

# Close all open issues (use with caution)
gh issue list --state open --json number --jq '.[].number' | xargs -I {} gh issue close {}

Troubleshooting

Authentication:

gh auth status                 # Check status
gh auth login                  # Re-authenticate
gh auth logout                 # Clear auth

Environment variables:

export GITHUB_TOKEN=your_token  # Linux/Mac
$env:GITHUB_TOKEN="token"      # Windows PowerShell

References

For detailed command reference and advanced workflows, see:

• commands.md - Complete command reference
• workflows.md - Common workflow scenarios