gh_api.md - Github Cli 中文文档（非官方翻译)

gh api

gh api <endpoint> [flags]

向 GitHub API 发出经过身份验证的 HTTP 请求，并打印响应。

endpoint 参数应该是 GitHub API v3 endpoint 的路径，或者是访问 GitHub API v4 的graphql。

endpoint 参数中的占位符值{owner}、{repo}和{branch}将替换成当前目录存储库中的值。请注意，在某些 shell（例如 PowerShell）中，可能需要用{…}的值，放在引号中，以防止 shell 对花括号应用特殊含义。

默认的 HTTP 请求方法通常为GET，如果添加了任何参数，则为POST。用--method覆盖默认。

-f/--raw-field传递key=value格式的一个或多个，用于向请求负载，添加静态字符串参数。要添加非字符串或其他动态值，请参见--field。请注意，添加请求参数将自动将请求方法切换为 POST。要改 GET，请使用--method GET.

这个-F/--field标志具有基于值格式的魔法类型转换：

文本值true、false、null和整数，被转换为适当的 JSON 类型；
占位符值{owner}、{repo}和{branch}由当前目录存储库中的值填充；
如果该值以@开头，则该值的其余部分将被解释为，读取值的文件名。传递-则从标准输入读取。

对于 GraphQL 请求，除query和operationName之外的所有字段都被解释为 GraphQL 变量。

原始请求主体可以通过--input指定的文件，从外部传递。传递-则从标准输入读取。在此模式下，通过--field指定的参数。被序列化为 URL 查询参数。

在--paginate模式下，将按顺序请求所有结果页，直到没有更多结果页为止。对于 GraphQL 请求，这要求原始查询接受一个$endCursor: String变量，之后它从一个集合，获取pageInfo{ hasNextPage, endCursor }字段集。

Options

--cache <duration>: 缓存一个响应, e.g. "3600s", "60m", "1h"
-F, --field <key=value>: 添加一个类型参数，格式是 key=value
-H, --header <key:value>: 添加一个 HTTP 请求头，格式是 key=value
--hostname <string>: 请求的 GitHub 主址 (默认为 "github.com")
-i, --include: 将 HTTP 响应头也输出
--input <file>: file 作为 HTTP 请求的主体 (使用 "-" 可以从标准输入读取)
-q, --jq <string>: 使用 jq 语法，查询响应的值
-X, --method <string>: HTTP 方法
--paginate: 发出额外的 HTTP 请求，获取所有的结果页
-p, --preview <strings>: GitHub API 预览版本的功能
-f, --raw-field <key=value>: 添加一个字符串参数，格式是 key=value
--silent: 不打印
-t, --template <string>: 用模板格式化响应

Examples

# 列出，repo 的 releases 
$ gh api repos/{owner}/{repo}/releases

# 发布一个 issue 评论
$ gh api repos/{owner}/{repo}/issues/123/comments -f body='Hi from CLI'

# 为 GET 请求，添加参数
$ gh api -X GET search/issues -f q='repo:cli/cli is:open remote'

# 自定义 HTTP header
$ gh api -H 'Accept: application/vnd.github.v3.raw+json' ...

# GitHub API 预览版本的功能
$ gh api --preview baptiste,nebula ...

# 打印 response 中特殊字段
$ gh api repos/{owner}/{repo}/issues --jq '.[].title'

# 模板化输出
$ gh api repos/{owner}/{repo}/issues --template \
  '{{range .}}{{.title}} ({{.labels | pluck "name" | join ", " | color "yellow"}}){{"\n"}}{{end}}'

# 列出，releases with GraphQL
$ gh 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 }
      }
    }
  }
'

# 列出，一个用户所有的存储库
$ gh api graphql --paginate -f query='
  query($endCursor: String) {
    viewer {
      repositories(first: 100, after: $endCursor) {
        nodes { nameWithOwner }
        pageInfo {
          hasNextPage
          endCursor
        }
      }
    }
  }
'

Github Cli 中文文档（非官方翻译)

gh api

Options

Examples

See also