NAME

SYNOPSIS

DESCRIPTION

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 or the repository specified in the GH_REPO environment variable. 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:

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 <names>

GitHub API preview names to request (without the "-preview" suffix)

-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