Find Repos, Issues and Code with gh search

Grepping through GitHub's web search is slow when you just want an API-shaped result: gh search does the same job from a terminal. The examples were checked with GitHub CLI 2.87.3 on this machine, and it works across repositories, issues, pull requests, code and commits. Allow about fifteen minutes. You need the gh command, network access and a GitHub account with an appropriate authentication setup for the searches you need.

The command only searches. It does not create, edit, close or merge anything, so none of the examples below need sudo or touch local files.

1. Check the installed command and authentication

Confirm the binary and version before relying on it:

$ command -v gh
$ gh --version
gh version 2.87.3 (2026-02-23)

Your path and date may differ. The subcommand ships with the main GitHub CLI install; the installed top-level manual describes it as a search across GitHub with five forms: code, commits, issues, prs and repos.

If a search fails with an authentication error, inspect the account and host before changing anything:

$ gh auth status

Use gh auth login only once you have decided which account and host to use. Authentication can grant access to private or internal results, so never paste a token into a shell command or a shared terminal history. Public searches may work without it, but a successful command is not proof that private repositories are visible.

2. Search repositories by words

Use gh search repos followed by a query. Separate words are search terms; quote a phrase when its words must stay together:

$ gh search repos "terminal file manager" --limit 10

The default limit is 30 results. Add --limit for a smaller, repeatable amount for human review, or a larger one for a one-off investigation. Output is designed for people by default, so fields and formatting can change between releases: do not scrape display columns when a structured format exists.

Qualifiers narrow the search without changing the repository. This asks for public Go repositories owned by the GitHub organisation, excluding archived projects:

$ gh search repos --owner=github --language=go --visibility=public --archived=false --limit 20

Other repository filters include stars, forks, topic, licence, size, owner, creation date and update date. --sort accepts forks, help-wanted-issues, stars or updated; without it, the command uses best-match ordering. --order only matters once a sort is chosen.

3. Search issues and pull requests in one repository

Issues and pull requests use separate subcommands because their filters differ. Limit a search to a known repository with --repo OWNER/REPOSITORY:

$ gh search issues "documentation" --repo=cli/cli --state=open --limit 10
$ gh search prs "authentication" --repo=cli/cli --state=open --limit 10

For issues, useful filters include author, assignee, label, milestone, state, comments, reactions, creation and update dates. Add --include-prs to gh search issues when you deliberately want pull requests in the result set. With gh search prs, filter by base or head branch, draft state, checks, review status, reviewer and merged state.

Do not infer that a result is an issue rather than a pull request from its title. Ask the right subcommand for the right type, or request the isPullRequest JSON field from the issue search.

4. Use qualifiers without losing them to the shell

GitHub search syntax supports qualifiers such as label:bug, owner:github and date expressions. A qualifier that starts with a hyphen is an exclusion, but the shell or the command's own parser can mistake that hyphen for a flag. Put the query after --:

$ gh search issues -- "renderer -label:wontfix" --repo=cli/cli

Keep the whole query in one quoted argument when it contains spaces. Here, -- ends GitHub CLI's own options and everything after is the search query. Put -label:wontfix before that boundary and gh may reject it as an unknown option instead of sending it to GitHub.

The same boundary helps repository queries too:

$ gh search repos -- "cli -topic:linux" --limit 10

PowerShell has its own additional stop-parsing token. On Linux and other Unix-like systems, the ordinary -- form is the one that matters.

5. Make results useful to scripts

Use --json to request named fields instead of parsing the display output. This returns a compact repository record:

$ gh search repos "github cli" --limit 5 --json fullName,description,url
[
  {
    "description": "...",
    "fullName": "OWNER/REPOSITORY",
    "url": "https://github.com/OWNER/REPOSITORY"
  }
]

The actual repositories and descriptions will differ. Field names are command-defined, not arbitrary JSON paths. Repository fields include names, URLs, descriptions, owners, languages, stars, forks, visibility and update timestamps. Issue and pull request searches expose fields such as number, title, URL, author, labels, state, repository and timestamps. Code search exposes path, repository, SHA, URL and text matches; commit search exposes author, committer, repository, SHA and URL.

For a quick value filter, combine --json with --jq:

$ gh search repos "shell tools" --limit 10 --json fullName,stargazersCount --jq '.[] | "\(.stargazersCount)\t\(.fullName)"'

For a complete custom layout, use --template and check the formatting rules with gh help formatting. Keep the machine-readable form in a script's data path and save human-oriented output for interactive use.

6. Search code, commits and the web

The remaining forms follow the same shape:

$ gh search code "retry backoff" --repo=cli/cli --filename '*.go' --limit 20
$ gh search commits "release notes" --repo=cli/cli --author=octocat --limit 20
$ gh search repos "observability" --web

Code search takes a required query plus filters such as repository, owner, language, file extension, filename, size and whether the match is in the file or the path. The installed manual warns this uses GitHub's legacy code search engine, so results may not match the website, and regular expressions are not available through this interface.

Commit search filters by author or committer, author or committer dates, hash, parent, tree, merge status and repository. --web opens the query in a browser instead of showing results in the terminal: treat that as an interactive convenience, not a reliable batch operation.

7. Diagnose empty or surprising results

Rerun the smallest possible query first, then add one filter at a time. Check spelling, repository owner, and whether you meant issues or prs. A valid query can return nothing because the search index has no match, the state you picked is wrong, the repository is private to another account, or a qualifier excludes everything.

Keep the exit status when scripting:

if results=$(gh search issues "YOUR QUERY" --repo=OWNER/REPOSITORY --limit 10 --json number,title,url); then
    printf '%s\n' "$results"
else
    printf '%s\n' 'gh search failed; check authentication, network access and the query' >&2
    exit 1
fi

An empty JSON array is different from a command failure: handle both cases explicitly. Do not switch off error handling just because an empty search is sometimes expected.