GitHub CLI (gh)

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

Quick Start

Authentication:

bash
1gh auth login          # First-time setup
2gh auth status         # Check authentication

Basic operations:

bash
1gh repo view                    # View current repository
2gh pr list                      # List pull requests
3gh issue list                   # List issues
4gh pr create                    # Create pull request

Core Workflows

Repository Operations

View repository:

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

Clone and create:

bash
1gh repo clone OWNER/REPO
2gh repo create my-repo --public
3gh repo create my-repo --private --clone

List repositories:

bash
1gh repo list                    # Your repos
2gh repo list USERNAME           # User's repos
3gh repo list --limit 10

Pull Request Workflow

Create PR:

bash
1# Interactive
2gh pr create
3
4# Direct
5gh pr create --title "feat: feature" --body "description"
6gh pr create --draft            # Draft PR
7gh pr create --base main --head feature-branch

Manage PRs:

bash
1gh pr list                      # List PRs
2gh pr view PR_NUMBER            # View PR
3gh pr checkout PR_NUMBER        # Checkout locally
4gh pr merge PR_NUMBER           # Merge PR
5gh pr close PR_NUMBER           # Close PR
6gh pr review PR_NUMBER --approve # Review

PR status and diff:

bash
1gh pr checks PR_NUMBER          # Check status
2gh pr diff PR_NUMBER            # View diff
3gh pr view PR_NUMBER --web      # Open in browser

Issue Management

Create and list:

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

Manage issues:

bash
1gh issue view ISSUE_NUMBER
2gh issue close ISSUE_NUMBER --comment "Fixed"
3gh issue reopen ISSUE_NUMBER
4gh issue edit ISSUE_NUMBER --title "New title"

Release Management

Create release:

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

Manage releases:

bash
1gh release list
2gh release view TAG_NAME
3gh release download TAG_NAME
4gh release delete TAG_NAME

Configuration

Set editor:

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

Create aliases:

bash
1gh alias set prl "pr list"
2gh alias set prd "pr create --draft"
3gh alias set il "issue list"
4gh alias list                  # View aliases

Git credentials:

bash
1gh auth setup-git

Advanced Usage

JSON Output and Filtering

JSON output:

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

With jq filtering:

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

Automation Scripts

Create PR script:

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

Check PR status:

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

Search

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

Common Patterns

Daily development:

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

Review PR:

bash
1gh pr list
2gh pr view PR_NUMBER
3gh pr checkout PR_NUMBER        # Test locally
4gh pr review PR_NUMBER --approve

Batch operations:

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

Troubleshooting

Authentication:

bash
1gh auth status                 # Check status
2gh auth login                  # Re-authenticate
3gh auth logout                 # Clear auth

Environment variables:

bash
1export GITHUB_TOKEN=your_token  # Linux/Mac
2$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