GitHub CLI: Search Repositories

Overview

Search for repositories across GitHub using

gh search repos

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

gh search repos [<query>] [flags]

Key Flags Reference

Repository Attributes

--language <string>

--language python

--topic <strings>

--topic machine-learning

--license <strings>

--license mit

--archived {true|false}

--archived false

--owner <strings>

--owner github

--visibility <string>

--visibility public

Popularity Metrics

--stars <number>

--stars ">1000"

--forks <number>

--forks ">100"

--followers <number>

--followers ">50"

--size <string>

--size "100..1000"

Issue Counts

--good-first-issues <number>

--good-first-issues ">=5"

--help-wanted-issues <number>

--help-wanted-issues ">=3"

Date Filters

--created <date>

--created ">2024-01-01"

--updated <date>

--updated ">2024-06-01"

Search Scope

--match <strings>

--match name

--include-forks {false|true|only}

--include-forks false

Output & Sorting

-L, --limit <int>

--limit 100

--sort <string>

--sort stars

--order <string>

--order desc

--json <fields>

--json name,stargazersCount,language

-w, --web

-w

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

-

--

✅ Correct:

gh search repos -- "search-terms -qualifier:value"

gh search repos "search-terms" --flag=-value

gh search repos "search-terms" --flag=!value

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

--

--

-qualifier:value

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 repos "cli" --language go --stars ">100"

Query Syntax with

--

gh 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

--

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 language
gh search repos -- "web framework -language:javascript"

# Exclude archived repos
gh search repos -- "cli tool -archived:true"

Multiple exclusions:

# Exclude multiple languages
gh search repos -- "game engine -language:javascript -language:python"

# Exclude archived and small repos
gh search repos -- "starter -archived:true -stars:<10"

Combine with positive filters using flags:

# Wrong - mixing syntaxes:
gh search repos "cli" --language go -archived:true  # ❌

# Correct - use query syntax for everything when excluding:
gh search repos -- "cli language:go -archived:true"  # ✅

PowerShell exclusions:

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

Common Exclusion Patterns:

gh search repos -- "starter -archived:true"

gh search repos -- "web framework -language:php"

gh search repos -- "cli -topic:deprecated"

gh search repos -- "game -language:javascript -language:css"

gh search repos -- "template -is:fork"

--include-forks false

gh search repos -- "framework -stars:<100"

gh search repos -- "library -license:gpl-3.0"

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:

gh search repos "machine learning"

Comparison operators need quotes:

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

Ranges use quotes:

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

Common Use Cases

Find popular Python repos:

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

Find repos with good first issues:

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

Find recently updated repos:

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

Find repos by topic:

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

Find repos by license:

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

Exclude archived repos:

gh search repos "cli tool" --archived false

Find repos by organization:

gh search repos --owner microsoft --visibility public

Exclude forks:

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

Find only forks:

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

Find repos in star range:

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

Exclude specific language:

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

Search in name only:

gh search repos "awesome" --match name

Common Mistakes

--language="NOT javascript"

--archived=-true

-- "-language:javascript"

-- "-archived:true"

gh search repos cli -language:js

-language

--

-- "cli -language:js"

"cli NOT language:js"

NOT

-

-- "cli -language:js"

--stars ">100" "cli -language:js"

-- "cli stars:>100 -language:js"

>

--stars ">1000"

--archived archived

--archived true

false

"machine learning"

@

@

--owner github

--%

gh --%

Installation Check

If

gh

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

  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