GitHub CLI：把整个 GitHub 搬进终端和 Agent

Fen9Pi2026/9/16大约 5 分钟

前言

很多人装了 gh（GitHub CLI），用法停留在两个：gh pr list 和 gh pr create。偶尔回 GitHub 网页点两下，感觉 gh 是个可有可无的补充。

翻一遍 gh 的官方手册，会发现格局完全不对：gh 是把整个 GitHub 平台搬进终端的官方通道——PR、Issue、Actions、Projects、Codespaces、Release、Secret，全在命令行里。而且 2026 年的手册里出现了两个新信号：gh agent-task 和 gh skill——GitHub 官方把 Agent 也接进了这条通道。

手册：https://cli.github.com/manual/
仓库：https://github.com/cli/cli

一、项目身份

是什么：GitHub 官方命令行工具，在终端或脚本里操作 GitHub
定位一句话：git 管的是你本地的代码，gh 管的是 GitHub 平台上的一切
企业支持：GitHub Enterprise Server 2.20+，gh auth login --hostname 接私有实例"
手册结构本身就有信息量：30+ 个命令组，从 auth 到 workflow，最上面两个"Getting started"级别的入口是 gh 和 gh agent-task——Agent 任务已经和根命令并列

二、核心模块：30+ 命令组的分层地图

手册上的命令组看起来吓人，但按功能一收，就五层：

流程图1

几个模块值得单独说。

gh api 是逃生舱。所有官方命令没覆盖到的 REST 端点，gh api 直连——不用自己搞 token、拼 curl、处理分页。这意味着 gh 的能力边界其实等于 GitHub API 的边界。

gh pr 是最厚的一组。checkout（把别人的 PR 拉到本地）、checks（盯 CI 状态）、diff、review、merge、update-branch——一个 PR 的完整生命周期不用碰浏览器。gh pr status 一条命令汇总"等我 review 的、我打开的、提到我的"三张清单。

Actions 模块是脚本党的最爱。gh run watch 终端里盯流水线，gh run download 拉产物，gh workflow run 手动触发，配合 secret/variable 管理，CI 的日常操作全在 shell 里闭环。

gh project 是被低估的一组。Projects（表格/看板）的增删改查、字段管理、item 操作都有——项目管理数据也能脚本化了。

三、主执行链路：从安装到自动化

流程图2

三条使用形态值得展开：交互式日常、脚本自动化（gh 原生支持 --json 输出结构化数据、--jq 服务端过滤，这是它比网页强的根本原因——GitHub 的状态变成了可以管道处理的数据）、以及新出现的 Agent 形态。

四、跨端边界

平台端：github.com + GitHub Enterprise Server 2.20+（GH_HOST 指定默认主机，GH_ENTERPRISE_TOKEN 供脚本认证）
系统端：macOS/Linux/Windows 全平台，输出适配终端（gh help mintty 连 Mintty 的兼容问题都有专门文档）
Agent 端（2026 新边界）：gh agent-task create/list/view 让 Agent 领任务干活；gh skill install/search/publish 管理 Agent Skills——gh 正在成为"人"和"Agent"共用同一条 GitHub 通道的地方
与 git 的边界：gh auth setup-git 把 gh 的凭证接给 git，clone/push 走 git，平台操作走 gh——各管一段，不重叠

五、数据与状态流

流程图3

关键认知：gh 让 GitHub 的状态从"网页里的信息"变成可管道处理的流。gh pr list --json number,title,headRefName --jq '.[] | ...' 这类组合，是所有 GitHub 自动化脚本的起点。

六、配置边界

gh 的配置面刻意做得很小：

认证：gh auth login（交互）或 GITHUB_TOKEN / GH_ENTERPRISE_TOKEN（脚本）——两条路，没有第三种
偏好：gh config get/set，最常用的是 editor；环境变量可覆盖大部分行为（详见 gh help environment）
别名：gh alias set 自定义高频组合，还能 gh alias import 批量导入
宿主：GH_HOST 切企业实例默认值

没有守护进程、没有本地数据库、没有后台状态——gh 是无状态的壳，所有真状态都在 GitHub 服务端。这让它在 CI 环境里几乎零成本。

七、扩展点

gh api：终极扩展——任何 REST 端点直连，官方命令没做的自己拼
gh extension：社区扩展体系（gh extension browse/install/exec/upgrade），Go/Python/Shell 写的二进制或脚本挂成 gh xxx 子命令
gh alias：轻量扩展——不改代码，组合现有命令
gh skill：Agent Skills 的安装、搜索、发布进了官方 CLI——GitHub 在给 Agent 生态修轨道
gh agent-task：把"给 Agent 派活"变成一等公民命令，可 create、list、view 追踪

八、风险点

token 权限即天花板。GITHUB_TOKEN 权限给太大，脚本一处注入就全盘暴露；给太小，自动化跑到一半 403。最小权限 + 按仓库限定，是底线
非交互模式的错误处理容易被忽略。gh help exit-codes 专门有文档——脚本里不检查退出码，自动化会静默烂掉
扩展是第三方代码。gh extension install 装的东西在你的终端环境里跑，供应链安全自己把关
API 限流。高频轮询 gh api（尤其 CI 里每分钟查 PR 状态）会撞 rate limit，脚本要加退避
agent-task/skill 还是新东西。手册里部分命令组还挂着 preview 标签，接口可能变，生产自动化别急着深度依赖

记住

gh 的正确打开方式不是"网页的替代品"，而是把 GitHub 变成数据流：--json 拿结构化输出，--jq 服务端过滤，管道接你的脚本。
记住三个逃生舱：gh api 直连任意端点，gh extension 挂社区能力，gh alias 组合高频操作。
新信号值得盯：gh agent-task 和 gh skill——人和 Agent 正在共用同一条 GitHub 通道。

参考资源

手册：https://cli.github.com/manual/
仓库：https://github.com/cli/cli
社区扩展：https://github.com/topics/gh-extension