AgentSkillsCN

gh-cli-setup

当gh CLI未安装、未配置或认证失败时使用——提供所有平台的安装步骤、认证方法和故障排除

SKILL.md
--- frontmatter
name: gh-cli-setup
description: Use when gh CLI is not installed, not configured, or authentication fails - provides installation steps, authentication methods, and troubleshooting for all platforms

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