gh-cli-setup
Skill9 starsChanged 12 months agoMITView on GitHub
Use when gh CLI is not installed, not configured, or authentication fails - provides installation steps, authentication methods, and troubleshooting for all platforms
- Installs packages
In this repository8 other files it gives its agents.
- gh-search-codeSkill
- gh-search-commitsSkill
- gh-search-issuesSkill
- gh-search-prsSkill
- gh-search-reposSkill
- gh-searchSkill
- testing-gh-skillsSkill
- using-gh-cli-searchSkill
The file
We split this skill into the rules it gives an agent
8 rules. About 0 are common, 7 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 16
Add context about what the command does
- Distinctive: line 17
Do NOT just return a bare command without explanation
- Distinctive: line 21
Use this skill when:
- Distinctive: line 30
Run these commands to check status:
- Distinctive: line 184
Cause: Not logged in to GitHub
- Distinctive: line 331
When gh CLI isn't working, check these in order:
- Very specific: line 358
Public repos/issues/PRs: No authentication required (but rate limited)
- Distinctive: line 365
Create tokens at: https://github.com/settings/tokens
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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:
ghcommand 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-tokenInstallation
macOS
Using Homebrew (recommended):
brew install ghUsing MacPorts:
sudo port install ghUsing Conda:
conda install gh --channel conda-forgeLinux
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 -yFedora/CentOS/RHEL:
sudo dnf install ghArch Linux:
sudo pacman -S github-cliUsing Snap:
sudo snap install ghUsing Conda:
conda install gh --channel conda-forgeWindows
Using WinGet:
winget install --id GitHub.cliUsing Scoop:
scoop install ghUsing Chocolatey:
choco install ghUsing Conda:
conda install gh --channel conda-forgeManual Download:
- Download MSI installer from: https://cli.github.com/
Authentication
Interactive Authentication (Recommended)
gh auth loginThis will prompt you to:
- Choose GitHub.com or GitHub Enterprise Server
- Choose authentication method (Web browser or Token)
- 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 loginCheck Authentication
# Verify authentication status
gh auth status
# View authenticated user
gh api user --jq '.login'
# Test API access
gh api rate_limitCommon 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 statusError: "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/tokensError: "HTTP 401: Bad credentials"
Cause: Token expired or invalid
Solution:
# Logout and re-authenticate
gh auth logout
gh auth loginError: "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 accountError: "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.comConfiguration
View Configuration
# View all config settings
gh config list
# View specific setting
gh config get git_protocolCommon 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.comConfig 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 statusDebugging
Enable Debug Mode
# Run command with debug output
GH_DEBUG=api gh search repos "test"
# Or for all commands
export GH_DEBUG=apiView Request/Response
# See HTTP requests and responses
gh api repos/owner/repo --verboseCheck Version
# View gh version
gh --version
# Check for updates
gh extension upgrade --allTroubleshooting 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
reposcope - Organization repos: Requires
read:orgscope - Workflow files: Requires
workflowscope
Token Scopes
Create tokens at: https://github.com/settings/tokens
Minimal scopes for search:
public_repo- Search public repositoriesrepo- Search private repositoriesread:org- Search organization repositories
Recommended scopes:
repo- Full repository accessread:org- Organization accessworkflow- Workflow accessgist- Gist access
Uninstallation
macOS
brew uninstall ghLinux
# Debian/Ubuntu
sudo apt remove gh
# Fedora/CentOS/RHEL
sudo dnf remove gh
# Arch
sudo pacman -R github-cliWindows
# WinGet
winget uninstall GitHub.cli
# Scoop
scoop uninstall gh
# Chocolatey
choco uninstall ghRelated
- 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
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

