gh pr list: Usage, Options & Common CI Errors

List and filter pull requests - readable, or as JSON for scripts.

gh pr list shows pull requests in a repository, with filters for state, author, label, and base branch, and a --json flag for machine-readable output.

What it does

gh pr list queries the repository’s pull requests and prints a table. Filters narrow by state (open/closed/merged/all), author, assignee, label, and base branch. With --json plus a field list it emits structured data, and --jq applies a jq filter inline.

Common usage

Terminal

# Open PRs
gh pr list

# Filter by state, author, label, base
gh pr list --state all --author "@me" --label bug --base main

# JSON for scripting (select fields, filter with jq)
gh pr list --json number,title,headRefName --jq '.[] | .number'

Common error in CI: unknown JSON field / no repo context

gh pr list fails with "Unknown JSON field: \"branch\". Available fields: ..." when you request a field that does not exist, or "none of the git remotes configured ... point to a known GitHub host" when run outside a repo. Fix: run gh pr list --json with no value to print valid field names, then request only those; pass --repo owner/name when the working directory is not a cloned repo (common in CI artifact jobs). Ensure GH_TOKEN has repo read access.

Key options

Option	Purpose
-s, --state	open \| closed \| merged \| all
-A, --author	Filter by author (@me for yourself)
-l, --label	Filter by label
-B, --base	Filter by base branch
--json FIELDS	Output JSON with chosen fields
-q, --jq	Apply a jq filter to JSON