List and Filter Pull Requests with gh pr list

gh pr list finds pull requests from a terminal in seconds, narrowed by state, author, branch or label, and shaped into fields a script can consume. The examples use GitHub CLI 2.87.3, installed from the gh package on this machine.

Allow about ten minutes. You need GitHub CLI installed and authenticated for the repository you want to query. These commands read GitHub data only: they do not create, merge, close or edit a pull request, and none needs sudo.

1. Confirm the command and repository

Check the installed version and the command's contract first:

$ gh --version
gh version 2.87.3 (2026-02-23)
$ gh pr list --help
List pull requests in a GitHub repository. By default, this only lists open PRs.

Run the command inside a checked-out repository when the current directory identifies the GitHub repository. For an explicit target, use --repo OWNER/REPO:

$ cd /path/to/your/checkout
$ gh pr list --repo OWNER/REPO

Replace both placeholders. The repository form can also include a host, as HOST/OWNER/REPO, for a GitHub Enterprise installation. Fix authentication or repository detection before adding filters: a filter cannot repair a wrong repository target.

2. Understand the default list

With no filters, gh pr list returns open pull requests and fetches at most 30 items. It prints a human-readable table with the pull request number, title and head branch. The exact rows depend on the repository:

$ gh pr list --repo cli/cli --limit 1
Showing 1 of 1 open pull requests in cli/cli
...

The ellipsis represents repository data that changes over time, not literal output to copy. Set --limit deliberately when the default is not what you want: a larger limit asks for more items, it does not mean the server has more matching pull requests.

To include closed or merged work, set --state to open, closed, merged or all:

$ gh pr list --repo OWNER/REPO --state merged --limit 20

open is the default. Do not mistake an empty default result for a repository with no pull requests until you have checked the state you actually need.

3. Combine ordinary filters

Use the named flags when the condition is clear and stable. These examples are read-only:

$ gh pr list --repo OWNER/REPO --author "@me" --state open
$ gh pr list --repo OWNER/REPO --assignee USERNAME --label bug --label "priority 1"
$ gh pr list --repo OWNER/REPO --base main --head feature/login
$ gh pr list --repo OWNER/REPO --draft --limit 100

Repeated --label flags select pull requests carrying every given label. Quote labels, branch names and logins that contain spaces or shell punctuation. --author "@me" means your authenticated GitHub account. For --head, the installed command accepts a branch name but explicitly does not support the OWNER:BRANCH form.

• -s is state.
• -L is limit.
• -A is author.
• -H is head.

Use those short flags only when they remain obvious; long flags are easier to audit in scripts and runbooks.

4. Search with GitHub query syntax

For conditions with no dedicated flag, pass GitHub's pull request search syntax to --search. This example asks for open pull requests with successful status checks that still require review:

$ gh pr list --repo OWNER/REPO --search "status:success review:required"

Search syntax is separate from your shell. Keep the whole query in quotes so spaces reach gh as one argument. Search terms and qualifiers are evaluated by GitHub, so consult the official search documentation when a qualifier's meaning is unclear.

You can combine --search with ordinary flags. A useful example for finding a merged change by commit:

$ gh pr list --repo OWNER/REPO --search "SHA" --state merged

Replace SHA with the commit identifier. If the query returns nothing, check the spelling and state before assuming the commit was never introduced by a pull request.

5. Produce JSON for scripts

Human-readable tables suit a terminal but are fragile in automation. Request only the fields a script needs with --json:

$ gh pr list --repo OWNER/REPO --state open --limit 100 \
    --json number,title,headRefName,baseRefName,updatedAt,url

The result is a JSON array. Field names are defined by the installed command; examples include number, title, headRefName, baseRefName, updatedAt and url. Requesting fewer fields keeps output easier to review and reduces the chance a later script depends on an accidental detail.

Use --jq to filter that JSON. This prints one tab-separated line per pull request:

$ gh pr list --repo OWNER/REPO --json number,title,headRefName \
    --jq '.[] | [.number, .title, .headRefName] | @tsv'
12	Improve the login flow	feature/login

The example output is illustrative. Titles and branch names come from the repository, and tabs inside a title would still be part of the generated line. If another program needs JSON, keep the original array instead of parsing the table or the tab-separated display.

$ gh pr list --repo OWNER/REPO --limit 1 --json number,title

An unknown field is an immediate command error, preferable to silently receiving a different shape.

6. Use the browser only when you need it

--web opens the matching pull request list in a browser rather than showing the list in the terminal:

$ gh pr list --repo OWNER/REPO --state open --web

Keep this out of non-interactive scripts. A headless session may have no browser handler, and --json or the normal table output serves the command's purpose better anyway.

7. Separate listing from changes

gh pr list has no undo step because the examples only query data. Be careful when copying a number from its output into a different gh pr command: close, edit, merge and checkout have very different effects. Recheck the repository, pull request number and intended action before running any state-changing command.

For a failed query, rerun the smallest safe form first:

$ gh pr list --repo OWNER/REPO --limit 1
$ gh pr list --repo OWNER/REPO --state all --limit 1

If both fail, inspect authentication and host configuration rather than increasing --limit. If they succeed but a filtered command does not, add the filters back one at a time.