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:

bash

# 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):

bash

brew install gh

Using MacPorts:

bash

sudo port install gh

Using Conda:

bash

conda install gh --channel conda-forge

Linux

Debian/Ubuntu/Raspbian:

bash

# 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:

bash

sudo dnf install gh

Arch Linux:

bash

sudo pacman -S github-cli

Using Snap:

bash

sudo snap install gh

Using Conda:

bash

conda install gh --channel conda-forge

Windows

Using WinGet:

powershell

winget install --id GitHub.cli

Using Scoop:

powershell

scoop install gh

Using Chocolatey:

powershell

choco install gh

Using Conda:

bash

conda install gh --channel conda-forge

Manual Download:

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

Authentication

Interactive Authentication (Recommended)

bash

gh auth login

This will prompt you to:

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

Token Authentication

bash

# 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

bash

# 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:

bash

# 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:

bash

# 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:

bash

# 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:

bash

# 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:

bash

# 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:

bash

# 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

bash

# View all config settings
gh config list

# View specific setting
gh config get git_protocol

Common Settings

bash

# 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

bash

# 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

bash

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

# Or for all commands
export GH_DEBUG=api

View Request/Response

bash

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

Check Version

bash

# 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

bash

# 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

bash

brew uninstall gh

Linux

bash

# Debian/Ubuntu
sudo apt remove gh

# Fedora/CentOS/RHEL
sudo dnf remove gh

# Arch
sudo pacman -R github-cli

Windows

powershell

# WinGet
winget uninstall GitHub.cli

# Scoop
scoop uninstall gh

# Chocolatey
choco uninstall gh

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

gh-cli-setup

NPX Install

Tags

SKILL.md Content

GitHub CLI Setup & Troubleshooting

Overview

When to Use

Quick Diagnostic

Installation

macOS

Linux

Windows

Authentication

Interactive Authentication (Recommended)

Token Authentication

Check Authentication

Common Errors & Solutions

Error: "gh: command not found"

Error: "authentication required"

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

Error: "HTTP 401: Bad credentials"

Error: "API rate limit exceeded"

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

Configuration

View Configuration

Common Settings

Config File Locations

Multiple Accounts

Debugging

Enable Debug Mode

View Request/Response

Check Version

Troubleshooting Checklist

Getting Help

Permissions Required for Search

Token Scopes

Uninstallation

macOS

Linux

Windows

Related