name	gh-search-issues
description	Use when searching GitHub issues ACROSS REPOSITORIES or organizations - provides syntax for filtering by labels, state, assignees, authors, comments, reactions, dates. For current repo issues, use gh issue list instead.

GitHub CLI: Search Issues

Overview

Search for issues across GitHub repositories using gh search issues. Add --include-prs flag to also search pull requests.

⚠️ CRITICAL: Search vs List Commands

gh search issues - 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 issues in the microsoft organization", "Search for bugs in kubernetes repos"

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

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

When user says "my issues" or "issues here" → Use gh issue list (NOT this skill) When user specifies repo/org or cross-repo search → Use gh search issues (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 my open issues across GitHub")
Complex queries needing search qualifiers (e.g., "comments>50 across microsoft repos")

DO NOT use this skill when:

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

Syntax

gh search issues [<query>] [flags]

Key Flags Reference

User Filters

Flag	Purpose	Example
`--author <string>`	Created by user	`--author octocat`
`--assignee <string>`	Assigned to user	`--assignee @me`
`--mentions <user>`	Mentions specific user	`--mentions octocat`
`--commenter <user>`	Commented by user	`--commenter octocat`
`--team-mentions <string>`	Mentions team	`--team-mentions myteam`

Issue Attributes

Flag	Purpose	Example
`--label <strings>`	Has specific labels	`--label bug,urgent`
`--state <string>`	Issue state: open or closed	`--state open`
`--milestone <title>`	In specific milestone	`--milestone v1.0`
`--locked`	Locked conversation	`--locked`
`--no-label`	Has no labels	`--no-label`

Repository Filters

Flag	Purpose	Example
`--owner <strings>`	Repository owner	`--owner github`
`-R, --repo <strings>`	Specific repository	`--repo cli/cli`
`--language <string>`	Repository language	`--language go`
`--visibility <strings>`	Repo visibility	`--visibility public`
`--archived`	In archived repos	`--archived`

Engagement Metrics

Flag	Purpose	Example
`--comments <number>`	Number of comments	`--comments ">10"`
`--reactions <number>`	Reaction count	`--reactions ">5"`
`--interactions <number>`	Comments + reactions	`--interactions ">20"`

Date Filters

Flag	Purpose	Example
`--created <date>`	Creation date	`--created ">2024-01-01"`
`--updated <date>`	Last update date	`--updated ">2024-06-01"`
`--closed <date>`	Close date	`--closed "<2024-12-31"`

Search Scope

Flag	Purpose	Example
`--match <strings>`	Search in: title, body, comments	`--match title`
`--include-prs`	Include pull requests	`--include-prs`

Output & Sorting

Flag	Purpose	Example
`-L, --limit <int>`	Max results (default: 30)	`--limit 100`
`--sort <string>`	Sort by: comments, created, reactions, etc.	`--sort comments`
`--order <string>`	Sort direction: asc or desc	`--order desc`
`--json <fields>`	JSON output	`--json number,title,state`
`-w, --web`	Open in browser	`-w`

JSON Output Fields

assignees, author, authorAssociation, body, closedAt, commentsCount, createdAt, id, 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 issues -- "search-terms -qualifier:value" ❌ Wrong: gh search issues "search-terms" --flag=-value ❌ Wrong: gh search issues "search-terms" --flag=!value ❌ Wrong: gh search issues --label!=bug

Examples:

gh search issues -- "bug -label:wontfix" (exclude label)
gh search issues -- "crash -assignee:olduser" (exclude assignee)
gh search issues -- "error -author:bot" (exclude author)
gh search issues -- "performance -milestone:v1.0" (exclude milestone)

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 issues "bug" --label urgent --state open

Query Syntax with -- (required for exclusions):

gh search issues -- "bug -label:duplicate -label:wontfix"

⚠️ 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:

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

Examples:

Single exclusion:

# Exclude specific label
gh search issues -- "bug -label:duplicate"

# Exclude specific assignee
gh search issues -- "crash -assignee:olduser"

Multiple exclusions:

# Exclude multiple labels
gh search issues -- "bug -label:duplicate -label:wontfix"

# Exclude author and label
gh search issues -- "performance -author:bot -label:invalid"

Combine with positive filters using flags:

# Wrong - mixing syntaxes:
gh search issues "bug" --state open -label:duplicate  # ❌

# Correct - use query syntax for everything when excluding:
gh search issues -- "bug state:open -label:duplicate"  # ✅

PowerShell exclusions:

# Use --% to prevent PowerShell parsing
gh --% search issues -- "bug -label:duplicate"

Common Exclusion Patterns:

User Request	Command
"Find bugs but not duplicates"	`gh search issues -- "bug -label:duplicate"`
"Issues not assigned to anyone"	`gh search issues -- "enhancement -assignee:*"` (use `--no-assignee` instead)
"Open issues excluding specific label"	`gh search issues -- "state:open -label:wontfix"`
"Issues excluding multiple labels"	`gh search issues -- "crash -label:duplicate -label:invalid"`
"Issues not in milestone"	`gh search issues -- "bug -milestone:v1.0"`
"Issues not by bot authors"	`gh search issues -- "error -author:dependabot -author:renovate"`

2. Special Values

@me - Current authenticated user

gh search issues --assignee @me --state open

3. Quoting Rules

Multi-word search:

gh search issues "memory leak"

Labels with spaces:

gh search issues -- 'crash label:"bug fix"'

Comparison operators need quotes:

gh search issues "performance" --comments ">10"

Common Use Cases

Find your open issues across all of GitHub:

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

Find unassigned bugs in a specific org:

gh search issues --label bug --no-assignee --state open --owner kubernetes

Find highly discussed issues in a specific repo:

gh search issues --comments ">50" --state open --repo microsoft/vscode

Find stale issues across multiple repos:

gh search issues --state open --updated "<2023-01-01" --owner myorg

Search issues AND PRs in an organization:

gh search issues "authentication" --include-prs --state open --owner github

Exclude specific labels in cross-repo search:

gh search issues -- "crash -label:duplicate -label:wontfix" --repo cli/cli

Find issues in milestone across repos:

gh search issues --milestone v2.0 --state open --owner golang

Find issues by title only in specific language repos:

gh search issues "error in:title" --state open --language rust

Common Mistakes

Mistake	Problem	Fix
`--label="NOT duplicate"` or `--assignee=-bot`	Flag syntax doesn't support negation	Use query: `-- "-label:duplicate"` or `-- "-assignee:bot"`
`gh search issues bug -label:duplicate`	`-label` interpreted as flag	Use `--`: `-- "bug -label:duplicate"`
`"bug NOT label:duplicate"`	`NOT` keyword doesn't work	Use `-`: `-- "bug -label:duplicate"`
Mixing syntaxes: `--state open "bug -label:dup"`	Can't mix flags with query qualifiers	Use query for all: `-- "bug state:open -label:dup"`
`--assignee @username`	Invalid `@` prefix	Use `@me` or drop `@`: `--assignee username`
Not quoting comparisons	Shell interprets `>`	Quote: `--comments ">10"`
`label:"bug fix"` outside quotes	Shell parsing error	Quote query: `'label:"bug fix"'`
Forgetting `--include-prs`	Misses pull requests	Add: `--include-prs`
PowerShell without `--%`	Breaks with exclusions	Add: `gh --%`

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 issues "crash in:title" --state open

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-prs, gh-search-repos

gh-search-issues

Install Skill

SKILL.md