GitHub CLI: Search Repositories

Overview

Search for repositories across GitHub using gh search repos. Filter by stars, forks, language, topics, license, and more.

When to Use This Skill

Use this skill when searching for repositories across GitHub:

• Finding repositories by popularity (stars/forks)
• Searching by programming language or topics
• Finding repos with good first issues
• Filtering by license or archived status
• Searching in specific organizations or by owner
• Need to exclude certain results (requires -- flag)

Syntax

bash
1gh search repos [<query>] [flags]

Key Flags Reference

Repository Attributes

Popularity Metrics

Issue Counts

Date Filters

Search Scope

Output & Sorting

JSON Output Fields

createdAt, defaultBranch, description, forksCount, fullName, hasDownloads, hasIssues, hasPages, hasProjects, hasWiki, homepage, id, isArchived, isDisabled, isFork, isPrivate, language, license, name, openIssuesCount, owner, pushedAt, size, stargazersCount, updatedAt, url, visibility, watchersCount

Exclusion Syntax (Critical!)

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

✅ Correct: gh search repos -- "search-terms -qualifier:value" ❌ Wrong: gh search repos "search-terms" --flag=-value ❌ Wrong: gh search repos "search-terms" --flag=!value ❌ Wrong: gh search repos --language=-Go

Examples:

• gh search repos -- "cli -language:go" (exclude language)
• gh search repos -- "starter -archived:true" (exclude archived)
• gh search repos -- "web -topic:deprecated" (exclude topic)
• gh search repos -- "library -license:gpl-3.0" (exclude license)

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

bash
1gh search repos "cli" --language go --stars ">100"

Query Syntax with -- (required for exclusions):

bash
1gh search repos -- "cli -language:javascript -archived:true"

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

bash
1# Exclude specific language
2gh search repos -- "web framework -language:javascript"
3
4# Exclude archived repos
5gh search repos -- "cli tool -archived:true"

Multiple exclusions:

bash
1# Exclude multiple languages
2gh search repos -- "game engine -language:javascript -language:python"
3
4# Exclude archived and small repos
5gh search repos -- "starter -archived:true -stars:<10"

Combine with positive filters using flags:

bash
1# Wrong - mixing syntaxes:
2gh search repos "cli" --language go -archived:true  # ❌
3
4# Correct - use query syntax for everything when excluding:
5gh search repos -- "cli language:go -archived:true"  # ✅

PowerShell exclusions:

powershell
1# Use --% to prevent PowerShell parsing
2gh --% search repos -- "cli -language:javascript"

Common Exclusion Patterns:

2. Special Values

• Multiple topics: --topic unix,terminal
• Boolean flags: --archived false or --archived true
• Fork inclusion: --include-forks false|true|only

3. Quoting Rules

Multi-word search:

bash
1gh search repos "machine learning"

Comparison operators need quotes:

bash
1gh search repos "python" --stars ">1000"

Ranges use quotes:

bash
1gh search repos "cli" --stars "100..500"

Common Use Cases

Find popular Python repos:

bash
1gh search repos "data science" --language python --stars ">5000"

Find repos with good first issues:

bash
1gh search repos --language javascript --good-first-issues ">=10"

Find recently updated repos:

bash
1gh search repos "react" --updated ">2024-01-01" --stars ">100"

Find repos by topic:

bash
1gh search repos --topic machine-learning --language python

Find repos by license:

bash
1gh search repos "web framework" --license mit,apache-2.0

Exclude archived repos:

bash
1gh search repos "cli tool" --archived false

Find repos by organization:

bash
1gh search repos --owner microsoft --visibility public

Exclude forks:

bash
1gh search repos "starter" --include-forks false

Find only forks:

bash
1gh search repos "template" --include-forks only

Find repos in star range:

bash
1gh search repos "game engine" --stars "100..1000"

Exclude specific language:

bash
1gh search repos -- "cli -language:go"

Search in name only:

bash
1gh search repos "awesome" --match name

Common Mistakes

Installation Check

If gh command not found:

bash
1# Check if gh is installed
2which gh
3
4# Install: https://cli.github.com/manual/installation

If not authenticated:

bash
1# Authenticate with GitHub
2gh auth login

Comparison Operators

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

Common Licenses

• mit - MIT License
• apache-2.0 - Apache License 2.0
• gpl-3.0 - GNU GPL v3
• bsd-2-clause - BSD 2-Clause
• bsd-3-clause - BSD 3-Clause
• mpl-2.0 - Mozilla Public License 2.0
• isc - ISC License

Match Field Options

• name - Search repository names only
• description - Search descriptions only
• readme - Search README files only

Example: gh search repos "documentation" --match readme

Related

• GitHub search syntax: https://docs.github.com/search-github/searching-on-github/searching-for-repositories
• For searching other resources: gh-search-code, gh-search-commits, gh-search-issues, gh-search-prs