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 placeholder-determined values, see --field below. Note that adding re‐
39 quest parameters will automatically switch the request method to POST.
40 To 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 To pass nested parameters in the request payload, use "key[sub‐
65 key]=value" syntax when declaring fields. To pass nested values as ar‐
66 rays, declare multiple fields with the syntax "key[]=value1",
67 "key[]=value2". To pass an empty array, use "key[]" without a value.
68 To pass pre-constructed JSON or payloads in other formats, a request
71 body may be read from file specified by --input. Use "-" to read from
72 standard input. When passing the request body this way, any parameters
73 specified via field flags are added to the query string of the endpoint
74 URL.
75 In --paginate mode, all pages of results will sequentially be requested
78 until there are no more pages of results. For GraphQL requests, this
79 requires that the original query accepts an $endCursor: String variable
80 and that it fetches the pageInfo{ hasNextPage, endCursor } set of
81 fields from a collection.
82
86 --cache <duration>
87 Cache the response, e.g. "3600s", "60m", "1h"
88 -F, --field <key=value>
91 Add a typed parameter in key=value format
92 -H, --header <key:value>
95 Add a HTTP request header in key:value format
96 --hostname <string>
99 The GitHub hostname for the request (default "github.com")
100 -i, --include
103 Include HTTP response status line and headers in the output
104 --input <file>
107 The file to use as body for the HTTP request (use "-" to read
108 from standard input)
109 -q, --jq <string>
112 Query to select values from the response using jq syntax
113 -X, --method <string>
116 The HTTP method for the request
117 --paginate
120 Make additional HTTP requests to fetch all pages of results
121 -p, --preview <names>
124 GitHub API preview names to request (without the "-preview" suf‐
125 fix)
126 -f, --raw-field <key=value>
129 Add a string parameter in key=value format
130 --silent
133 Do not print the response body
134 -t, --template <string>
137 Format JSON output using a Go template; see "gh help formatting"
138 --verbose
141 Include full HTTP request and response in the output
142
146 # list releases in the current repository
147 $ gh api repos/{owner}/{repo}/releases
148 # post an issue comment
150 $ gh api repos/{owner}/{repo}/issues/123/comments -f body='Hi from CLI'
151 # post nested parameter read from a file
153 $ gh api gists -F 'files[myfile.txt][content]=@myfile.txt'
154 # add parameters to a GET request
156 $ gh api -X GET search/issues -f q='repo:cli/cli is:open remote'
157 # set a custom HTTP header
159 $ gh api -H 'Accept: application/vnd.github.v3.raw+json' ...
160 # opt into GitHub API previews
162 $ gh api --preview baptiste,nebula ...
163 # print only specific fields from the response
165 $ gh api repos/{owner}/{repo}/issues --jq '.[].title'
166 # use a template for the output
168 $ gh api repos/{owner}/{repo}/issues --template \
169 '{{range .}}{{.title}} ({{.labels | pluck "name" | join ", " | color "yellow"}}){{"\n"}}{{end}}'
170 # list releases with GraphQL
172 $ gh api graphql -F owner='{owner}' -F name='{repo}' -f query='
173 query($name: String!, $owner: String!) {
174 repository(owner: $owner, name: $name) {
175 releases(last: 3) {
176 nodes { tagName }
177 }
178 }
179 }
180 # list all repositories for a user
182 $ gh api graphql --paginate -f query='
183 query($endCursor: String) {
184 viewer {
185 repositories(first: 100, after: $endCursor) {
186 nodes { nameWithOwner }
187 pageInfo {
188 hasNextPage
189 endCursor
190 }
191 }
192 }
193 }
194
200 gh(1)
201 Oct 2023 GH-API(1)