Search GitHub Repositories from the Shell with gh

You will finish with repeatable searches for GitHub repositories, including owner, language, topic, activity and archive filters, plus machine-readable output for scripts. The examples use GitHub CLI 2.87.3, installed here on 24 September 2026.

Allow about ten minutes. You need gh installed and a network connection. Public searches work without changing local files, but private or internal results depend on the account and host you are using. No command in this guide needs elevated privileges.

1. Check the installed command

Confirm the version and read the option list from the same binary that will run your search:

$ gh --version
gh version 2.87.3 (2026-02-23)
$ gh search repos --help

The command is gh search repos [query] [flags]. The default is at most 30 repositories, sorted by best match. A search is read-only: it does not clone, edit, archive or delete a repository.

2. Search with words and phrases

Separate words are search terms. Quote a phrase so that your shell passes it as one argument:

$ gh search repos cli shell --limit 5
$ gh search repos "vim plugin" --limit 5

The first search asks GitHub for repositories matching both words. The second passes one multi-word phrase. Search is not case sensitive. The normal human-readable output includes repository names and summary details, but the exact display is not a stable interface for a script.

GitHub's repository search also supports raw qualifiers. Put a qualifier in the query when the repository search syntax expresses the condition more directly:

$ gh search repos topic:github 'stars:>5000' --limit 10
$ gh search repos -- -topic:linux --limit 10

The -- before -topic:linux stops option parsing, so the leading hyphen reaches GitHub as a search term. This is an easy place to lose time: a query beginning with a hyphen can be mistaken for a gh option if you omit the separator. Quote values containing shell metacharacters, spaces or comparison operators.

3. Add repository filters

Use flags when you want the command's named parameters to describe the search. This example finds public repositories owned by an organisation:

$ gh search repos --owner=microsoft --visibility=public --limit 10

For a language and issue signal, use a quoted comparison:

$ gh search repos --language=go --good-first-issues='>=10' --limit 10

Other useful repository filters include --stars, --forks, --followers, --created, --updated, --license, --topic, --number-topics, --size and --match. The last one restricts matching to name, description or readme.

Archived repositories are included unless you say otherwise. Exclude them explicitly when you are looking for an active starting point:

$ gh search repos --archived=false --limit 10

Forks are a separate trap. The --include-forks flag accepts false, true or only. Without an explicit fork choice, do not assume that a result set contains every fork. For example:

$ gh search repos --topic=unix,terminal --include-forks=only --limit 10

4. Control ordering and result count

--limit controls the maximum number fetched, not a promise that many will exist. Keep it small while refining a query:

$ gh search repos --language=rust --sort=updated --order=desc --limit 5

The installed command supports forks, help-wanted-issues, stars and updated for --sort. --order is ignored unless a sort is selected. If you omit it, the default order is descending. If you omit --sort, the default sort is best match rather than an activity ranking.

5. Request fields for a script

Use --json when another command needs structured data. Ask only for the fields you need:

$ gh search repos --language=go --archived=false --limit 5 \
    --json fullName,description,stargazersCount,url

The available fields include fullName, description, language, license, stargazersCount, forksCount, updatedAt, isArchived, isFork, isPrivate, visibility and url. Ask for gh search repos --help to see the complete list for this installed release.

Pipe JSON to --jq when you want a simple projection. This prints one URL per line:

$ gh search repos --language=go --archived=false --limit 5 \
    --json fullName,url --jq '.[] | [.fullName, .url] | @tsv'

Keep the query, filters and limit explicit in automation. Do not parse the default table output, because presentation can change between CLI releases. Treat repository descriptions and names as untrusted text if you pass them into another program.

6. Diagnose an empty or unexpected result

First run the same search with a small limit and no optional filter. Then add conditions one at a time. A query can be valid and still return nothing because the owner, language, topic or date condition is too narrow.

Check the most common boundaries:

• A phrase in quotes is one term; unquoted words are separate terms.
• A comparison such as >=10 should be quoted so the shell does not reinterpret it.
• A leading negative qualifier needs -- before it.
• --order has no effect without --sort.
• A private or internal result requires access through the current GitHub account and host.

To open the query in a browser rather than print results, add --web:

$ gh search repos --topic=terminal --web

This launches the configured browser and is the only example here that intentionally moves the result into another application. If that is unsuitable for a restricted workstation, leave out --web and use the terminal or JSON output.