gh api

gh api <endpoint> [flags]

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

端点参数应为 GitHub API v3 端点的路径，或 graphql 用于访问 GitHub API v4。

端点参数中的占位符值 {owner}、{repo} 和 {branch} 将被当前目录的仓库或 GH_REPO 环境变量中指定的仓库的值替换。请注意，在某些 shell（例如 PowerShell）中，您可能需要将包含 {...} 的任何值用引号括起来，以防止 shell 对花括号应用特殊含义。

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

以 key=value 格式传递一个或多个 -f/--raw-field 值，以将静态字符串参数添加到请求有效负载中。要添加非字符串或占位符确定的值，请参见下面的 -F/--field。请注意，添加请求参数会自动将请求方法切换到 POST。要改为将参数作为 GET 查询字符串发送，请使用 --method GET。

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

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

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

要将嵌套参数传递到请求有效负载中，请在声明字段时使用 key[subkey]=value 语法。要将嵌套值作为数组传递，请使用语法 key[]=value1、key[]=value2 声明多个字段。要传递一个空数组，请使用 key[]，但不要使用值。

要传递预先构建的 JSON 或其他格式的有效负载，可以从 --input 指定的文件中读取请求主体。使用 - 以从标准输入读取。通过这种方式传递请求主体时，通过字段标志指定的任何参数都将添加到端点 URL 的查询字符串中。

在 --paginate 模式下，将按顺序请求结果的所有页面，直到没有更多结果页面。对于 GraphQL 请求，这要求原始查询接受 $endCursor: String 变量，并且它从集合中获取 pageInfo{ hasNextPage, endCursor } 字段集。每个页面都是一个单独的 JSON 数组或对象。传递 --slurp 以将所有 JSON 数组或对象的页面包装到一个外部 JSON 数组中。

选项

--cache <duration>
缓存响应，例如“3600s”、“60m”、“1h”。
-F, --field <key=value>
以键值对格式添加类型参数
-H, --header <key:value>
以键值对格式添加 HTTP 请求头
--hostname <string>
请求的 GitHub 主机名（默认“github.com”）
-i, --include
在输出中包含 HTTP 响应状态行和头
--input <file>
用作 HTTP 请求主体的文件（使用“-” 从标准输入读取）
-q, --jq <string>
使用 jq 语法从响应中选择值的查询
-X, --method <string> (default "GET")
请求的 HTTP 方法
--paginate
发出其他 HTTP 请求以获取结果的所有页面
-p, --preview <names>
要请求的 GitHub API 预览名称（不带“-preview”后缀）
-f, --raw-field <key=value>
以键值对格式添加字符串参数
--silent
不要打印响应主体
--slurp
与“--paginate”一起使用，以返回 JSON 数组或对象的各个页面的数组
-t, --template <string>
使用 Go 模板格式化 JSON 输出；参见“gh help formatting”。
--verbose
在输出中包含完整的 HTTP 请求和响应

示例

# list releases in the current repository
$ gh api repos/{owner}/{repo}/releases

# post an issue comment
$ gh api repos/{owner}/{repo}/issues/123/comments -f body='Hi from CLI'

# post nested parameter read from a file
$ gh api gists -F 'files[myfile.txt][content][email protected]'

# add parameters to a GET request
$ gh api -X GET search/issues -f q='repo:cli/cli is:open remote'

# set a custom HTTP header
$ gh api -H 'Accept: application/vnd.github.v3.raw+json' ...

# opt into GitHub API previews
$ gh api --preview baptiste,nebula ...

# print only specific fields from the response
$ gh api repos/{owner}/{repo}/issues --jq '.[].title'

# use a template for the output
$ gh api repos/{owner}/{repo}/issues --template \
  '{{range .}}{{.title}} ({{.labels | pluck "name" | join ", " | color "yellow"}}){{"\n"}}{{end}}'

# update allowed values of the "environment" custom property in a deeply nested array
gh api --PATCH /orgs/{org}/properties/schema \
   -F 'properties[][property_name]=environment' \
   -F 'properties[][default_value]=production' \
   -F 'properties[][allowed_values][]=staging' \
   -F 'properties[][allowed_values][]=production'

# list 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 }
      }
    }
  }
'

# list all repositories for a user
$ gh api graphql --paginate -f query='
  query($endCursor: String) {
    viewer {
      repositories(first: 100, after: $endCursor) {
        nodes { nameWithOwner }
        pageInfo {
          hasNextPage
          endCursor
        }
      }
    }
  }
'

# get the percentage of forks for the current user
$ gh api graphql --paginate --slurp -f query='
  query($endCursor: String) {
    viewer {
      repositories(first: 100, after: $endCursor) {
        nodes { isFork }
        pageInfo {
          hasNextPage
          endCursor
        }
      }
    }
  }
' | jq 'def count(e): reduce e as $_ (0;.+1);
[.[].data.viewer.repositories.nodes[]] as $r | count(select($r[].isFork))/count($r[])'

另请参见