gh-cli-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

GitHub CLI Setup & Troubleshooting

GitHub CLI 安装配置与故障排查

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

本技能可帮助诊断并修复GitHub CLI（

gh

）的安装、配置及认证问题。

重要提示：提供安装说明时，请务必：

说明推荐的安装方式（例如：“在macOS上推荐使用Homebrew安装”）
提供具体命令
提及替代安装方法
补充命令的作用说明
请勿仅返回裸命令而不做任何解释

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

在以下场景中使用本技能：

```
gh
```
命令未找到
出现认证错误
gh CLI运行异常
需要检查gh CLI配置
首次设置gh CLI

Quick Diagnostic

快速诊断

Run these commands to check status:

bash

undefined

运行以下命令检查状态：

bash

undefined

Check if gh is installed

检查gh是否已安装

which gh

Check gh version

检查gh版本

gh --version

Check authentication status

检查认证状态

gh auth status

List authenticated accounts

列出已认证账号

gh auth status --show-token

undefined

gh auth status --show-token

undefined

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

推荐使用Homebrew安装：

bash

brew install gh

使用MacPorts安装：

bash

sudo port install gh

使用Conda安装：

bash

conda install gh --channel conda-forge

Linux

Debian/Ubuntu/Raspbian:

bash

undefined

Debian/Ubuntu/Raspbian系统：

bash

undefined

Add GitHub CLI repository

添加GitHub CLI仓库

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

sudo apt update sudo apt install gh -y


**Fedora/CentOS/RHEL系统：**
```bash
sudo dnf install gh

Arch Linux系统：

bash

sudo pacman -S github-cli

使用Snap安装：

bash

sudo snap install gh

使用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/

使用WinGet安装：

powershell

winget install --id GitHub.cli

使用Scoop安装：

powershell

scoop install gh

使用Chocolatey安装：

powershell

choco install gh

使用Conda安装：

bash

conda install gh --channel conda-forge

手动下载安装：

从以下链接下载MSI安装包：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

bash

gh auth login

执行后将引导您完成以下步骤：

选择GitHub.com或GitHub Enterprise Server
选择认证方式（浏览器或令牌）
完成认证流程

Token Authentication

令牌认证

bash

undefined

bash

undefined

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

在以下地址创建令牌：https://github.com/settings/tokens

Required scopes: repo, read:org, workflow

必填权限范围：repo, read:org, workflow

Authenticate with token

使用令牌完成认证

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

Or paste token when prompted

或在提示时粘贴令牌

gh auth login

undefined

gh auth login

undefined

Check Authentication

认证状态检查

bash

undefined

bash

undefined

Verify authentication status

验证认证状态

gh auth status

View authenticated user

查看已认证用户

gh api user --jq '.login'

Test API access

测试API访问权限

gh api rate_limit

undefined

gh api rate_limit

undefined

Common Errors & Solutions

常见错误与解决方案

Error: "gh: command not found"

错误："gh: command not found"

Cause: gh CLI not installed or not in PATH

Solution:

bash

undefined

原因： gh CLI未安装或未添加至系统PATH

解决方案：

bash

undefined

Check if gh is installed

检查gh是否已安装

which gh

If not found, install (see Installation section above)

若未找到，请参考上方安装章节进行安装

If installed but not in PATH, add to PATH

若已安装但未在PATH中，将其添加至PATH

For bash/zsh, add to ~/.bashrc or ~/.zshrc:

对于bash/zsh，添加至~/.bashrc或~/.zshrc：

export PATH="/path/to/gh/bin:$PATH"

undefined

export PATH="/path/to/gh/bin:$PATH"

undefined

Error: "authentication required"

错误："authentication required"

Cause: Not logged in to GitHub

Solution:

bash

undefined

原因： 未登录GitHub账号

解决方案：

bash

undefined

Login interactively

交互式登录

gh auth login

Or check authentication status

或检查认证状态

gh auth status

undefined

gh auth status

undefined

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

错误："HTTP 403: Resource not accessible by integration"

Cause: Insufficient token permissions

Solution:

bash

undefined

原因： 令牌权限不足

解决方案：

bash

undefined

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

undefined

undefined

Error: "HTTP 401: Bad credentials"

错误："HTTP 401: Bad credentials"

Cause: Token expired or invalid

Solution:

bash

undefined

原因： 令牌过期或无效

解决方案：

bash

undefined

Logout and re-authenticate

登出后重新认证

gh auth logout gh auth login

undefined

gh auth logout gh auth login

undefined

Error: "API rate limit exceeded"

错误："API rate limit exceeded"

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

Solution:

bash

undefined

原因： API请求次数超限（未认证时60次/小时，已认证时5000次/小时）

解决方案：

bash

undefined

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

等待速率限制重置或切换至其他账号

undefined

undefined

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

错误："Could not resolve host: github.com"

Cause: Network connectivity issue

Solution:

bash

undefined

原因： 网络连接问题

解决方案：

bash

undefined

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

检查DNS解析

nslookup github.com

undefined

nslookup github.com

undefined

Configuration

配置管理

View Configuration

查看配置

bash

undefined

bash

undefined

View all config settings

查看所有配置项

gh config list

View specific setting

查看指定配置项

gh config get git_protocol

undefined

gh config get git_protocol

undefined

Common Settings

常用配置项

bash

undefined

bash

undefined

Set default protocol (https or ssh)

设置默认协议（https或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

设置GitHub Enterprise主机地址

gh config set host github.enterprise.com

undefined

gh config set host github.enterprise.com

undefined

Config File Locations

配置文件位置

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

Linux/macOS：
```
~/.config/gh/config.yml
```
Windows：
```
%AppData%\GitHub CLI\config.yml
```

Multiple Accounts

多账号管理

bash

undefined

bash

undefined

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

undefined

gh auth status

undefined

Debugging

调试方法

Enable Debug Mode

启用调试模式

bash

undefined

bash

undefined

Run command with debug output

运行命令时输出调试信息

GH_DEBUG=api gh search repos "test"

Or for all commands

或为所有命令启用调试

export GH_DEBUG=api

undefined

export GH_DEBUG=api

undefined

View Request/Response

查看请求/响应详情

bash

undefined

bash

undefined

See HTTP requests and responses

查看HTTP请求与响应内容

gh api repos/owner/repo --verbose

undefined

gh api repos/owner/repo --verbose

undefined

Check Version

检查版本

bash

undefined

bash

undefined

View gh version

查看gh版本

gh --version

Check for updates

检查更新

gh extension upgrade --all

undefined

gh extension upgrade --all

undefined

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
```
)

当gh CLI无法正常工作时，请按以下顺序检查：

是否已安装gh？（执行
```
which gh
```
）
gh是否已添加至PATH？（执行
```
echo $PATH
```
| grep gh）
是否已完成认证？（执行
```
gh auth status
```
）
令牌是否具备所需权限范围？
网络连接是否正常？（执行
```
ping github.com
```
）
是否触发API速率限制？（执行
```
gh api rate_limit
```
）
gh版本是否为最新？（执行
```
gh --version
```
）
配置项是否正确？（执行
```
gh config list
```
）

Getting Help

获取帮助

bash

undefined

bash

undefined

Get help for any command

查看任意命令的帮助信息

gh help gh search --help gh search repos --help

View manual online

在线查看官方手册

https://cli.github.com/manual/

undefined

undefined

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

不同类型的搜索需要不同的权限：

公开仓库/议题/PR： 无需认证（但受速率限制）
私有仓库： 需要
```
repo
```
权限范围
组织仓库： 需要
```
read:org
```
权限范围
工作流文件： 需要
```
workflow
```
权限范围

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

在以下地址创建令牌：https://github.com/settings/tokens

搜索功能最小权限范围：

```
public_repo
```
- 搜索公开仓库
```
repo
```
- 搜索私有仓库
```
read:org
```
- 搜索组织仓库

推荐权限范围：

```
repo
```
- 完整仓库访问权限
```
read:org
```
- 组织访问权限
```
workflow
```
- 工作流访问权限
```
gist
```
- Gist访问权限

Uninstallation

卸载方法

macOS

bash

brew uninstall gh

bash

brew uninstall gh

Linux

bash

undefined

bash

undefined

Debian/Ubuntu

Debian/Ubuntu系统

sudo apt remove gh

Fedora/CentOS/RHEL

Fedora/CentOS/RHEL系统

sudo dnf remove gh

Arch

Arch系统

sudo pacman -R github-cli

undefined

sudo pacman -R github-cli

undefined

Windows

powershell

undefined

powershell

undefined

WinGet

WinGet卸载

winget uninstall GitHub.cli

Scoop

Scoop卸载

scoop uninstall gh

Chocolatey

Chocolatey卸载

choco uninstall gh

undefined

choco uninstall gh

undefined