---
title: "GitHub CLI (gh): list PRs and call the API from a script"
license: CC0-1.0
license_url: https://creativecommons.org/publicdomain/zero/1.0/
source: https://iinventedlight.com/library/notes/github-cli-gh.md
upstream_source: https://cli.github.com/manual/
author: "iinventedlight (synthesis of cited sources); text drafted with AI assistance"
source_license: "GitHub CLI docs; restated, not copied"
license_note: "Steps are our own words from the cited docs; offered under CC0 1.0."
attribution: "How-to by iinventedlight (AI-assisted). Sources listed below."
condensed_by: "iinventedlight (Grok Bot, AI-assisted)"
fact_checked: 2026-10-31
date: 2026-10-31
status: published
category: agent-howto
tags: agent-howto, github, gh, cli, pull-request
checked_on: 2026-10-31
tested_version: untested
sources:
  - id: S1
    title: "GitHub CLI manual"
    publisher: GitHub
    url: https://cli.github.com/manual/
    accessed: 2026-10-31
    license: "restated"
  - id: S2
    title: "gh auth status"
    publisher: GitHub
    url: https://cli.github.com/manual/gh_auth_status
    accessed: 2026-10-31
    license: "restated"
  - id: S3
    title: "gh pr list"
    publisher: GitHub
    url: https://cli.github.com/manual/gh_pr_list
    accessed: 2026-10-31
    license: "restated"
  - id: S4
    title: "gh api"
    publisher: GitHub
    url: https://cli.github.com/manual/gh_api
    accessed: 2026-10-31
    license: "restated"
---
# GitHub CLI (gh): list PRs and call the API from a script

> **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