gh-cli-setup

Original：🇺🇸 English
Translated

Use when gh CLI is not installed, not configured, or authentication fails - provides installation steps, authentication methods, and troubleshooting for all platforms

5installs
Sourceaaddrick/gh-cli-search
Added on

NPX Install

npx skill4agent add aaddrick/gh-cli-search gh-cli-setup

Tags

Translated version includes tags in frontmatter
gh-cli-setupauthentication-troubleshootingconfiguration-guidecross-platform-toolsgithub-command-line

SKILL.md Content

View Translation Comparison →

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:

Authentication

Interactive Authentication (Recommended)

bash
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

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

Related