GitHub CLI - Complete Guide to Command Line Interface

GitHub CLI (gh) is the official command-line tool for GitHub that brings the power of GitHub directly to your terminal. It allows you to manage repositories, pull requests, issues, and more without leaving your command line environment.

This comprehensive guide covers everything you need to know about GitHub CLI, from installation to advanced workflows and automation.

Introduction to GitHub CLI

GitHub CLI extends your Git workflow by providing commands for:

• Repository management (create, clone, fork)
• Pull request operations (create, review, merge)
• Issue management (create, list, close)
• GitHub Actions workflow management
• Release management
• Gist operations
• And much more

Key Benefits:

• Work entirely from terminal
• Automate GitHub workflows
• Integrate with scripts and tools
• Faster than web interface for many operations
• Consistent interface across platforms

Use Cases:

• Quick repository operations
• Automated workflows and scripts
• CI/CD integration
• Bulk operations
• Development workflow automation

Installation

Windows

Using winget:

winget install --id GitHub.cli

Using Chocolatey:

choco install gh

Using Scoop:

scoop install gh

Manual Installation:

1. Download from github.com/cli/cli/releases
2. Run installer
3. Verify: gh --version

macOS

Using Homebrew:

brew install gh

Using MacPorts:

sudo port install gh

Linux

Debian/Ubuntu:

curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null
sudo apt update
sudo apt install gh

Fedora/RHEL:

sudo dnf install 'dnf-command(config-manager)'
sudo dnf config-manager --add-repo https://cli.github.com/packages/rpm/gh-cli.repo
sudo dnf install gh

Arch Linux:

sudo pacman -S github-cli

Verify Installation

gh --version

Should display version information.

Authentication

Initial Authentication

First-time setup requires authentication:

gh auth login

Interactive Setup:

1. Choose GitHub.com or GitHub Enterprise
2. Select authentication method:
   • HTTPS (recommended): Uses personal access token
   • SSH: Uses SSH keys
3. Choose protocol (HTTPS or Git)
4. Authenticate via web browser or token

Authentication Methods

Browser Authentication (easiest):

gh auth login --web

Opens browser for OAuth authentication.

Token Authentication:

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

Create token at: github.com/settings/tokens

Required Token Scopes:

• repo - Full repository access
• workflow - GitHub Actions workflows
• read:org - Read organization data (if needed)

Check Authentication Status

gh auth status

Switch Accounts

gh auth login --hostname github.com

Logout

gh auth logout

Repository Management

Create Repository

Create new repository:

gh repo create my-new-repo

With options:

gh repo create my-repo \
  --public \
  --description "My repository description" \
  --clone

Options:

• --public / --private - Repository visibility
• --description - Repository description
• --clone - Clone after creation
• --source - Create from existing directory
• --remote - Add as remote

Clone Repository

gh repo clone owner/repo-name

Clone to specific directory:

gh repo clone owner/repo-name my-directory

View Repository

gh repo view owner/repo-name

View in browser:

gh repo view --web

Fork Repository

gh repo fork owner/repo-name

Clone fork:

gh repo fork owner/repo-name --clone

List Repositories

Your repositories:

gh repo list

Organization repositories:

gh repo list organization-name

Filter by language:

gh repo list --language JavaScript

Limit results:

gh repo list --limit 10

Repository Settings

View settings:

gh repo view owner/repo-name --json name,description,isPrivate

Edit repository:

gh repo edit owner/repo-name --description "New description"

Pull Requests

Create Pull Request

From current branch:

gh pr create

With title and body:

gh pr create --title "My PR Title" --body "PR description"

Interactive creation:

gh pr create --web

Opens browser for PR creation.

List Pull Requests

Open PRs:

gh pr list

All PRs:

gh pr list --state all

By author:

gh pr list --author username

By label:

gh pr list --label bug

View Pull Request

gh pr view 123

View in browser:

gh pr view 123 --web

View diff:

gh pr diff 123

Checkout Pull Request

gh pr checkout 123

Creates local branch from PR.

Review Pull Request

Approve:

gh pr review 123 --approve

Request changes:

gh pr review 123 --request-changes --body "Comments"

Comment:

gh pr review 123 --comment --body "Comments"

Merge Pull Request

gh pr merge 123

Merge options:

gh pr merge 123 --squash
gh pr merge 123 --rebase
gh pr merge 123 --merge

Delete branch after merge:

gh pr merge 123 --delete-branch

Close Pull Request

gh pr close 123

Issues Management

Create Issue

gh issue create

With title and body:

gh issue create --title "Bug title" --body "Bug description"

With labels:

gh issue create --title "Bug" --body "Description" --label bug

Interactive creation:

gh issue create --web

List Issues

Open issues:

gh issue list

All issues:

gh issue list --state all

By author:

gh issue list --author username

By label:

gh issue list --label bug

By assignee:

gh issue list --assignee username

View Issue

gh issue view 123

View in browser:

gh issue view 123 --web

Close Issue

gh issue close 123

With comment:

gh issue close 123 --comment "Fixed in PR #456"

Reopen Issue

gh issue reopen 123

Add Comments

gh issue comment 123 --body "My comment"

Assign Issues

gh issue edit 123 --add-assignee username

GitHub Actions Workflows

List Workflows

gh workflow list

View Workflow

gh workflow view workflow-name

View in browser:

gh workflow view workflow-name --web

Run Workflow

gh workflow run workflow-name

With inputs:

gh workflow run workflow-name --field key=value

View Workflow Runs

gh run list

View specific run:

gh run view 1234567890

View in browser:

gh run view 1234567890 --web

Watch Workflow Run

gh run watch 1234567890

Download Workflow Logs

gh run download 1234567890

Advanced Features

Aliases

Create command aliases:

gh alias set prc "pr create"
gh alias set prl "pr list"

Use alias:

gh prc

Extensions

GitHub CLI supports extensions:

List extensions:

gh extension list

Install extension:

gh extension install owner/extension-name

Create extension:

gh extension create my-extension

API Access

Use GitHub API directly:

gh api repos/owner/repo

With query parameters:

gh api repos/owner/repo --jq '.name'

Gists

Create gist:

gh gist create file.txt

List gists:

gh gist list

View gist:

gh gist view gist-id

Releases

List releases:

gh release list

Create release:

gh release create v1.0.0

View release:

gh release view v1.0.0

Configuration

Set default editor:

gh config set editor vim

Set default browser:

gh config set browser firefox

View configuration:

gh config list

Best Practices

Workflow Integration

1. Use in scripts: Automate repetitive tasks
2. CI/CD integration: Use in GitHub Actions
3. Local automation: Create helper scripts
4. Team workflows: Standardize on gh commands

Security

1. Token management: Use secure token storage
2. SSH keys: Prefer SSH for Git operations
3. Scope permissions: Use minimum required scopes
4. Regular updates: Keep gh updated

Productivity Tips

1. Use aliases: Create shortcuts for common commands
2. Combine commands: Chain operations
3. Use filters: Narrow down results efficiently
4. Leverage JSON output: Parse with jq for automation

Common Workflows

Quick PR creation:

gh pr create --fill --web

Review and merge:

gh pr checkout 123
# Review code
gh pr review 123 --approve
gh pr merge 123 --squash --delete-branch

Issue triage:

gh issue list --label "needs-triage" --limit 10
gh issue view 123
gh issue edit 123 --add-label "bug" --add-assignee @me

Conclusion

GitHub CLI is a powerful tool that brings GitHub functionality to your terminal. Key benefits:

• Faster workflows: No context switching to browser
• Automation: Integrate with scripts and tools
• Consistency: Same interface across platforms
• Power: Full GitHub API access

Master these commands:

• Repository management
• Pull request operations
• Issue management
• Workflow automation
• Advanced features

With GitHub CLI, you can manage your entire GitHub workflow from the command line, making development more efficient and streamlined.