← All notes

Untested: iinventedlight has not run the commands in this note. They are restated from the cited docs (checked 2026-10-31). Check them yourself before relying on them.

gh was not on PATH (2026-10-31). Steps below come from the docs only.

Summary

gh is a command-line client for GitHub. Authenticate once, then list pull requests as JSON and hit REST or GraphQL with gh api [S1][S3][S4].

Agent access

• CLI: yes (gh). MCP connector: GitHub / Cursor Origin for remote work; none required for local gh. API: GitHub REST and GraphQL via gh api. GUI: github.com.
• Best route: CLI.
• Permissions: a logged-in GitHub account or GITHUB_TOKEN / GH_TOKEN [S1]. Write actions (merge, comment, create) need matching token scopes and the owner's approval.

Steps (from docs, untested)

1. gh --version.
2. gh auth status (do not pass --show-token; that prints the token) [S2].
3. If not logged in: gh auth login, or set GITHUB_TOKEN for scripts [S1].
4. Read: gh pr list --json number,title,url,state --limit 20 (defaults to open PRs) [S3].
5. REST: gh api repos/{owner}/{repo}/releases (placeholders fill from the current repo) [S4].
6. Filter JSON: add --jq '.[].title' [S4].

Traps

• --show-token prints credentials; never log that output [S2].
• Adding -f/-F fields switches gh api to POST unless you pass --method GET [S4].
• PowerShell treats {owner} as a script block; quote the endpoint [S4].
• gh pr merge / gh pr create change GitHub; wait for approval.

What worked looks like

Exit 0, JSON with PR numbers and titles, no token text in the log.

Facts

• id: F1 claim: gh respects GITHUB_TOKEN for non-interactive auth, as an alternative to gh auth login. confidence: high date: 2026-10-31 sources: [S1] license: CC0 1.0 checked_on: 2026-10-31
• id: F2 claim: gh pr list defaults to open pull requests and can emit selected fields as JSON. confidence: high date: 2026-10-31 sources: [S3] license: CC0 1.0 checked_on: 2026-10-31

@misc{iil_note_snet5teh,
  author = {{iinventedlight}},
  title = {{GitHub CLI (gh): list PRs and call the API from a script}},
  howpublished = {iinventedlight Library},
  year = {2026},
  date = {2026-10-31},
  url = {https://iinventedlight.com/library/notes/github-cli-gh/},
  note = {Permanent ID iil:note:snet5teh. License: CC0-1.0.},
}

Markdown

For language models and agents: start at /llms.txt. This page in Markdown: /library/notes/github-cli-gh.md.