1GH-API(1) GitHub CLI manual GH-API(1)
2
6 gh-api - Make an authenticated GitHub API request
7
11 gh api <endpoint> [flags]
12
16 Makes an authenticated HTTP request to the GitHub API and prints the
17 response.
18 The endpoint argument should either be a path of a GitHub API v3 end‐
21 point, or "graphql" to access the GitHub API v4.
22 Placeholder values "{owner}", "{repo}", and "{branch}" in the endpoint
25 argument will get replaced with values from the repository of the cur‐
26 rent directory or the repository specified in the GH_REPO environment
27 variable. Note that in some shells, for example PowerShell, you may
28 need to enclose any value that contains "{...}" in quotes to prevent
29 the shell from applying special meaning to curly braces.
30 The default HTTP request method is "GET" normally and "POST" if any pa‐
33 rameters were added. Override the method with --method.
34 Pass one or more -f/--raw-field values in "key=value" format to add
37 static string parameters to the request payload. To add non-string or
38 otherwise dynamic values, see --field below. Note that adding request
39 parameters will automatically switch the request method to POST. To
40 send the parameters as a GET query string instead, use --method GET.
41 The -F/--field flag has magic type conversion based on the format of
44 the value:
45 • literal values "true", "false", "null", and integer numbers
48 get converted to appropriate JSON types;
49 • placeholder values "{owner}", "{repo}", and "{branch}" get
51 populated with values from the repository of the current di‐
52 rectory;
53 • if the value starts with "@", the rest of the value is inter‐
55 preted as a filename to read the value from. Pass "-" to read
56 from standard input.
57 For GraphQL requests, all fields other than "query" and "operationName"
61 are interpreted as GraphQL variables.
62 Raw request body may be passed from the outside via a file specified by
65 --input. Pass "-" to read from standard input. In this mode, parame‐
66 ters specified via --field flags are serialized into URL query parame‐
67 ters.
68 In --paginate mode, all pages of results will sequentially be requested
71 until there are no more pages of results. For GraphQL requests, this
72 requires that the original query accepts an $endCursor: String variable
73 and that it fetches the pageInfo{ hasNextPage, endCursor } set of
74 fields from a collection.
75
79 --cache <duration>
80 Cache the response, e.g. "3600s", "60m", "1h"
81 -F, --field <key=value>
84 Add a typed parameter in key=value format
85 -H, --header <key:value>
88 Add a HTTP request header in key:value format
89 --hostname <string>
92 The GitHub hostname for the request (default "github.com")
93 -i, --include
96 Include HTTP response status line and headers in the output
97 --input <file>
100 The file to use as body for the HTTP request (use "-" to read
101 from standard input)
102 -q, --jq <string>
105 Query to select values from the response using jq syntax
106 -X, --method <string>
109 The HTTP method for the request
110 --paginate
113 Make additional HTTP requests to fetch all pages of results
114 -p, --preview <names>
117 GitHub API preview names to request (without the "-preview" suf‐
118 fix)
119 -f, --raw-field <key=value>
122 Add a string parameter in key=value format
123 --silent
126 Do not print the response body
127 -t, --template <string>
130 Format the response using a Go template
131
135 # list releases in the current repository
136 $ gh api repos/{owner}/{repo}/releases
137 # post an issue comment
139 $ gh api repos/{owner}/{repo}/issues/123/comments -f body='Hi from CLI'
140 # add parameters to a GET request
142 $ gh api -X GET search/issues -f q='repo:cli/cli is:open remote'
143 # set a custom HTTP header
145 $ gh api -H 'Accept: application/vnd.github.v3.raw+json' ...
146 # opt into GitHub API previews
148 $ gh api --preview baptiste,nebula ...
149 # print only specific fields from the response
151 $ gh api repos/{owner}/{repo}/issues --jq '.[].title'
152 # use a template for the output
154 $ gh api repos/{owner}/{repo}/issues --template \
155 '{{range .}}{{.title}} ({{.labels | pluck "name" | join ", " | color "yellow"}}){{"\n"}}{{end}}'
156 # list releases with GraphQL
158 $ gh api graphql -F owner='{owner}' -F name='{repo}' -f query='
159 query($name: String!, $owner: String!) {
160 repository(owner: $owner, name: $name) {
161 releases(last: 3) {
162 nodes { tagName }
163 }
164 }
165 }
166 # list all repositories for a user
168 $ gh api graphql --paginate -f query='
169 query($endCursor: String) {
170 viewer {
171 repositories(first: 100, after: $endCursor) {
172 nodes { nameWithOwner }
173 pageInfo {
174 hasNextPage
175 endCursor
176 }
177 }
178 }
179 }
180
186 gh(1)
187 Jun 2022 GH-API(1)