Home / Alt manpages / gh-search-prs(1)

  • gh-search-prs(1)
  • User command
  • linux

Search Pull Requests Reliably with gh search prs

You will build repeatable pull request searches with GitHub CLI, 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.

The route

Jump straight to the step you need, or tick off Done means at the end.

This guide describes the installed GitHub CLI 2.87.3 on this machine. The command is gh search prs, although the supplied manual page is named gh-search-prs(1). These searches query GitHub, not a local Git repository, so being inside a checkout is not required.

1. Check the installed command and authentication

Start by confirming 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, but an account is normally needed for private repositories and 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 reports that you are not logged in, run gh auth login only when you are ready to choose a host, protocol and credential flow. Do not paste a token into a shell command or save one in a script.

Checkpoint

You know the exact gh binary and version, and you have decided whether the search needs an authenticated account.

Put ordinary search words after prs. The 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 result view is intended 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 you are 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 to search for pull requests matching both words, then restricts the results to open pull requests in cli/cli. A keyword search is not the same as an exact title match. Use --match title when the words must be searched in titles rather than the issue body or comments.

3. Add the filters that describe the work

The flags are useful because they 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 include --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 a promise that the shell will expand them. Quote values containing operators or spaces.

Some flags are positive state filters. --merged selects merged pull requests; it is not a general replacement for --state closed, which also includes closed pull requests that were not merged. Use --merged-at when the merge date is the part of the question.

4. Handle search qualifiers safely

You can pass GitHub search syntax as the query itself. A leading hyphen needs care because it can look 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. GitHub's search language and the CLI flags are combined by the command, but each still has its own accepted values. Check the installed help with 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. Pull request data changes. The installed help lists fields including assignees, author, body, commentsCount, createdAt, isDraft, labels, repository, state and updatedAt.

When you need 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 merely because another search returned it. Request the fields you need, and handle an empty array as a normal result rather than as a parsing failure.

6. Sort and limit deliberately

The default sort is best-match. If you are looking for the newest work, make that choice explicit:

$ 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. A limit is a fetch limit, not proof that no further matches exist. If the result set is full, widen the limit or narrow the filters before treating it as complete.

7. Diagnose empty or unexpected results

First remove filters one at a time, starting with dates, reviewer identity and repository scope. Then run the simpler query with --limit 1 to separate a query problem from a large result set. Check spelling and case for repository names, labels and branch names.

If a branch name or keyword begins with a hyphen, use the -- separator. If a query contains shell characters, quote it. If a private repository is missing from the results, 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.

Warning

gh search prs is read-only with respect to pull requests. It does not merge, close, label or modify them. The risk is primarily disclosure: JSON fields such as body and reviewer data may contain information you should not copy into a public log. Request only the fields you need and review output before redirecting it to a shared file.

Done means

  • You confirmed the installed GitHub CLI version and login context.
  • Your query has an explicit repository or owner scope where that matters.
  • You selected state, reviewer, label, branch or date filters that match the question.
  • You used --limit and, when ordering matters, explicit --sort and --order.
  • You used --json or --jq instead of scraping a display table for automation.
  • You checked whether an empty result is expected and kept sensitive fields out of shared logs.