Gh Search Issues

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 [] [flags]

Key Flags Reference

User Filters

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

Issue Attributes

| Flag | Purpose | Example | |------|---------|---------| | --label | Has specific labels | --label bug,urgent | | --state | Issue state: open or closed | --state open | | --milestone | In specific milestone | --milestone v1.0 | | --locked | Locked conversation | --locked | | --no-label | Has no labels | --no-label |

Repository Filters

| Flag | Purpose | Example | |------|---------|---------| | --owner | Repository owner | --owner github | | -R, --repo | Specific repository | --repo cli/cli | | --language | Repository language | --language go | | --visibility | Repo visibility | --visibility public | | --archived | In archived repos | --archived |

Engagement Metrics

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

Date Filters

| Flag | Purpose | Example | |------|---------|---------| | --created | Creation date | --created ">2024-01-01" | | --updated | Last update date | --updated ">2024-06-01" | | --closed | Close date | --closed " | Search in: title, body, comments | --match title | | --include-prs | Include pull requests | --include-prs |

Output & Sorting

| Flag | Purpose | Example | |------|---------|---------| | -L, --limit | Max results (default: 30) | --limit 100 | | --sort | Sort by: comments, created, reactions, etc. | --sort comments | | --order | Sort direction: asc or desc | --order desc | | --json | 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:

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 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

``bash 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 "` | 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:
```bash
# 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

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: aaddrick
• Source: aaddrick/gh-cli-search
• License: MIT

Install and usage instructions live in the source repository linked above.