gh-api

Display the releases for the current repository in JSON format

$ gh api repos/:owner/:repo/releases

$ gh api [[-H|--header]] [Accept:application/vnd.github.squirrel-girl-preview+json] [[-f|--raw-field]] '[content=+1]' [repos/:owner/:repo/issues/123/reactions]

$ gh api graphql [[-f|--field]] [name=':repo'] [[-f|--raw-field]] '[query]'

$ gh api [[-X|--method]] [POST] [endpoint]

$ gh api [[-i|--include]] [endpoint]

$ gh api --silent [endpoint]

$ gh api --hostname [github.example.com] [endpoint]

$ gh api --help

gh api <path> [flags]
gh api -q <GraphQL_query> [flags]

<path>
    The specific GitHub API endpoint path (e.g., /user, /repos/OWNER/REPO).

-X, --method <METHOD>
    Specifies the HTTP method for the request (e.g., GET, POST, PUT, DELETE).

-F, --field <NAME>=<VALUE>
    Adds a form field to the request body, useful for POST/PATCH/PUT with form data.

-f, --raw-field <NAME>=<VALUE>
    Adds a raw string field to the request body, similar to -F but without JSON escaping.

-H, --header <NAME>=<VALUE>
    Adds a custom HTTP header to the request.

-i, --include
    Includes HTTP response headers in the output.

-q, --jq <QUERY>
    Applies a jq expression to the JSON output. Also used to specify a GraphQL query if the argument starts with '{' or 'query'.

-v, --verbose
    Displays detailed information about the request and response for debugging.

-P, --paginate
    Automatically fetches all pages of a paginated API response.

-p, --template <TEMPLATE>
    Formats the output using a Go template.

--input <FILE>
    Reads the request body from a specified file or standard input.

--cache <DURATION>
    Caches the API response for the given duration (e.g., 1h, 30m).

The gh api command is a powerful subcommand of the GitHub CLI that enables users to make direct, authenticated requests to both the GitHub REST API and GraphQL API. It leverages your existing gh authentication session, eliminating the need for manual token management. This command is invaluable for scripting complex workflows, automating repetitive tasks, or accessing GitHub API endpoints not covered by other specific gh commands. Users can specify HTTP methods, path parameters, request bodies (via form fields or raw input), and custom headers. It provides robust features such as automatic pagination for REST endpoints, jq integration for output processing, and caching of responses. gh api is designed for developers, system administrators, and power users who require granular control and direct programmatic interaction with GitHub's extensive API infrastructure.

gh api respects GitHub API rate limits; excessive or rapid requests, especially with pagination, can quickly consume your quota.
It relies on your existing gh auth configuration for authentication, so proper authentication setup is crucial.
The API token used must possess the necessary scopes for the requested operations to succeed.
While supporting GraphQL, complex queries might be more manageable with dedicated GraphQL tools.
Users should always anticipate and handle potential API errors in their scripts.

gh api automatically uses the authentication credentials established via gh auth login, simplifying API interactions by eliminating manual token handling.

By default, the command prints the raw JSON response body to standard output. This output is ideal for piping into jq for parsing or for custom formatting using a Go template with the -p flag.

The -q flag is versatile; if its argument starts with '{' or 'query', it's interpreted as a GraphQL query executed against the GitHub GraphQL API endpoint, otherwise it applies a jq filter.

The gh api subcommand was introduced as a fundamental component of the GitHub CLI, making its debut with the CLI's first stable release (v1.0.0 in September 2020). Its primary purpose was to provide a flexible and direct interface to the GitHub REST and GraphQL APIs, leveraging the CLI's built-in authentication system. This allowed users to script and automate interactions with GitHub beyond the capabilities of pre-defined gh commands. Since its inception, gh api has undergone continuous development, incorporating features like enhanced pagination, response caching, and refined GraphQL support, solidifying its role as an indispensable tool for advanced GitHub automation.

gh(1), curl(1), jq(1), gh auth(1)