List Your Review Queue with gh search prs

Your review queue is scattered across a dozen repositories, and the GitHub notifications page is not helping. gh search prs lets you build repeatable pull request searches, narrow them with repository and review filters, and inspect the result as JSON when a table is not enough. Allow about ten minutes.

• You need: the gh package, a working network connection, and access to the GitHub account or host containing the repositories you want to search.
• Version: this guide describes the installed GitHub CLI 2.87.3. The command is gh search prs, although the manual page is named gh-search-prs(1).
• No checkout needed: these searches query GitHub, not a local Git repository.

1. Check the installed command and authentication

Confirm which executable will run and which version it provides:

$ command -v gh
/home/linuxbrew/.linuxbrew/bin/gh
$ gh --version
gh version 2.87.3 (2026-02-23)

Searches against public repositories may work without an interactive login. An account is normally needed for private repositories, and it gives you a clearer rate-limit position. Check the current login state without changing anything:

$ gh auth status

If this reports an account or host you recognise, continue. If it says you are not logged in, run gh auth login only when you are ready to choose a host, protocol and credential flow.

2. Start with a small, scoped search

Put ordinary search words after prs. This example searches the GitHub CLI repository and asks for one open result, which keeps the output easy to inspect:

$ gh search prs --repo cli/cli --state open --limit 1

The default view is meant for people reading at a terminal. The local manual sets the default limit to 30, so a broad search can return more rows than you expected. Set --limit deliberately when testing a query or feeding its output into another step.

To combine keywords, pass them as separate arguments:

$ gh search prs fix bug --repo cli/cli --state open --limit 10

This asks GitHub for pull requests matching both words, then restricts the results to open pull requests in cli/cli.

3. Add the filters that describe the work

Flags keep routine search rules visible in the command. For example, find open pull requests currently requesting your review:

$ gh search prs --review-requested=@me --state=open --limit 20

Find pull requests assigned to you that have already merged:

$ gh search prs --assignee=@me --merged --limit 20

Repository and ownership filters are separate. Use --repo=OWNER/REPOSITORY for one or more named repositories, or --owner OWNER for repositories belonging to an owner. For a team review queue, use --review-requested=ORGANISATION/TEAM when that is the identifier your GitHub host accepts.

Other practical filters: --label bug, --draft, --base main, --head feature-branch, --language go, --created YYYY-MM-DD, --updated YYYY-MM-DD and --visibility private. The date values are GitHub search date expressions, not something the shell will expand. Quote values containing operators or spaces.

4. Handle search qualifiers safely

You can pass GitHub search syntax as the query itself. A leading hyphen needs care because it looks like a command-line option. The manual documents the -- separator for this case:

$ gh search prs -- -label:bug

That searches for pull requests without the bug label. Put the separator before the search expression, and quote a query when it contains spaces or shell metacharacters:

$ gh search prs -- 'repo:cli/cli is:open review:approved'

Do not mix a guessed qualifier with a flag and assume the meanings are identical. The command combines GitHub's search language with the CLI flags, but each has its own accepted values. Check gh search prs --help before putting a new expression in automation.

5. Make results script-friendly with JSON

Use --json to request named fields instead of scraping the human-readable table. This example asks for the pull request number, title and URL:

$ gh search prs --repo cli/cli --state open --limit 5 \
    --json number,title,url
[{"number":14485,"title":"Example title","url":"https://github.com/cli/cli/pull/14485"}]

The values above illustrate the shape, not a permanent result, because pull request data changes. The installed help lists fields including assignees, author, body, commentsCount, createdAt, isDraft, labels, repository, state and updatedAt.

For one value per result, add --jq. Keep the expression in single quotes so the shell does not interpret its punctuation:

$ gh search prs --repo cli/cli --state open --limit 5 \
    --json number,title --jq '.[] | "#\(.number) \(.title)"'

For a stable report format, --template is another documented option. Do not assume a field is present just because another search returned it: request the fields you need, and treat an empty array as a normal result, not a parsing failure.

6. Sort and limit deliberately

The default sort is best-match. If you want the newest work, say so:

$ gh search prs --repo cli/cli --state open \
    --sort updated --order desc --limit 20

The manual lists sort values such as comments, reactions, created and updated. --order is ignored unless --sort is supplied, and its default is descending.

7. Diagnose empty or unexpected results

• Remove filters one at a time. Start with dates, reviewer identity and repository scope.
• Shrink the query. Run the simpler version with --limit 1 to separate a query problem from a large result set.
• Check spelling and case. Repository names, labels and branch names all count.
• Mind the hyphen and the shell. If a branch name or keyword begins with a hyphen, use the -- separator. If a query contains shell characters, quote it.
• Missing private repository. Check gh auth status and the account's access rather than retrying indefinitely.

A network, permission or API error is different from a successful search with no matches. Preserve the command's error text when diagnosing automation.