How to use the command 'gh api' (with examples)

The ‘gh api’ command is a powerful tool provided by the GitHub CLI that allows users to make authenticated HTTP requests to the GitHub API and print the response. It can be used to interact with various GitHub API endpoints, retrieve data, create reactions, send custom requests, and more.

Use case 1: Display the subcommand help

Code:

gh api --help

Motivation: The ‘–help’ option will display the help screen for the ‘gh api’ command, providing a summary of all available options and subcommands. This is useful when you need a quick reference on how to use the command or when you want to explore new features.

Explanation: The ‘–help’ option is a common command-line option that is used to display the help screen for a particular command. When used with the ‘gh api’ command, it will show information about the available options and subcommands.

Example output:

Commands:
  gh api batch
  gh api graphql
  gh api repos/:owner/:repo
  gh api users/:username

Use case 2: Display the releases for the current repository in JSON format

Code:

gh api repos/:owner/:repo/releases

Motivation: This command is useful for retrieving information about the releases of a repository. It can be used to obtain details such as release tags, release notes, and assets associated with each release. By printing the response in JSON format, it becomes easier to parse and manipulate the data programmatically.

Explanation: The command ‘gh api repos/:owner/:repo/releases’ is used to retrieve the releases for a specific repository. In the command, ‘:owner’ should be replaced with the owner of the repository and ‘:repo’ with the name of the repository. This command will make an HTTP GET request to the GitHub API and print the response, which will include information about the releases.

Example output:

[
  {
    "id": 123,
    "tag_name": "v1.0.0",
    "name": "Release 1.0.0",
    "body": "This is the first release of the project.",
    "assets": [
      {
        "name": "project.zip",
        "download_url": "https://api.github.com/repos/:owner/:repo/releases/assets/123"
      }
    ]
  }
]

Use case 3: Create a reaction for a specific issue

Code:

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

Motivation: This command allows users to create reactions (such as thumbs-up or heart) for a specific issue on GitHub. Reactions can be used to express emotions or opinions about an issue without leaving a comment. This is particularly useful when collaborating with others on GitHub and wanting to provide quick feedback.

Explanation: The command ‘gh api –header Accept:application/vnd.github.squirrel-girl-preview+json –raw-field ‘content=+1’ repos/:owner/:repo/issues/123/reactions’ is used to create a reaction for a specific issue. In the command, ‘:owner’ should be replaced with the owner of the repository, ‘:repo’ with the name of the repository, and ‘123’ with the issue number. The ‘–header’ option is used to set the request header to accept a specific media type for the GitHub API. The ‘–raw-field’ option is used to specify the content of the reaction.

Example output:

{
  "id": 456,
  "content": "+1",
  "user": {
    "login": "exampleuser",
    "id": 789
  }
}

Use case 4: Display the result of a GraphQL query in JSON format

Code:

gh api graphql --field name=':repo' --raw-field 'query'

Motivation: GitHub provides a powerful GraphQL API that allows users to query for specific data with a single request. This command allows users to execute a GraphQL query and print the response in JSON format, making it easier to extract and manipulate the data.

Explanation: The command ‘gh api graphql –field name=’:repo’ –raw-field ‘query’’ is used to execute a GraphQL query and print the response in JSON format. In this example, the ‘–field’ option is used to specify the variables for the GraphQL query. The ‘:repo’ variable is replaced with the name of the repository. The ‘–raw-field’ option is used to specify the actual GraphQL query itself.

Example output:

{
  "data": {
    "repository": {
      "name": "example-repo",
      "description": "This is an example repository."
    }
  }
}

Use case 5: Send a request using a custom HTTP method

Code:

gh api --method POST endpoint

Motivation: Sometimes, the standard HTTP methods (GET, POST, PUT, DELETE, etc.) might not be sufficient for certain requests. This command allows users to send a request using a custom HTTP method, giving them more flexibility and control over their API interactions.

Explanation: The ‘–method’ option is used to specify the HTTP method to be used for the request. In this example, ‘POST’ is used as the custom HTTP method. The ’endpoint’ parameter should be replaced with the desired API endpoint.

Example output: (No output will be printed for this command)

Use case 6: Include the HTTP response headers in the output

Code:

gh api --include endpoint

Motivation: Including the HTTP response headers in the output can provide additional information that might be useful for debugging or analysis purposes. It allows users to inspect the headers returned by the API for a better understanding of the request and response.

Explanation: The ‘–include’ option is used to include the HTTP response headers in the output. This option can be added to any ‘gh api’ command to retrieve the headers along with the response body. The ’endpoint’ parameter should be replaced with the desired API endpoint.

Example output:

HTTP/1.1 200 OK
Cache-Control: private, max-age=0, s-maxage=0
Content-Type: application/json; charset=utf-8
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1632294237
...
{
  "id": 123,
  ...
}

Use case 7: Do not print the response body

Code:

gh api --silent endpoint

Motivation: Sometimes, users might be interested only in the HTTP response status code or headers and do not need the actual response body. This option allows users to make a request without printing the response body, reducing unnecessary output.

Explanation: The ‘–silent’ option is used to make a request without printing the response body. This option can be added to any ‘gh api’ command to skip printing the actual response. The ’endpoint’ parameter should be replaced with the desired API endpoint.

Example output: (No output will be printed for this command)

Use case 8: Send a request to a specific GitHub Enterprise Server

Code:

gh api --hostname github.example.com endpoint

Motivation: GitHub Enterprise Server is a self-hosted solution that enables organizations to host their own instance of GitHub. This option allows users to send a request to a specific GitHub Enterprise Server instead of the default github.com, giving them the ability to interact with their organization’s instance.

Explanation: The ‘–hostname’ option is used to specify the hostname of the GitHub Enterprise Server to send the request to. In this example, ‘github.example.com’ is used as the custom hostname. The ’endpoint’ parameter should be replaced with the desired API endpoint.

Example output: (Output will vary based on the specific request and GitHub Enterprise Server configuration)

Conclusion:

The ‘gh api’ command provides a convenient and flexible way to interact with the GitHub API directly from the command line. It allows users to perform various actions such as retrieving data, creating reactions, executing GraphQL queries, and sending custom requests. By understanding its different use cases and options, users can make the most out of the command and seamlessly integrate it into their development workflows.