Add semantic & hybrid search to gh search issues via --search-type #14014

Describe the feature or problem you'd like to solve

Semantic search for Issues is GA and exposed via the REST search API's search_type parameter (lexical | semantic | hybrid; the GraphQL equivalent is the SearchType enum's ISSUE_SEMANTIC / ISSUE_HYBRID values), defaulting to lexical/keyword. Today gh never sends this parameter, so there is no native, discoverable way to run a semantic search from the CLI.

The only workaround is a raw API call, which is not ideal:

gh api -X GET /search/issues -f q="is:issue repo:cli/cli sticky sidebar" -f search_type=semantic

This proposal adds a first-class flag so users and agents can run relevance-ranked semantic (or hybrid) issue searches directly from gh search issues.

Proposed solution

Add a --search-type <lexical|semantic|hybrid> flag to gh search issues, defaulting to lexical so today's behavior is unchanged. When set to semantic or hybrid, the command sends the REST search_type query parameter.

Benefits:

• Discoverability: a documented flag with client-side validation instead of hand-rolled gh api calls.
• Better results for natural-language queries: semantic ranking surfaces relevant issues even when keywords don't match exactly (e.g. triage, duplicate detection, "have we seen this bug before?").
• Agent friendly: a stable, validated surface for AI agents doing issue triage/dedup, with clear errors rather than silent fallbacks.

Additional context

• search_type has nothing to do with the existing advanced issue search (advanced_search=true). That's a separate, richer query syntax; this change doesn't touch it.
• Semantic/hybrid uses a separate, smaller rate-limit bucket (10/min) distinct from the normal 30/min search bucket.
• The API silently ignores unknown search_type values and silently accepts sort/order under search_type=semantic (returns 200, echoes them). So any validation/rejection is a deliberate CLI-side UX choice.
• Semantic search is Dotcom-only (github.com / ghe.com); single-tenant GHES does not support it.

Proposed Design

Following the Primer CLI design reference, this adds a single flag to the existing gh search issues command rather than a new command surface.

Flag

--search-type string   Type of issue search to perform: {lexical|semantic|hybrid} (default "lexical")

• lexical (default): today's keyword search. No search_type param is sent, keeping the request byte-for-byte identical to current behavior.
• semantic: relevance-ranked semantic search. Sends search_type=semantic.
• hybrid: blends lexical + semantic ranking. Sends search_type=hybrid.

Scoping to issues only

Semantic/hybrid is scoped to issues, not PRs. Issue-only results come from keeping the type:issue qualifier the command already sends. Because --include-prs drops type:issue, it cannot be combined with --search-type semantic|hybrid; specifying both errors.

Interaction with --sort / --order

Semantic results are relevance-ranked, so --sort/--order are meaningless. Since the API silently accepts them, the CLI hard-errors on the combination with a clear message (a deliberate UX choice to avoid a confusing no-op). Open to reviewer preference on error vs. a non-fatal warning.

Interaction with --web

The web search UI cannot carry search_type, so --web is rejected when combined with semantic|hybrid rather than silently opening a lexical search.

Client-side enum validation

Because the API silently ignores unknown search_type values, the CLI validates the flag value itself and errors on anything outside {lexical|semantic|hybrid}.

GHES / host support (feature detection)

Semantic search is Dotcom-only. Support is feature-detected via the existing search feature-detection path (SearchType enum introspection for ISSUE_SEMANTIC / ISSUE_HYBRID), present on github.com and ghe.com, absent on single-tenant GHES. On an unsupported host the command fails with a clear "not supported on this host" message rather than sending an unsupported param.

Rate limiting / pagination

Semantic/hybrid draws from a separate, smaller rate-limit bucket (10/min). To avoid burning the whole budget in a single invocation, result fetching is bounded to a single page for semantic/hybrid rather than the default multi-page pagination. (--limit still applies, capped at one page.)

Note on query phrasing

Natural-language semantic queries should be entered unquoted. A quoted exact phrase (e.g. "auth fails on mobile") is treated as an exact-match lexical query by the backend, which falls back to lexical ranking even when search_type=semantic is sent. This is server-side behavior; the CLI always sends the requested search_type.

Summary of validation rules

Scope

This is scoped to gh search issues only, the direct REST analog (GET /search/issues), matching the open draft PR #14006.

Mockup

Semantic search

$ gh search issues auth fails on mobile --repo cli/cli --search-type semantic

Showing 3 of 3 issues

REPO     ID   TITLE                                             LABELS       UPDATED
cli/cli  #14  Mobile login flow returns 401 after SSO redirect  bug, auth    about 2 hours ago
cli/cli  #9   Token refresh fails on iOS Safari                 bug          about 1 day ago
cli/cli  #7   Session expired errors on phone browsers          needs-repro  about 3 days ago

Results are relevance-ranked (not date-sorted). Request sends search_type=semantic.

Hybrid search

$ gh search issues login broken --repo cli/cli --search-type hybrid
# request sends search_type=hybrid

Lexical unchanged (no flag)

$ gh search issues readme typo --repo cli/cli
# no search_type param sent — identical to today

JSON output

$ gh search issues auth fails on mobile --repo cli/cli --search-type semantic --json number,title -L 2
[
  {
    "number": 14,
    "title": "Mobile login flow returns 401 after SSO redirect"
  },
  {
    "number": 9,
    "title": "Token refresh fails on iOS Safari"
  }
]

Error cases

$ gh search issues foo --search-type bogus
X invalid argument "bogus" for "--search-type" flag: valid values are {lexical|semantic|hybrid}

$ gh search issues foo --search-type semantic --include-prs
X semantic search is scoped to issues and cannot be combined with `--include-prs`

$ gh search issues foo --search-type semantic --sort comments
X `--sort` and `--order` are not supported with semantic search

$ gh search issues foo --search-type semantic --web
X `--web` is not supported with semantic search

# On single-tenant GHES:
$ gh search issues foo --search-type semantic
X semantic search is not supported on this host: ghe.example.com