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 [[--include]] [endpoint]

$ gh api --silent [endpoint]

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

$ gh api --help

gh api [flags]

    The GitHub API endpoint to request. For example, `/repos/{owner}/{repo}/issues` or `/users/{username}`.

--method
    HTTP method for the request. Defaults to `GET` if no request body is provided, otherwise `POST`. Common methods include `GET`, `POST`, `PUT`, `PATCH`, and `DELETE`.

--raw-field =
    Adds a raw string field to the request body. Useful for simple key-value pairs.

--field =
    Adds a string field to the request body. If the value starts with `@` it will read data from the file specified after the `@` character.

--input
    The file that contains the request body. Use '-' to read from standard input.

--jq
    Process response JSON with jq. Requires `jq` to be installed.

--preview
    Enable a GitHub API preview for the request.

--paginate
    Fetches all pages of the results. Useful for endpoints that return paginated results.

--cache
    Cache the response for the specified number of seconds.

--request-header
    Add an additional HTTP request header.

--verbose
    Show HTTP requests and responses

The `gh-api` command within the GitHub CLI (gh) allows users to make authenticated GitHub API requests directly from the command line.

Instead of using tools like `curl` and manually constructing API calls, `gh api` simplifies the process by handling authentication (using your GitHub credentials configured with `gh auth login`), header formatting, and basic JSON parsing. This makes it ideal for scripting, automating tasks, and quickly querying GitHub's API without the complexities of managing API tokens and request structures.

You can specify the endpoint, method, and any necessary data to send to the GitHub API. The response is typically printed to standard output, allowing you to process it further with other command-line tools like `jq`.

This command is a powerful tool for developers and system administrators who need to programmatically interact with GitHub, allowing them to perform tasks such as creating issues, retrieving repository information, managing pull requests, and more, all from the comfort of their terminal.

Requires GitHub CLI to be installed and authenticated (`gh auth login`). jq needs to be installed separately to use the --jq flag. The GitHub API is subject to rate limits; consider using `--cache` flag to avoid hitting API rate limits.

1. Get information about the current authenticated user:
`gh api /user`

2. Create a new issue in a repository:
`gh api repos/owner/repo/issues --field title="My new issue" --field body="Issue description"`

3. List pull requests for a repository and filter the result using jq:
`gh api repos/owner/repo/pulls --jq '.[].title'`

The `gh api` command was introduced as part of the GitHub CLI to provide a more user-friendly way to interact with the GitHub API. Before gh, developers often relied on `curl` or other HTTP clients, which required manual construction of requests and handling authentication.

The development of `gh api` aimed to simplify these tasks by abstracting away the complexities of API interactions and providing a consistent interface for accessing GitHub's resources. Its usage has grown alongside the adoption of the GitHub CLI, becoming a popular tool for scripting and automating GitHub-related workflows.

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