GitHub CLI Setup & Troubleshooting

Overview

This skill helps diagnose and fix GitHub CLI (gh) installation, configuration, and authentication issues.

IMPORTANT: When providing installation instructions, always:

• Explain the recommended method (e.g., "Homebrew is the recommended way to install on macOS")
• Provide the actual command
• Mention alternative installation methods
• Add context about what the command does
• Do NOT just return a bare command without explanation

When to Use

Use this skill when:

• gh command not found
• Authentication errors occur
• gh CLI behaves unexpectedly
• Need to check gh CLI configuration
• Setting up gh CLI for first time

Quick Diagnostic

Run these commands to check status:

# Check if gh is installed
which gh

# Check gh version
gh --version

# Check authentication status
gh auth status

# List authenticated accounts
gh auth status --show-token

Installation

macOS

Using Homebrew (recommended):

brew install gh

Using MacPorts:

sudo port install gh

Using Conda:

conda install gh --channel conda-forge

Linux

Debian/Ubuntu/Raspbian:

# Add GitHub CLI repository
type -p curl >/dev/null || (sudo apt update && sudo apt install curl -y)
curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
sudo chmod go+r /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

# Install
sudo apt update
sudo apt install gh -y

Fedora/CentOS/RHEL:

sudo dnf install gh

Arch Linux:

sudo pacman -S github-cli

Using Snap:

sudo snap install gh

Using Conda:

conda install gh --channel conda-forge

Windows

Using WinGet:

winget install --id GitHub.cli

Using Scoop:

scoop install gh

Using Chocolatey:

choco install gh

Using Conda:

conda install gh --channel conda-forge

Manual Download:

• Download MSI installer from: https://cli.github.com/

Authentication

Interactive Authentication (Recommended)

gh auth login

This will prompt you to:

1. Choose GitHub.com or GitHub Enterprise Server
2. Choose authentication method (Web browser or Token)
3. Complete authentication flow

Token Authentication

# Create token at: https://github.com/settings/tokens
# Required scopes: repo, read:org, workflow

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

# Or paste token when prompted
gh auth login

Check Authentication

# Verify authentication status
gh auth status

# View authenticated user
gh api user --jq '.login'

# Test API access
gh api rate_limit

Common Errors & Solutions

Error: "gh: command not found"

Cause: gh CLI not installed or not in PATH

Solution:

# Check if gh is installed
which gh

# If not found, install (see Installation section above)

# If installed but not in PATH, add to PATH
# For bash/zsh, add to ~/.bashrc or ~/.zshrc:
export PATH="/path/to/gh/bin:$PATH"

Error: "authentication required"

Cause: Not logged in to GitHub

Solution:

# Login interactively
gh auth login

# Or check authentication status
gh auth status

Error: "HTTP 403: Resource not accessible by integration"

Cause: Insufficient token permissions

Solution:

# Re-authenticate with proper scopes
gh auth login --scopes repo,read:org,workflow

# Or create new token with required scopes:
# https://github.com/settings/tokens

Error: "HTTP 401: Bad credentials"

Cause: Token expired or invalid

Solution:

# Logout and re-authenticate
gh auth logout
gh auth login

Error: "API rate limit exceeded"

Cause: Too many API requests (60/hour unauthenticated, 5000/hour authenticated)

Solution:

# Check rate limit status
gh api rate_limit

# Authenticate to get higher limit (if not already)
gh auth login

# Wait for rate limit reset or use different account

Error: "Could not resolve host: github.com"

Cause: Network connectivity issue

Solution:

# Check internet connection
ping github.com

# Check proxy settings if behind corporate firewall
gh config set http_proxy http://proxy.example.com:8080

# Check DNS resolution
nslookup github.com

Configuration

View Configuration

# View all config settings
gh config list

# View specific setting
gh config get git_protocol

Common Settings

# Set default protocol (https or ssh)
gh config set git_protocol https

# Set default editor
gh config set editor vim

# Set default browser
gh config set browser firefox

# Set proxy
gh config set http_proxy http://proxy.example.com:8080

# Set GitHub Enterprise host
gh config set host github.enterprise.com

Config File Locations

• Linux/macOS: ~/.config/gh/config.yml
• Windows: %AppData%\GitHub CLI\config.yml

Multiple Accounts

# Login to multiple hosts
gh auth login --hostname github.com
gh auth login --hostname github.enterprise.com

# Switch between accounts
gh auth switch

# Check which account is active
gh auth status

Debugging

Enable Debug Mode

# Run command with debug output
GH_DEBUG=api gh search repos "test"

# Or for all commands
export GH_DEBUG=api

View Request/Response

# See HTTP requests and responses
gh api repos/owner/repo --verbose

Check Version

# View gh version
gh --version

# Check for updates
gh extension upgrade --all

Troubleshooting Checklist

When gh CLI isn't working, check these in order:

• [ ] Is gh installed? (which gh)
• [ ] Is gh in PATH? (echo $PATH | grep gh)
• [ ] Is gh authenticated? (gh auth status)
• [ ] Does token have required scopes?
• [ ] Is network connectivity working? (ping github.com)
• [ ] Is rate limit exceeded? (gh api rate_limit)
• [ ] Is gh version up to date? (gh --version)
• [ ] Are config settings correct? (gh config list)

Getting Help

# Get help for any command
gh help
gh search --help
gh search repos --help

# View manual online
# https://cli.github.com/manual/

Permissions Required for Search

Different search types require different permissions:

• Public repos/issues/PRs: No authentication required (but rate limited)
• Private repos: Requires repo scope
• Organization repos: Requires read:org scope
• Workflow files: Requires workflow scope

Token Scopes

Create tokens at: https://github.com/settings/tokens

Minimal scopes for search:

• public_repo - Search public repositories
• repo - Search private repositories
• read:org - Search organization repositories

Recommended scopes:

• repo - Full repository access
• read:org - Organization access
• workflow - Workflow access
• gist - Gist access

Uninstallation

macOS

brew uninstall gh

Linux

# Debian/Ubuntu
sudo apt remove gh

# Fedora/CentOS/RHEL
sudo dnf remove gh

# Arch
sudo pacman -R github-cli

Windows

# WinGet
winget uninstall GitHub.cli

# Scoop
scoop uninstall gh

# Chocolatey
choco uninstall gh

Related

• Official documentation: https://cli.github.com/manual/
• Installation guide: https://github.com/cli/cli#installation
• Authentication guide: https://cli.github.com/manual/gh_auth_login
• For using gh search: gh-search-code, gh-search-commits, gh-search-issues, gh-search-prs, gh-search-repos