告别浏览器限制用 GitHub CLI 的 gh api 命令直连 REST 与 GraphQL API 深度指南【免费下载链接】cliGitHub’s official command line tool项目地址: https://gitcode.com/GitHub_Trending/cli/cliGitHub CLI 的gh api命令让开发者无需打开浏览器就能直接在终端发起已认证的 GitHub REST APIv3与 GraphQL APIv4请求。它是官方命令行工具中最灵活的一把万能钥匙一条命令即可完成查询、创建、嵌套参数、自动分页和 JSON 过滤把浏览器里繁琐的点击操作变成可复用的脚本。本指南面向新手带你从零掌握gh api的核心用法。 为什么需要 gh api 命令GitHub 的大部分命令如gh pr list、gh issue view已经覆盖了日常操作但总有场景需要直达底层调用官方尚未封装的高级接口如项目 v2、自定义属性编写自动化脚本批量处理仓库数据探索 API 返回的完整 JSON 结构gh api帮你绕开浏览器和 curl 手动拼 token 的麻烦自动复用gh auth login的登录态并输出美观的彩色 JSON。 命令定义位于 pkg/cmd/api/api.go并在主命令中注册pkg/cmd/root/root.go 快速上手第一条已认证请求最简单的用法是给出一个 API 路径# 查看当前登录用户等价于浏览器访问 /user gh api /user # 列出当前仓库的 Releases gh api repos/{owner}/{repo}/releases占位符魔法{owner}、{repo}、{branch}会自动替换为当前目录所在仓库的信息无需手敲仓库名。这个替换逻辑实现在 pkg/cmd/api/api.go 的fillPlaceholders函数中。官方验收测试可直观看到两种请求的最小形态REST 示例acceptance/testdata/api/basic-rest.txtarGraphQL 示例acceptance/testdata/api/basic-graphql.txtar REST API 实战参数、方法与请求体gh api默认使用 GET 请求一旦添加参数会自动切换为 POST见 pkg/cmd/api/api.go。常用参数组合场景命令发一条 Issue 评论gh api repos/{owner}/{repo}/issues/123/comments -f bodyHi from CLIGET 请求带查询参数gh api -X GET search/issues -f qrepo:cli/cli is:open remote从文件读取嵌套参数gh api gists -F files[myfile.txt][content]myfile.txt用 JSON 文件作请求体gh api repos/{owner}/{repo}/rulesets --input file.json-f与-F的区别解析逻辑在 pkg/cmd/api/fields.go-fraw-field值一律按字符串处理-Ffield带类型魔法——true/false/null和整数自动转为对应 JSON 类型文件语法从文件读取值-从标准输入读取嵌套参数支持key[subkey]value与数组语法key[]value1, key[]value2例如更新深层嵌套的自定义属性值gh api -X PATCH /orgs/{org}/properties/schema \ -F properties[][property_name]environment \ -F properties[][default_value]production GraphQL API一条命令直连 v4 接口在路径参数中写graphql即可访问 GraphQL 端点除query外的所有字段会被自动归入 GraphQL 变量见 pkg/cmd/api/http.gogh api graphql -F owner{owner} -F name{repo} -f query query($name: String!, $owner: String!) { repository(owner: $owner, name: $name) { releases(last: 3) { nodes { tagName } } } } 比 REST 更适合一次性精确取数——字段全由你自己指定不多不少。 分页详解--paginate 与 --slurp数据量超过一页时手动翻页是最痛苦的部分gh api内置了解决方案REST--paginate会解析响应的Link头自动请求下一页实现见 pkg/cmd/api/pagination.go并自动追加per_page100提高效率各页 JSON 数组会被无缝拼成一个连续数组输出GraphQL查询需声明$endCursor: String变量并取回pageInfo { hasNextPage, endCursor }--paginate会解析游标findEndCursorpkg/cmd/api/pagination.go继续请求--slurp把所有页包进一个外层 JSON 数组方便交给jq做跨页统计# 拉取用户全部仓库的 fork 占比 gh api graphql --paginate --slurp -f query... | jq ...✂️ 输出过滤只留你需要的字段原始 JSON 动辄上千行两个内置参数让你所见即所得# 用 jq 语法只提取标题列表 gh api repos/{owner}/{repo}/issues --jq .[].title # 用 Go 模板渲染自定义表格 gh api repos/{owner}/{repo}/issues --template \ {{range .}}{{.title}} ({{.labels | pluck name | join , }}){{\n}}{{end}}过滤结果适合直接管道给其他工具实现完整的终端自动化工作流其他实用开关定义见 pkg/cmd/api/api.go参数作用-i, --include输出状态行和响应头便于调试--verbose打印完整 HTTP 请求与响应-H Accept: ...自定义请求头-p, --preview启用实验性 API 预览版本--cache 1h缓存响应 1 小时降低 API 配额消耗--silent只看状态码不打印响应体 相关源码与文档路径想深入阅读实现推荐从以下文件入手命令主逻辑与全部标志位pkg/cmd/api/api.go参数解析与类型转换pkg/cmd/api/fields.goHTTP 请求构造pkg/cmd/api/http.go分页游标解析pkg/cmd/api/pagination.go项目整体文档目录docs/❓ 常见问题速答Q1提示 403 或权限不足怎么办gh api复用gh auth登录态若 token 权限不够输出会附带授权建议错误处理逻辑见 pkg/cmd/api/api.go。重新gh auth refresh -s repo,read:org补充权限即可。Q2Windows 上报invalid API endpointPowerShell 可能把带前导斜杠的路径改写成磁盘路径去掉开头的/即可该检查位于 pkg/cmd/api/api.go。Q3能访问非 github.com 的实例吗可以用--hostname或环境变量GH_HOST指定目标主机。Q4gh api 和 gh search / gh repo view 等高阶命令怎么选日常操作优先用高阶命令输出更友好、更易读如 docs/primer/components/images/Detail-gh-issue-view.png 所示的 Issue 视图需要细粒度 JSON、批量处理或调用未封装接口时交给gh api。掌握gh api你的终端就拥有了 GitHub 数据的全部入口——从一行查询到复杂自动化脚本都只隔一条命令的距离。【免费下载链接】cliGitHub’s official command line tool项目地址: https://gitcode.com/GitHub_Trending/cli/cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考