Find the Right GitHub CLI Extension Before Installing It

You will finish with a repeatable way to search GitHub CLI extensions, narrow the results by owner or licence, inspect machine-readable fields, and decide what to install without guessing from a repository name. The examples use GitHub CLI 2.87.3, installed here as package gh.

Allow about ten minutes. You need gh on your PATH and a network connection to GitHub. Searching is an ordinary user operation: it does not need sudo, does not install anything, and does not alter your local extensions. The search results are live repository data, so check the repository before trusting it.

1. Check the installed command

Confirm which executable and version will handle the search:

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

Your path and version may differ. Read the local command help when a newer release changes an option:

$ gh extension search --help

Checkpoint: the command is available, and the reported version is the one you are documenting or troubleshooting. The shorter gh ext search form is also accepted by the installed CLI and is used in the manual examples.

2. List popular extensions

With no query, the command prints the first 30 available extensions. The manual describes this list as sorted by star count. Run it without elevated privileges:

$ gh extension search

When the output goes to a terminal, each row has an installed marker, an OWNER/REPO name, and a description. The marker is a tick for an extension already installed locally. When output is redirected or piped, the tick is rendered as the word installed instead. Do not mistake a result in the list for an installed extension: verify local state separately.

$ gh ext list

A long result set can distract you before you have a question in mind. Start with a small limit while exploring, then increase it deliberately:

$ gh extension search --limit 10
$ gh extension search --limit 100

--limit, or -L, defaults to 30 and controls the maximum number fetched. A larger value can take longer and produces more candidates to review; it does not make the results more trustworthy.

3. Search for a capability

Put a plain search term after the command. For example, look for extensions related to pull request workflows:

$ gh extension search pull-request --limit 20

The output is repository-oriented rather than a package catalogue. Read each repository's description, recent activity and documentation before installing it. Check the owner, licence, intended permissions and installation instructions. Treat a similarly named repository as a candidate to investigate, not as proof that it is the official project.

For a narrower search by owner, use --owner:

$ gh extension search --owner github --limit 20

Filter by a licence string when that is part of your selection criteria:

$ gh extension search --license MIT --limit 20

These filters reduce the fetched result set. They do not audit a project's source, establish that its licence is suitable for your use, or replace your organisation's review process.

4. Make sorting explicit

The command supports forks, help-wanted-issues, stars and updated for --sort. Use --order asc or --order desc when the selected sort needs a direction:

$ gh extension search --sort updated --order asc --limit 20

The manual says that --order is ignored unless --sort is specified, and its default is descending. The help output reports best-match as the option default for --sort, while the no-argument description calls out a first-30 list sorted by stars. If the ordering matters to a script or review, pass both options explicitly rather than relying on a default.

Checkpoint: you can explain why a repository appeared and can reproduce the ordering with explicit flags. A star count is a popularity signal, not a security or maintenance guarantee.

5. Ask for stable fields

For a review note or a script, request JSON instead of parsing the human-readable columns. Limit the fields to what you need:

$ gh extension search pull-request --limit 5 \
    --json fullName,description,stargazersCount,updatedAt,url

Expect a JSON array. The field names available in this installed version include fullName, description, stargazersCount, updatedAt and url. The exact records will change as GitHub changes. Keep the JSON output intact when you need an auditable candidate list.

Use --jq to select or reshape that JSON with a jq expression. This example prints only repository names and URLs:

$ gh extension search pull-request --limit 5 \
    --json fullName,url \
    --jq '.[] | "\(.fullName) \(.url)"'

Do not pass untrusted text as a jq expression. If you need Go-template formatting instead, use --template; choose one output format and verify it against a small result set before putting it in automation.

6. Investigate a candidate before installation

Search does not install an extension. Before you change your workstation, open the repository or inspect it with the normal GitHub CLI repository commands:

$ gh repo view OWNER/REPO
$ gh repo view OWNER/REPO --web

Replace OWNER/REPO with the exact value from fullName. Confirm that the repository is the one you intended, read its installation instructions, review recent commits and releases, and check what the extension will execute with your GitHub credentials. Installation can run code or grant an extension access to repository data, so it is a security-sensitive change. Do not install a result merely because it has many stars.

If you only want to browse the search in a browser, -w or --web opens the query:

$ gh extension search pull-request --web

This opens a browser and does not install anything. In a headless shell, omit it and use JSON output instead.

7. Use repository search for finer queries

gh extension search deliberately exposes fewer search qualifiers than general repository search. If the extension search is too broad, use the topic suggested by the manual:

$ gh search repos --topic gh-extension --limit 20

Use gh help search repos to check the qualifiers supported by your installed release. The topic search is a discovery aid, not a guarantee that every result is a usable GitHub CLI extension. Confirm the repository's documentation and entry points before treating it as one.

Common failure checks

A network, authentication or API error is not an empty search result. Capture the command and exit status, then retry after checking connectivity and the normal gh authentication state:

$ gh extension search --limit 5
$ printf 'exit status: %s\n' "$?"
exit status: 0

A zero status means this invocation completed successfully. It does not validate any repository returned. If a query returns no useful candidates, change the search term or use gh search repos; do not immediately broaden the limit without understanding the results.

If the installed marker is missing from a non-interactive result, that is expected: the marker becomes the word installed when the command is not connected to a terminal. To list local extensions directly, use gh ext list. No recovery action is needed because searching changed no local state.