github cli（gh）是github官方推出的命令行工具，用于在终端中高效管理仓库、议题、pr等协作资源，需安装并登录后使用，支持与git协同、结构化输出及高级工作流集成。
如果您希望在不离开终端的情况下高效操作 GitHub 仓库、议题、拉取请求等资源，则需要借助 GitHub 命令行工具。GitHub Command 指的是 GitHub CLI（gh），它是 GitHub 官方推出的开源命令行界面工具，专为与 GitHub 平台深度集成而设计。以下是对其核心用途与使用方式的详细说明：
一、GitHub CLI 的本质与定位
GitHub CLI 是一个独立于 Git 命令行的工具，其可执行文件名为 gh，并非 git 的子命令或别名。它直接调用 GitHub API，实现对 GitHub 特有功能（如 Issues、Pull Requests、Actions、Gists、Codespaces）的原生支持。与仅管理代码版本的 git 不同，gh 管理的是 GitHub 上的协作上下文。
1、GitHub CLI 不替代 git，而是与其协同工作：执行 gh pr create 后，仍需使用 git push 上传分支；
2、所有 gh 命令均以 gh 开头，后接子命令（如 repo、issue、pr、run）；
3、命令输出默认为简洁文本格式，支持 --json、--jq 等参数进行结构化处理，便于脚本集成。
二、安装与身份验证配置
GitHub CLI 必须完成安装与登录才能执行任何需权限的操作。未认证状态下，多数命令将返回 401 错误或提示登录。安装过程因操作系统而异，但验证流程统一。
1、在 macOS 上通过 Homebrew 安装：brew install gh；
2、在 Windows 上通过 Scoop 安装：scoop install gh；
3、运行 gh auth login，按提示选择 GitHub.com 或企业版实例；
4、选择 HTTPS 协议后，工具会自动打开浏览器完成 OAuth 授权，并将令牌安全存储至系统凭据管理器；
5、验证是否成功：gh api user 应返回当前用户 JSON 数据。
三、核心资源操作命令详解
GitHub CLI 将高频协作对象抽象为子命令域，每个域提供 list、view、create、update 等标准动词。操作范围可显式指定（如 --repo OWNER/REPO），也可在已克隆仓库目录中自动推断。
1、查看当前账户下所有公开仓库：gh repo list --limit 20；
2、在本地目录中创建并推送新仓库：gh repo create my-project --public --source=. --push；
3、列出当前仓库中所有打开的 issue：gh issue list --state open；
本文档主要讲述的是github协同工作教程；文中将以gitchinaui项目为例进行讲解。git有命令行和图形工具，强烈推荐你用命令行工具。希望本文对大家会有帮助；感兴趣的朋友可以过来看看
4、基于当前分支快速创建 PR：gh pr create --title "Add dark mode toggle" --body "Closes #42"；
5、查看最近一次工作流运行日志：gh run list --limit 1 | gh run view。
四、高级工作流集成技巧
GitHub CLI 支持嵌套调用与管道组合，可替代大量网页操作。其设计目标是让开发者在终端内完成端到端协作闭环，避免上下文切换损耗。
1、一键复刻并克隆上游仓库：gh repo fork cli/cli && gh repo clone cli/cli；
2、将 issue 转换为 PR（需先 checkout 对应分支）：gh issue convert 123 --branch fix-login-bug；
3、批量关闭已合并的 PR：gh pr list --state merged --json number -q '.[]' | xargs -I{} gh pr close {}；
4、在 codespace 中直接打开 VS Code：gh codespace code --browser；
5、使用 Copilot 辅助生成命令：gh copilot suggest "list all issues assigned to me with label 'bug'"。
五、调试与状态诊断方法
当命令行为异常（如权限拒绝、仓库未识别、API 限流）时，GitHub CLI 提供多层级诊断机制。启用调试模式可暴露完整 HTTP 请求与响应，便于定位网络或认证问题。
1、启用详细日志输出：gh --verbose repo view；
2、检查当前认证状态：gh auth status，确认主机名、用户名及令牌有效期；
3、手动刷新令牌（适用于过期或权限不足）：gh auth refresh --scopes repo,read:org,user；
4、查看当前配置项：gh config get -h github.com；
5、重置全部配置并重新登录：gh auth logout && gh auth login。
