GH-SEARCH-REPOS(1)

💅 GH-SEARCH-REPOS(1) — like, the GitHub CLI manual, but make it make sense

okay bestie, welcome to gh-search-repos from the GitHub CLI manual — this is the page where we learn how to go find repositories on GitHub like the main character we are 🔍✨

---

✨ NAME ✨

gh-search-repos — search for repositories, fr fr 🫶

---

🎀 SYNOPSIS 🎀

gh search repos [<query>] [flags]

that's it. that's the whole vibe. <query> is optional, flags are optional, chaos is optional but encouraged 💖

---

🌸 DESCRIPTION 🌸

So you wanna search for repositories on GitHub. Iconic. Slay. Let's go 🦋

This command is lowkey flexible: you can build your query using the GitHub search syntax, you can use the parameter and qualifier flags, or — and this is the fun part — you can mix both. Combination queen behavior 👑

The GitHub search syntax is documented right here, and yes you should read it, it's giving homework but the useful kind:

⟨https://docs.github.com/search-github/searching-on-github/searching-for-repositories⟩

And heads up: if your search query has a hyphen in it and you're like "why is this being weird 😭", run gh search --help for the deets on handling search queries containing a hyphen. Not me almost losing my mind over a dumb little dash 💀

---

💅 OPTIONS 💅

• --archived — filter based on the repository archived state, and it takes {true|false} 🗂️
• --created <date> — filter based on the created at date 🗓️
• --followers <number> — filter based on how many followers the repo owner has 👀
• --forks <number> — filter on the number of forks 🍴
• --good-first-issues <number> — filter on how many issues carry the 'good first issue' label — perfect for your first contribution era 🌱
• --help-wanted-issues <number> — filter on how many issues carry the 'help wanted' label 🙋‍♀️
• --include-forks <string> — include forks in the fetched repositories: {false|true|only} 🍴
• -q, --jq <expression> — filter JSON output using a jq expression, chef's kiss for pipelines 🧑‍🍳
• --json <fields> — output JSON with the specified fields (peep the list further down 👇)
• --language <string> — filter based on the coding language 💻
• --license <strings> — filter based on license type 📜
• -L, --limit <int> (default 30) — maximum number of repositories to fetch 🚦
• --match <strings> — restrict the search to a specific field of the repository: {name|description|readme} 🎯
• --number-topics <number> — filter on the number of topics 🏷️
• --order <string> (default "desc") — order of repositories returned, and ngl it's ignored unless the '--sort' flag is specified: {asc|desc} ⬆️⬇️
• --owner <strings> — filter on owner 👤
• --size <string> — filter on a size range, in kilobytes 📦
• --sort <string> (default "best-match") — sort the fetched repositories: {forks|help-wanted-issues|stars|updated} 🔥
• --stars <number> — filter on the number of stars ⭐
• -t, --template <string> — format JSON output using a Go template; see "gh help formatting" 🎨
• --topic <strings> — filter on topic 🧵
• --updated <date> — filter on the last updated at date 🔄
• --visibility <strings> — filter based on visibility: {public|private|internal} 🕵️‍♀️
• -w, --web — open the search query in the web browser, chaos mode activated 🌐

---

🌈 JSON FIELDS 🌈

If you're passing --json <fields>, these are the ones that exist, and yes I'm listing all of them because we don't do half-finished over here 💖

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

---

🧚 EXIT CODES 🧚

• 0: successful execution — we ate 🍽️
• 1: error — it's giving oops 😭
• 2: command canceled
• 4: authentication required — log in bestie 🔐

NOTE: specific commands may have additional exit codes. Refer to the command's help for more information. No cap, always check 💀

---

⭐ EXAMPLE ⭐

# Search repositories matching set of keywords "cli" and "shell"
$ gh search repos cli shell

# Search repositories matching phrase "vim plugin"
$ gh search repos "vim plugin"

# Search repositories using raw search qualifiers as separate arguments
$ gh search repos topic:github 'stars:>5000'

# Search repositories public repos in the microsoft organization
$ gh search repos --owner=microsoft --visibility=public

# Search repositories with a set of topics
$ gh search repos --topic=unix,terminal

# Search repositories by coding language and number of good first issues
$ gh search repos --language=go --good-first-issues=">=10"

# Search repositories without topic "linux"
$ gh search repos -- -topic:linux

# Search repositories excluding archived repositories
$ gh search repos --archived=false

not the -- -topic:linux with the double dash… the way that hyphen handling haunts us 🫠 iykyk

---

👑 SEE ALSO 👑

gh-search(1) — go read the parent page too, it's the whole family 🫶

---

okay that's the page!! this was GitHub CLI v2.102.0, dated Oct 2026, and honestly? iconic of them. mwah 💋🌸 go search some repos bestie, you're gonna slay ✨💜