aaddrick/gh-cli-search/gh-search-prs

GitHub CLI: Search Pull Requests

Overview

Search for pull requests across GitHub repositories using gh search prs. Includes PR-specific filters like draft status, merge state, review status, and CI checks.

⚠️ CRITICAL: Search vs List Commands

`gh search prs` - GitHub-wide search (THIS SKILL):

• Searches across multiple repositories or organizations
• Searches in specific repos outside your current directory
• Uses GitHub's search query syntax with qualifiers
• Examples: "Find draft PRs in kubernetes repos", "Search for approved PRs in microsoft org"

`gh pr list` - Current repository only (NOT THIS SKILL):

• Lists PRs in your current working directory's repo
• Uses simple flag-based filtering
• Examples: "Show my PRs in this repo", "List open PRs here"

When user says "my PRs" or "PRs here" → Use `gh pr list` (NOT this skill) When user specifies repo/org or cross-repo search → Use `gh search prs` (THIS skill)

When to Use This Skill

Use this skill when the user explicitly indicates:

• Searching across multiple repositories or organizations
• Searching in a specific repo (e.g., "in kubernetes/kubernetes")
• Cross-GitHub searches (e.g., "all draft PRs across the organization")
• Complex queries needing search qualifiers (e.g., "approved PRs with >10 comments in golang repos")

DO NOT use this skill when:

• User asks about "PRs in this repo" or "my PRs here"
• No repo/org is specified and context is clearly current repository
• Use gh pr list for current repo operations instead

Syntax

gh search prs [<query>] [flags]

Key Flags Reference

PR-Specific Filters

User Filters

PR Attributes

Repository Filters

Engagement Metrics

Date Filters

Search Scope

Output & Sorting

JSON Output Fields

assignees, author, authorAssociation, body, closedAt, commentsCount, createdAt, id, isDraft, isLocked, isPullRequest, labels, number, repository, state, title, updatedAt, url

Exclusion Syntax (Critical!)

When using inline query exclusions (negations with -), you MUST use the -- separator:

✅ Correct: gh search prs -- "search-terms -qualifier:value" ❌ Wrong: gh search prs "search-terms" --flag=-value ❌ Wrong: gh search prs "search-terms" --flag=!value ❌ Wrong: gh search prs --label=-WIP

Examples:

• gh search prs -- "feature -label:draft" (exclude label)
• gh search prs -- "fix -is:draft" (exclude draft PRs)
• gh search prs -- "deploy -author:bot" (exclude author)
• gh search prs -- "security -review:changes_requested" (exclude review status)

Why the `--` separator is required: The -- tells the shell to stop parsing flags and treat everything after it as arguments. Without it, -qualifier:value inside quotes may be misinterpreted.

Critical Syntax Rules

When to Use Flag Syntax vs Query Syntax

Decision Tree:

Does your search include:
  - Any exclusions (NOT, minus, without, except)?  → Use Query Syntax with `--`
  - Complex boolean logic (OR, AND)?              → Use Query Syntax with `--`
 
Otherwise:
  - Simple positive filters only?                  → Use Flag Syntax

Flag Syntax (for positive filters):

gh search prs "refactor" --draft --state open

Query Syntax with `--` (required for exclusions):

gh search prs -- "refactor -label:wip -is:draft"

⚠️ NEVER mix both syntaxes in a single command!

1. Exclusions and Negations

CRITICAL: When excluding results, you MUST use query syntax with the -- separator.

Exclusion Syntax Rules:

1. Use the -- separator before your query
2. Use -qualifier:value format (dash prefix for negation)
3. Quote the entire query string

Examples:

Single exclusion:

# Exclude specific label
gh search prs -- "refactor -label:wip"
 
# Exclude draft PRs
gh search prs -- "feature -is:draft"

Multiple exclusions:

# Exclude multiple labels
gh search prs -- "bug -label:wip -label:blocked"
 
# Exclude draft PRs and specific review status
gh search prs -- "security -is:draft -review:changes_requested"

Combine with positive filters using flags:

# Wrong - mixing syntaxes:
gh search prs "fix" --state open -label:wip  # ❌
 
# Correct - use query syntax for everything when excluding:
gh search prs -- "fix state:open -label:wip"  # ✅

PowerShell exclusions:

# Use --% to prevent PowerShell parsing
gh --% search prs -- "refactor -label:wip"

Common Exclusion Patterns:

2. Special Values

• @me - Current authenticated user

``bash gh search prs --review-requested @me --state open ``

3. Review Status Values

• none - No reviews
• required - Review required
• approved - Approved
• changes_requested - Changes requested

4. Check Status Values

• pending - Checks pending
• success - All checks passed
• failure - Checks failed

5. Quoting Rules

Multi-word search:

gh search prs "bug fix"

Labels with spaces:

gh search prs -- 'refactor label:"needs review"'

Comparison operators need quotes:

gh search prs "performance" --comments ">5"

Common Use Cases

Find your open PRs across all of GitHub:

gh search prs --author @me --state open

Find PRs awaiting your review in an organization:

gh search prs --review-requested @me --state open --owner kubernetes

Find draft PRs in a specific repo:

gh search prs --draft --repo microsoft/vscode

Find merged PRs in date range across an org:

gh search prs --merged --merged-at "2024-01-01..2024-12-31" --owner golang

Find PRs with failing checks in specific repos:

gh search prs --checks failure --state open --repo cli/cli

Find approved PRs not yet merged in a repo:

gh search prs --review approved --state open --repo kubernetes/kubernetes

Find PRs by base branch in an organization:

gh search prs --base main --state open --owner github

Find PRs with specific head branch pattern across repos:

gh search prs --head feature-* --state open --language go

Exclude specific labels in cross-repo search:

gh search prs -- "refactor -label:wip -label:draft" --owner myorg

Find stale PRs across multiple repos:

gh search prs --state open --updated "<2024-01-01" --owner rust-lang

Common Mistakes

Installation Check

If gh command not found:

# Check if gh is installed
which gh
 
# Install: https://cli.github.com/manual/installation

If not authenticated:

# Authenticate with GitHub
gh auth login

Comparison Operators

• > - Greater than
• >= - Greater than or equal
• < - Less than
• <= - Less than or equal
• .. - Range: 10..50 or 2024-01-01..2024-12-31

Field Qualifiers

Use in: to search specific fields:

• in:title - Search in title only
• in:body - Search in body only
• in:comments - Search in comments only

Example: gh search prs "authentication in:title" --state open

Related

• GitHub search syntax: https://docs.github.com/search-github/searching-on-github/searching-issues-and-pull-requests
• For searching other resources: gh-search-code, gh-search-commits, gh-search-issues, gh-search-repos