gh api Command Reference

By Kaveh Alemi·Latchkey

Call any GitHub REST or GraphQL endpoint with auth handled for you.

gh api is the escape hatch for anything the typed gh commands do not cover. It signs requests with your gh credentials and can paginate and filter results.

What it does

gh api sends authenticated requests to GitHub REST or GraphQL endpoints, inferring the method, attaching the token, and handling base URL and headers. It supports fields, pagination, and a built-in jq expression for shaping output.

Common flags and usage

ENDPOINT: REST path (repos/{owner}/{repo}) or graphql
--method GET|POST|PATCH|DELETE / -X: HTTP method
--field KEY=VALUE / -f and -F (raw): request fields
--paginate: follow pagination across pages
--jq EXPR: filter the JSON response with jq

Example

shell

- name: List job names for a run
  env:
    GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  run: |
    gh api "repos/${{ github.repository }}/actions/runs/${{ github.run_id }}/jobs" \
      --jq '.jobs[].name'

In CI

Set GH_TOKEN (or GITHUB_TOKEN) in env and gh api authenticates automatically, so no curl plus token plumbing is needed. Use --paginate for list endpoints and --jq to extract just the fields you need.

Using this in CI

Cloud CLIs behave differently on a runner than on your laptop. They assume no interactive terminal, no cached credentials, and no browser for device-code flows, so the same command that works locally can hang or fail on a runner.

Authenticate with a short-lived OIDC token rather than a long-lived static key. GitHub Actions can exchange id-token: write for cloud credentials with no stored secret.
Always pass the non-interactive flag. Most cloud CLIs will otherwise prompt and hang until the job times out.
Pin the CLI version. Cloud CLIs change output formats between minor releases, and any script parsing that output will break silently.
Set the output format explicitly (--output json) rather than relying on the default, which can differ by version and configuration profile.

Key takeaways

gh api handles authentication, base URL, and headers for REST and GraphQL.
Set GH_TOKEN in env and the request is authenticated automatically.
--paginate and --jq cover multi-page list endpoints and response parsing.

Frequently asked questions

gh api Command Reference?