Search — Understanding GitHub CLI

The gh search command lets you search across all of GitHub from the terminal — repositories, code, issues, pull requests, and commits.

Searching Repositories

gh search repos "machine learning"
 
# Filter by language
gh search repos "web framework" --language python
 
# Filter by stars
gh search repos "cli tool" --stars ">1000"
 
# Filter by license
gh search repos "database" --license mit
 
# Filter by topic
gh search repos --topic kubernetes
 
# Sort by stars, forks, or updated time
gh search repos "react" --sort stars --order desc
 
# Limit results
gh search repos "go cli" --limit 20
 
# JSON output
gh search repos "go cli" --json fullName,description,stargazersCount

Searching Code

gh search code "fmt.Println"
 
# Restrict to a specific repo
gh search code "TODO" --repo cli/cli
 
# Restrict to a specific language
gh search code "async function" --language javascript
 
# Restrict to a filename
gh search code "API_KEY" --filename .env
 
# Restrict to a file extension
gh search code "import React" --extension tsx
 
# Restrict to a path
gh search code "func main" --path cmd/
 
# JSON output
gh search code "handleError" --json path,repository,textMatches

Searching Issues

gh search issues "bug login"
 
# Filter by state
gh search issues "memory leak" --state open
gh search issues "memory leak" --state closed
 
# Filter by repo
gh search issues "crash" --repo cli/cli
 
# Filter by label
gh search issues "feature" --label enhancement
 
# Filter by author or assignee
gh search issues --author octocat
gh search issues --assignee @me
 
# Sort by created, updated, or comments
gh search issues "performance" --sort comments --order desc
 
# JSON output
gh search issues "bug" --json number,title,repository,state

Searching Pull Requests

gh search prs "refactor"
 
# Filter by state
gh search prs "fix" --state merged
 
# Filter by repo
gh search prs "auth" --repo cli/cli
 
# Filter by review status
gh search prs --review approved
gh search prs --review required
gh search prs --review none
 
# Filter by draft status
gh search prs --draft=false
 
# JSON output
gh search prs "migration" --json number,title,state,repository

Searching Commits

gh search commits "fix typo"
 
# Filter by repo
gh search commits "bump version" --repo cli/cli
 
# Filter by author
gh search commits --author octocat
 
# Filter by date
gh search commits "release" --committer-date ">2024-01-01"
 
# Sort by author-date or committer-date
gh search commits "deploy" --sort committer-date
 
# JSON output
gh search commits "fix" --json sha,commit

Exclusion Syntax

GitHub search supports excluding results with a hyphen prefix. Because the shell interprets hyphens as flags, use -- to separate:

# Exclude issues with the "wontfix" label
gh search issues -- "crash -label:wontfix"
 
# Exclude a specific repo
gh search code -- "TODO -repo:my-org/internal"

On PowerShell, also use --% :

gh --% search issues -- "crash -label:wontfix"

Combining Filters

Filters can be combined freely:

gh search repos \
  --language rust \
  --stars ">500" \
  --license apache-2.0 \
  --topic cli \
  --sort stars \
  --limit 10

Exercises

Search for popular Go repositories: gh search repos "cli" --language go --sort stars
Find open issues mentioning "bug" in a repo: gh search issues "bug" --repo cli/cli --state open
Search code across GitHub: gh search code "func main" --language go --limit 5
Find merged PRs by a user: gh search prs --author octocat --state merged