List and Filter Pull Requests with gh pr list

You will finish with a small set of commands for finding pull requests from a terminal, narrowing the result by state, author, branch or label, and emitting fields that scripts 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 requires sudo.

1. Confirm the command and repository

Check the installed version and the command 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. If authentication or repository detection fails, fix that 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 containing 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, but 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 all of the given labels. Quote labels, branch names and logins when they 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.

Use short flags only when they remain obvious: -s is state, -L is limit, -A is author and -H is head. Long flags are easier to audit in scripts and runbooks.

4. Search with GitHub query syntax

For conditions that do not have a dedicated flag, pass GitHub's pull request search syntax to --search. For example, this 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 or its meaning is unclear.

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

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

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

5. Produce JSON for scripts

Human-readable tables are useful at a terminal but 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 that 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. That is 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 presenting 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 the command's purpose is then better served by --json or the normal table output.

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: commands such as close, edit, merge and checkout have 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.