gh api

Make an authenticated GitHub API request

Synopsis

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.

The default HTTP request method is "GET" normally and "POST" if any parameters were added. Override the method with --method.

Pass one or more --raw-field values in "key=value" format to add JSON-encoded string parameters to the POST body.

The --field flag behaves like --raw-field with 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.

The --jq option accepts a query in jq syntax and will print only the resulting values that match the query. This is equivalent to piping the output to jq -r, but does not require the jq utility to be installed on the system. To learn more about the query syntax, see: https://stedolan.github.io/jq/manual/v1.6/

With --template, the provided Go template is rendered using the JSON data as input. For the syntax of Go templates, see: https://golang.org/pkg/text/template/

The following functions are available in templates:

• color <style>, <input>: colorize input using https://github.com/mgutz/ansi
• autocolor: like color, but only emits color to terminals
• timefmt <format> <time>: formats a timestamp using Go's Time.Format function
• timeago <time>: renders a timestamp as relative to now
• pluck <field> <list>: collects values of a field from all items in the input
• join <sep> <list>: joins values in the list using a separator

gh api <endpoint> [flags]

Examples

# 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 --filter '.[].title'

# use a template for the output
$ gh api repos/:owner/:repo/issues --template \
  ' ()\n'

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

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
  -q, --jq string             Query to select values from the response using jq syntax
  -X, --method string         The HTTP method for the request (default "GET")
      --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

Options inherited from parent commands

      --help   Show help for command