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
# 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 |
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: writefor 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.