gh-search

Search for code containing specific keywords

$ gh search code [keyword1 keyword2 ...]

$ gh search issues "[search_phrase]"

$ gh search commits --author [username]

$ gh search prs --assignee @me --state open

$ gh search repos --owner [org_name] --topic [topic_name]

$ gh search issues -- "[search_query] -label:[label_name]"

$ gh --% search issues -- "[search_query] -label:[label_name]"

$ gh search [subcommand] [[-w|--web]] [query]

gh search <SUBCOMMAND> <query> [flags]

Examples:
gh search repos "cli tool" --language go --stars ">=100"
gh search issues "bug report" --repo cli/cli --state open --label "help wanted"
gh search codes "func main" --repo cli/cli --language go

-h, --help
    Show help for the gh search command or its subcommands.

-f, --format <string>
    Output format: {json|text}. Specifies how the search results should be presented.

-q, --jq <expression>
    Filter JSON output using a jq expression for precise data extraction.

-t, --template <string>
    Format JSON output using a Go template for custom display.

--paginate
    Fetch all pages of results instead of just the first page.

--archived (repos subcommand)
    Include archived repositories in the search results.

--language <string> (repos, codes subcommands)
    Filter results by programming language (e.g., `go`, `python`).

--stars <string> (repos subcommand)
    Filter repositories by the number of stars (e.g., `">100"`, `"10..20"`).

--topic <string> (repos subcommand)
    Filter repositories by a specific topic tag.

--state <string> (issues, prs subcommands)
    Filter issues or pull requests by state: {open|closed}.

--label <string> (issues, prs subcommands)
    Filter issues or pull requests by specific labels (e.g., `"bug"`, `"enhancement"`).

--author <string> (issues, prs, users subcommands)
    Filter by the author's username.

The gh search command is an integral part of the GitHub CLI, enabling users to perform comprehensive searches across various GitHub entities directly from the command line. It provides subcommands to specifically search for repositories, issues, pull requests (PRs), code, and users. Users can construct sophisticated queries using GitHub's powerful search syntax, apply numerous filters based on criteria like language, stars, labels, author, and more. The command supports different output formats, including plain text and JSON, and allows for advanced filtering and formatting of results using `jq` expressions or Go templates. This makes it an indispensable tool for developers needing to discover projects, track issues, find code snippets, or locate collaborators without leaving their terminal environment, streamlining workflows and enhancing productivity.

Using gh search requires the GitHub CLI (`gh`) to be installed and authenticated with your GitHub account. Searches are subject to GitHub API rate limits, which may affect the speed and volume of requests, especially when using `--paginate` for extensive results. Effective use often requires familiarity with GitHub's specific search syntax, which can be more powerful but also more complex than simple keyword searches.

The power of gh search is greatly enhanced by leveraging GitHub's advanced search syntax. Users can combine keywords with qualifiers (e.g., `language:go`, `stars:>50`, `is:open`, `user:octocat`) to refine queries. For a comprehensive guide, refer to the official GitHub documentation on Constructing a search query.

The gh search command is categorized into several subcommands, each tailored for a specific type of GitHub entity:

• codes: Search for code within repositories.
• issues: Search for issues across repositories.
• prs: Search for pull requests.
• repos: Search for repositories.
• users: Search for users and organizations.

The gh search command is a core component of the GitHub CLI (`gh`), which was officially released by GitHub in 2020. It rapidly became a fundamental feature, allowing developers to extend their command-line workflows directly to GitHub's extensive data, reducing the need to switch to a web browser for discovery and information retrieval tasks. Its development has focused on providing a flexible and powerful interface to GitHub's search capabilities, mirroring and often enhancing the web experience.

gh(1), grep(1), jq(1)