Read Your Pull Request Queue with gh pr status

Use gh pr status to see which pull requests need you, with merge conflicts flagged and fields ready for a script. It takes a few minutes. The command is read-only: it reports GitHub state and never approves, merges, closes or updates a pull request.

Before you start

• You need: GitHub CLI, an authenticated account with access to the repository, and a local checkout if you want the command to infer the current repository.
• Checked against: GitHub CLI 2.87.3, on a system whose manpage is dated February 2026.
• Live data. The command contacts GitHub, so results can change between runs.

Check the version and authentication first:

gh --version
gh auth status

Expected version output begins with:

gh version 2.87.3

1. See the relevant pull requests

Run the command from a checkout of the repository you want to inspect:

cd /path/to/your/repository
gh pr status

The summary groups work under headings such as the current branch, pull requests created by you, and requests for your review. A line can show the pull request number, title, source branch, check state and review state. GitHub CLI decides which pull requests are relevant, so this is not a list of every open pull request.

A typical result has this shape:

Current branch
  #42 Improve cache handling [alice:cache-fix]
   - Checks passing - Approved

Created by you
  You have no open pull requests

Requesting a code review from you
  #45 Document the deployment check [docs]
  - 2/3 checks failing - Review required

These are illustrative values. Do not treat the labels as a machine-readable interface. For the individual check details of one pull request, use gh pr checks, for example:

gh pr checks 45

2. Add merge conflict status

The default summary does not show each pull request's merge conflict state. Add --conflict-status when that matters:

gh pr status --conflict-status

It is handy before you spend time on a review or ask an author to update a branch. It still only reports state and does not resolve conflicts or change the branch. The result is a snapshot, so re-run it before deciding anything about merging.

3. Inspect a repository without changing directory

Use the inherited --repo option with a repository name in OWNER/REPO form:

gh pr status --repo EXAMPLE_OWNER/EXAMPLE_REPO

For a GitHub Enterprise host, include the host in the value:

gh pr status --repo github.example.com/EXAMPLE_OWNER/EXAMPLE_REPO

Replace the uppercase placeholders with a real owner and repository. Your account must be able to read that repository. This form saves you from accidentally inspecting the checkout in the current directory when you meant a different project.

4. Use JSON when another command needs the result

Ask for only the fields you need with --json. This example requests identifiers, titles, branch names, review decisions and merge state:

gh pr status --repo EXAMPLE_OWNER/EXAMPLE_REPO   --json number,title,headRefName,reviewDecision,mergeStateStatus

The installed manpage documents the available field names. They include number, title, author, headRefName, baseRefName, reviewDecision, mergeable, mergeStateStatus, statusCheckRollup, state and url. Ask for each field explicitly rather than assuming the human summary stays stable.

Use --jq for a small projection. This example prints pull request numbers and titles:

gh pr status --repo EXAMPLE_OWNER/EXAMPLE_REPO   --json number,title   --jq '.[] | "#(.number) (.title)"'

In a shell script, preserve the exit status from gh and treat an empty result as normal. Do not mistake an empty list for successful authentication against the wrong repository.

5. Format a small human report

--template applies a Go template to the JSON result. It gives a repeatable terminal report with more structure than screen scraping:

gh pr status --repo EXAMPLE_OWNER/EXAMPLE_REPO   --json number,title,url   --template '{{range .}}#{{.number}} {{.title}} - {{.url}}{{"\n"}}{{end}}'

Use either --jq or --template for a given output transformation. Both work on the JSON representation, and neither adds fields the command did not request. If a template fails, simplify it and check the field name against gh pr status --help.

Common traps and recovery

• Wrong repository: run gh repo view --json nameWithOwner in the checkout, or use an explicit --repo value.
• Missing or stale authentication: run gh auth status. Re-authentication changes credentials, so check the selected host and account first.
• Too little check detail: gh pr status summarises checks. Use gh pr checks NUMBER for one pull request's check list. Its JSON output has check-specific fields such as name, state, bucket and link.
• Treating the result as a merge decision: review status, checks and mergeability are separate signals. Recheck them immediately before any write action with another command.
• Quoting a jq expression badly: use single quotes around the expression in Bash, as shown above. Keep untrusted pull request text inside the JSON transformation rather than building shell commands from it.