Skip to main content

GitHub CLI

(Terminal-First GitHub Management)

Quick Setup (First Time Only)​

Install GitHub CLI​

# Linux (Debian/Ubuntu)
sudo apt update && sudo apt install gh

# macOS
brew install gh

# Windows
choco install gh
# Or download: https://github.com/cli/cli/releases

Authenticate​

gh auth login                               # Interactive login (HTTPS or SSH)
gh auth status                              # Check current authentication
gh auth logout                              # Sign out

GitHub CLI Commands Cheatsheet​

Repository Basics​

gh repo list                                # List your repositories
gh repo list --public                       # List public repos
gh repo view                                # View current repo info
gh repo clone <owner/repo>                  # Clone a repo
gh repo create <name> --public --clone      # Create & clone new repo
gh repo delete <owner/repo>                 # Delete repository

Browse & Open​

gh browse                                   # Open current repo in browser
gh browse src/app/main.py:42                # Open file at line 42 in browser
gh repo view <owner/repo> --web             # Open specific repo in browser

Issues Management​

gh issue list                               # List open issues
gh issue list -a @me                        # Issues assigned to you
gh issue create --title "Bug" --body "..."  # Create new issue
gh issue create --fill                      # Create with template
gh issue view <number>                      # View issue details
gh issue view <number> --web                # Open issue in browser
gh issue comment <number> -b "Fixed!"       # Comment on issue
gh issue close <number>                     # Close an issue
gh issue close <number> -c "Done!"          # Close with comment
gh issue reopen <number>                    # Reopen issue
gh issue edit <number> --title "New title"  # Edit issue

Pull Requests (Engineering Flow)​

gh pr list                                  # List open PRs
gh pr list -a @me                           # PRs assigned to you
gh pr create --fill                         # Create PR from current branch
gh pr create --title "..." --body "..."     # Create PR with details
gh pr view <number>                         # View PR details
gh pr view <number> --web                   # Open PR in browser
gh pr checkout <number>                     # Checkout PR branch locally
gh pr diff <number>                         # View PR changes
gh pr review <number>                       # Review a PR
gh pr review <number> -a                    # Approve PR
gh pr review <number> -r -b "Needs work"    # Request changes
gh pr merge <number>                        # Merge PR
gh pr merge <number> --squash                # Squash & merge
gh pr merge <number> --delete-branch        # Merge & delete branch
gh pr status                                # Check PR status for your PRs

Git Operations (from Terminal)​

gh git-credential approve                   # Store credentials
gh git-credential reject                    # Remove stored credentials

GitHub Actions & Workflows​

gh run list                                 # List recent workflow runs
gh run list -w <workflow-name>              # List specific workflow runs
gh run view <run-id>                        # View workflow run details
gh run watch <run-id>                       # Watch run in real-time
gh run download <run-id>                    # Download artifacts
gh run rerun <run-id>                       # Rerun a workflow
gh run cancel <run-id>                      # Cancel running workflow

Secrets & Configuration​

gh secret list                              # List repository secrets
gh secret set <NAME> -b "value"             # Set a secret
gh secret remove <NAME>                     # Delete a secret
gh variable list                            # List repository variables
gh variable set <NAME> -b "value"           # Set environment variable

Labels & Projects​

gh label list                               # List issue labels
gh label create <name> --color "FF0000"     # Create label
gh label delete <name>                      # Delete label

Aliases & Shortcuts​

gh alias list                               # List custom aliases
gh alias set <name> "<command>"             # Create alias
gh alias delete <name>                      # Remove alias

Search & Discovery​

gh search repos --language go               # Search for Go repos
gh search issues --label bug                # Search for bug issues
gh search prs --author @me --state merged   # Search your merged PRs

Production GitHub Workflows​

🔀 Engineering Flow: Create PR from Feature Branch​

Scenario: You've pushed feature branch. Create PR with description template.

gh pr create --fill                         # Auto-fill from branch name + template
# Opens editor for title/body if template exists
# Automatically sets reviewers from CODEOWNERS

Why: --fill uses .github/pull_request_template.md if it exists. One command, full context.

✅ Engineering Flow: Review & Merge PR​

Scenario: Check PR status, approve, merge with squash.

gh pr view 45 --web                         # Check PR in browser
gh pr review 45 -a                          # Approve it
gh pr merge 45 --squash --delete-branch     # Squash merge & cleanup

🚀 Automation: Auto-Comment on PRs​

Scenario: Comment on PR automatically (useful in scripts).

gh pr comment 45 -b "Deployed to staging at https://staging.example.com"

Use case: CI/CD pipeline auto-comments with deployment URLs.

🔄 DevOps: Monitor Workflow Runs​

Scenario: Watch deployment workflow in real-time from terminal.

gh run list --limit 1                       # Get latest run
gh run watch <run-id>                       # Stream output live
# Shows: status, job names, step output

Use case: CI/CD monitoring without opening browser.

🔐 Security: Manage Repository Secrets​

Scenario: Set API keys for Actions workflow.

gh secret set STRIPE_API_KEY -b "sk_live_xxx"
gh secret set DATABASE_URL -b "postgres://..."
gh secret list                              # Verify (values hidden)

Why: Centralized secret management without GitHub UI.

GitHub CLI Best Practices​

🎯 Automation-Friendly​

  • Use JSON output (--json) for scripting and piping to other tools
  • Batch operations with loops and conditional logic
  • Integrate into CI/CD workflows for fully automated issue/PR management

⚡ Performance​

  • Use --limit 1 when you only need recent items (faster than full list)
  • Cache credentials with gh auth login for offline access
  • Avoid repeated calls — use --json once, parse multiple times

🔐 Security​

  • Never hardcode tokens — use gh auth login for interactive auth
  • Store secrets properly — use gh secret set, not env files
  • Review gh auth status regularly — ensure you're on correct account

🏗️ Workflows​

  • Create aliases for frequently used commands (gh alias set ...)
  • Use branch names that match PR title for --fill auto-detection
  • Combine with shell scripts for complex multi-step automation

Resources​