gh-api
Make authenticated GitHub API requests
TLDR
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
Display the subcommand help
SYNOPSIS
gh api
PARAMETERS
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
DESCRIPTION
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.
CAVEATS
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.
EXAMPLES
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'`
HISTORY
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.