Command referencegh api
gh api command (Linux & Windows / GitHub CLI)
What it does
Make authenticated HTTP requests to the GitHub REST or GraphQL API using your gh credentials. When people search for gh api request, they usually want practical GitHub CLI flags, safe examples, and how this subcommand fits everyday PR and repo workflows on Linux, Windows, and macOS. Syntax, options, and copyable examples are below.
Make authenticated HTTP requests to the GitHub REST or GraphQL API using your gh credentials.
Syntax
gh api <endpoint> [flags]
Common options
| Flag / option | Meaning |
|---|---|
| -X, --method | HTTP method (GET, POST, PATCH, DELETE, …). |
| -f, --field | Add a string parameter / form field. |
| -F, --raw-field | Add a typed/raw field. |
| --jq | Filter JSON output with jq syntax. |
| --paginate | Fetch all pages for list endpoints. |
| -H, --header | Add a custom header. |
Practical examples
Current user
gh api user
Returns the authenticated user’s profile JSON.
List issues
gh api repos/OWNER/REPO/issues --jq '.[].title'
Fetches issue titles with a jq filter.
GraphQL
gh api graphql -f query='query { viewer { login } }'Runs a GraphQL query with your logged-in token.
Paginate
gh api repos/OWNER/REPO/issues --paginate
Walks pagination for large result sets.
Common mistakes
- Embedding real tokens in examples or scripts — rely on `gh auth`.
- Using GET for mutating endpoints that require POST/PATCH.
Related commands
- gh auth loginAuthenticate the GitHub CLI with GitHub.com or GitHub Enterprise so other gh commands can run.
- gh issue listList issues in the current or specified GitHub repository with filters.
- gh pr listList pull requests in a repository with state, author, and search filters.
- gh gist createCreate a GitHub gist from files or standard input for quick snippets and scratch notes.
- gh pr createCreate a pull request from the current branch with title, body, reviewers, and base branch options.
- gh pr mergeMerge a pull request using merge commit, squash, or rebase strategies.
- gitTrack source history and collaborate through distributed repositories.
- gh repo cloneClone a GitHub repository to your machine using your authenticated gh settings.
FAQ
What does gh api do in GitHub CLI?
Make authenticated HTTP requests to the GitHub REST or GraphQL API using your gh credentials.
Does gh api work on Windows and Linux?
Yes. The GitHub CLI (`gh`) runs on Linux, Windows, and macOS with the same subcommand syntax after you authenticate with `gh auth login`.
What is a practical gh api example?
Try `gh api user` — Returns the authenticated user’s profile JSON.
Do I need a token in the command line for gh api?
Prefer `gh auth login` so credentials stay in the system keyring or secure storage. Avoid pasting personal access tokens into shell history.
Browse the full Linux and Windows command reference to search more bash, CMD, PowerShell, Conda, and GitHub CLI commands.