gh-api
Makes authenticated HTTP requests to the GitHub API and prints the response.
TLDR
Display the subcommand help
Display the releases for the current repository in JSON format
Create a reaction for a specific issue
Display the result of a GraphQL query in JSON format
Send a request using a custom HTTP method
Include the HTTP response headers in the output
Do not print the response body
Send a request to a specific GitHub Enterprise Server
SYNOPSIS
gh api <endpoint> [flags]
DESCRIPTION
Makes an authenticated HTTP request to the GitHub API and prints the response.
The endpoint argument should either be a path of a GitHub API v3 endpoint, or "graphql" to access the GitHub API v4.
Placeholder values "{owner}", "{repo}", and "{branch}" in the endpoint argument will get replaced with values from the repository of the current directory. Note that in some shells, for example PowerShell, you may need to enclose any value that contains "{...}" in quotes to prevent the shell from applying special meaning to curly braces.
The default HTTP request method is "GET" normally and "POST" if any
parameters were added. Override the method with
--method
.
Pass one or more -f/--raw-field
values in "key=value"
format to add static string parameters to the request payload. To add
non-string or otherwise dynamic values, see --field
below.
Note that adding request parameters will automatically switch the
request method to POST. To send the parameters as a GET query string
instead, use --method GET
.
The -F/--field
flag has magic type conversion based on
the format of the value:
literal values "true", "false", "null", and integer numbers get converted to appropriate JSON types;
placeholder values "{owner}", "{repo}", and "{branch}" get populated with values from the repository of the current directory;
if the value starts with "@", the rest of the value is interpreted as a filename to read the value from. Pass "-" to read from standard input.
For GraphQL requests, all fields other than "query" and "operationName" are interpreted as GraphQL variables.
Raw request body may be passed from the outside via a file specified
by --input
. Pass "-" to read from standard input. In this
mode, parameters specified via --field
flags are serialized
into URL query parameters.
In --paginate
mode, all pages of results will
sequentially be requested until there are no more pages of results. For
GraphQL requests, this requires that the original query accepts an
$endCursor: String
variable and that it fetches the
pageInfo{ hasNextPage, endCursor }
set of fields from a
collection.
OPTIONS
--cache
<duration>
-
Cache the response, e.g. "3600s", "60m", "1h"
-F
,--field
<key=value>
-
Add a typed parameter in key=value format
-H
,--header
<key:value>
-
Add a HTTP request header in key:value format
--hostname
<string>
-
The GitHub hostname for the request (default "github.com")
-i
,--include
-
Include HTTP response headers in the output
--input
<file>
-
The file to use as body for the HTTP request (use "-" to read from standard input)
-q
,--jq
<string>
-
Query to select values from the response using jq syntax
-X
,--method
<string>
-
The HTTP method for the request
--paginate
-
Make additional HTTP requests to fetch all pages of results
-p
,--preview
<strings>
-
Opt into GitHub API previews
-f
,--raw-field
<key=value>
-
Add a string parameter in key=value format
--silent
-
Do not print the response body
-t
,--template
<string>
-
Format the response using a Go template
EXAMPLE
# 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' # 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}}' # 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 } } } }
SEE ALSO
gh(1)