docs(search): add examples for multiple qualifiers by happysnaker · Pull Request #13756 · cli/cli

happysnaker · 2026-06-30T01:20:32Z

Summary

add gh search examples showing multiple search-syntax qualifiers as separate CLI arguments
cover issues, pull requests, repositories, code, and commits search help text

Why

Issue #13678 shows that passing a full multi-qualifier query as one shell argument can be misleading. The maintainers suggested improving the docs/examples, so this PR makes that usage explicit in the built-in help output.

Closes #13678

Signed-off-by: happysnaker <[email protected]>

github-actions · 2026-06-30T01:20:46Z

Thanks for your pull request! Unfortunately, it doesn't meet the requirements for review:

None of the referenced issues have the help wanted label

Please update your PR to address the above. This PR will be automatically closed in 4 days if these requirements are not met.

Full contribution requirements

Include a detailed description of what this PR does
Link to an issue with the help wanted label (use Fixes #123 or Closes #123)

happysnaker · 2026-06-30T01:25:57Z

Thanks! For context, this PR was opened in response to #13678 after @babakks noted that an external docs/example PR would be welcome.

If this change should go through the normal external-contribution path, would a maintainer be able to add the help wanted label to #13678 (or point me at the preferred issue)? Happy to adjust accordingly.

babakks

Thanks for the PR, @happysnaker! 🙏

Please apply the following comments and then ping me for another review.

babakks · 2026-06-30T11:24:41Z

 			$ gh search prs --repo=cli/cli --draft

+			# Search pull requests using multiple search syntax qualifiers as separate arguments
+			$ gh search prs review:required status:success base:main


Let's not use advanced qualifiers:

Suggested change

$ gh search prs review:required status:success base:main

$ gh search prs is:merged author:monalisa

babakks · 2026-06-30T11:28:10Z

 			$ gh search repos "vim plugin"

+			# Search repositories using multiple search syntax qualifiers as separate arguments
+			$ gh search repos topic:artificial-intelligence stars:>5000 pushed:>2026-06-01 archived:false


The stars:>5000 should be quoted (otherwise it'll be interpreted as a shell redirection), and the example can also be simplified:

Suggested change

$ gh search repos topic:artificial-intelligence stars:>5000 pushed:>2026-06-01 archived:false

$ gh search repos topic:github 'stars:>5000'

babakks · 2026-06-30T11:29:19Z

 			# Search code matching "error handling"
 			$ gh search code "error handling"

+			# Search code using multiple search syntax qualifiers as separate arguments


I'd rather reword this (and the other titles) to remark the "raw" qualifier usage (as there are already flags for some of them, like --author):

Suggested change

# Search code using multiple search syntax qualifiers as separate arguments

# Search code using raw search qualifiers as separate arguments

Please apply this to other cases.

happysnaker · 2026-06-30T12:54:08Z

Applied the requested changes:\n\n- simplified the PR search example to \n- quoted the repo search qualifier and simplified that example\n- reworded the example titles to consistently say "raw search qualifiers as separate arguments"\n\nPlease take another look when you have a moment. Thanks!

happysnaker · 2026-06-30T12:55:02Z

Applied the requested changes:

simplified the PR search example to is:merged author:monalisa
quoted the repo search stars:>5000 qualifier and simplified that example
reworded the example titles to consistently say "raw search qualifiers as separate arguments"

Please take another look when you have a moment. Thanks!

babakks

Thanks for the changes. Two titles still need to be fixed:

babakks · 2026-06-30T13:49:09Z

 			# Search commits matching phrase "bug fix"
 			$ gh search commits "bug fix"

+			# Search commits using multiple search syntax qualifiers as separate arguments


babakks · 2026-06-30T13:49:19Z

 			# Search issues matching phrase "broken feature"
 			$ gh search issues "broken feature"

+			# Search issues using multiple search syntax qualifiers as separate arguments


happysnaker · 2026-07-01T01:39:35Z

I believe all requested wording/title fixes are now applied.

The remaining blocker seems to be the external-contributor gate requiring a linked issue with the help wanted label. Since this PR follows @babakks's invitation in #13678, would a maintainer mind either adding help wanted there or pointing me at the preferred issue to link instead? Happy to retarget if needed.

babakks

LGTM

This MR contains the following updates: | Package | Update | Change | |---|---|---| | [cli/cli](https://github.com/cli/cli) | minor | `v2.94.0` → `v2.96.0` | MR created with the help of [el-capitano/tools/renovate-bot](https://gitlab.com/el-capitano/tools/renovate-bot). **Proposed changes to behavior should be submitted there as MRs.** --- ### Release Notes <details> <summary>cli/cli (cli/cli)</summary> ### [`v2.96.0`](https://github.com/cli/cli/releases/tag/v2.96.0): GitHub CLI 2.96.0 [Compare Source](cli/cli@v2.95.0...v2.96.0) #### Security A security vulnerability has been identified, and fixed, that could allow command execution on a user's computer when connecting to a malicious Codespace via `gh codespace jupyter`. Users of `gh codespace jupyter` are advised to update gh to version v2.96.0 as soon as possible. For more information see: <GHSA-8cg3-r6g9-fpg2> #### Download release assets without authentication `gh release download` now works against public repositories without authentication, matching `gh extension install`. A token is still used when one is present: ```shell # Download assets from a public repository, no login required gh release download v2.96.0 --repo cli/cli ``` #### What's Changed ##### ✨ Features - Allow `gh release download` without authentication on public repositories by [@BagToad](https://github.com/BagToad) in [#13723](cli/cli#13723) - Detect additional third-party coding agents by [@BagToad](https://github.com/BagToad) in [#13722](cli/cli#13722) - Support `antigravity-cli` and `antigravity2.0` in `gh skill` by [@BagToad](https://github.com/BagToad) in [#13784](cli/cli#13784) ##### 🐛 Fixes - fix: show checks summary when all checks were cancelled by [@s3onghyun](https://github.com/s3onghyun) in [#13679](cli/cli#13679) - fix(skills): install universal agent to `~/.agents/skills` by [@toller892](https://github.com/toller892) in [#13681](cli/cli#13681) - fix(skills): honor `--dir` without agent prompt by [@happysnaker](https://github.com/happysnaker) in [#13766](cli/cli#13766) - Fix concurrent map writes in codespace port forwarding by [@williammartin](https://github.com/williammartin) in [#13313](cli/cli#13313) - Use `int64` for GitHub database IDs by [@williammartin](https://github.com/williammartin) in [#13403](cli/cli#13403) ##### 📚 Docs & Chores - Pin reusable triage workflows to a commit SHA by [@BagToad](https://github.com/BagToad) in [#13705](cli/cli#13705) - Add security disclosure guidance to `AGENTS.md` by [@BagToad](https://github.com/BagToad) in [#13720](cli/cli#13720) - Clarify `--clone` boolean flag behaviour in `gh repo fork` help by [@BagToad](https://github.com/BagToad) in [#13786](cli/cli#13786) - Fix flaky `TestHuhPrompterMultiSelectWithSearchPersistence` on slow architectures by [@pdostal](https://github.com/pdostal) in [#13675](cli/cli#13675) - docs(search): add examples for multiple qualifiers by [@happysnaker](https://github.com/happysnaker) in [#13756](cli/cli#13756) - docs: fix broken anchor link in release-process-deep-dive by [@patrickwehbe](https://github.com/patrickwehbe) in [#13688](cli/cli#13688) - docs: fix broken install command and link/grammar errors by [@patrickwehbe](https://github.com/patrickwehbe) in [#13690](cli/cli#13690) - docs: fix duplicated word in primer README by [@s3onghyun](https://github.com/s3onghyun) in [#13677](cli/cli#13677) #####

Dependencies - chore(deps): bump github.com/microsoft/dev-tunnels from 0.1.19 to 0.1.27 by [@dependabot](https://github.com/dependabot) in [#13708](cli/cli#13708) - chore(deps): bump actions/checkout from 6.0.3 to 7.0.0 by [@dependabot](https://github.com/dependabot) in [#13703](cli/cli#13703) - chore(deps): bump github.com/google/go-containerregistry from 0.21.6 to 0.21.7 by [@dependabot](https://github.com/dependabot) in [#13702](cli/cli#13702) - chore(deps): bump actions/setup-go from 6.4.0 to 6.5.0 by [@dependabot](https://github.com/dependabot) in [#13740](cli/cli#13740) - chore(deps): bump actions/attest from 4.1.0 to 4.1.1 by [@dependabot](https://github.com/dependabot) in [#13754](cli/cli#13754) - chore(deps): bump goreleaser/goreleaser-action from 7.2.2 to 7.2.3 by [@dependabot](https://github.com/dependabot) in [#13759](cli/cli#13759) - chore(deps): bump golangci/golangci-lint-action from 9.2.1 to 9.3.0 by [@dependabot](https://github.com/dependabot) in [#13779](cli/cli#13779) #### New Contributors - [@patrickwehbe](https://github.com/patrickwehbe) made their first contribution in [#13688](cli/cli#13688) - [@s3onghyun](https://github.com/s3onghyun) made their first contribution in [#13679](cli/cli#13679) - [@toller892](https://github.com/toller892) made their first contribution in [#13681](cli/cli#13681) - [@happysnaker](https://github.com/happysnaker) made their first contribution in [#13756](cli/cli#13756) **Full Changelog**: <cli/cli@v2.95.0...v2.96.0> ### [`v2.95.0`](https://github.com/cli/cli/releases/tag/v2.95.0): GitHub CLI 2.95.0 [Compare Source](cli/cli@v2.94.0...v2.95.0) #### Read repository files and directories with `gh repo read-file` and `gh repo read-dir` Two new preview commands read repository contents without cloning: ```shell # Read a single file to stdout gh repo read-file README.md --repo cli/cli # Read from a specific branch, tag, or commit gh repo read-file go.mod --ref v2.94.0 --repo cli/cli # Write a file to disk (use --clobber to overwrite) gh repo read-file README.md --output ./README.md --repo cli/cli # List the entries in a directory gh repo read-dir script --repo cli/cli ``` Both commands default to the repository's default branch, accept `--ref` to target any branch, tag, or commit, and support `--json`, `--jq`, and `--template` for scripting. This makes it easy for agents and automation to inspect a repo without a full checkout. > \[!NOTE] > `gh repo read-file` and `gh repo read-dir` are in preview and subject to change without notice. #### What's Changed ##### ✨ Features - feat: add `repo read-file` and `repo read-dir` by [@babakks](https://github.com/babakks) in [#13580](cli/cli#13580) - feat(skills): list available skills when install runs non-interactively by [@SamMorrowDrums](https://github.com/SamMorrowDrums) in [#13548](cli/cli#13548) - Support custom CLAUDE\_CONFIG\_DIR in install by [@tommaso-moro](https://github.com/tommaso-moro) in [#13523](cli/cli#13523) ##### 🐛 Fixes - fix(skills): stage updates in a temp dir and swap in-place by [@SamMorrowDrums](https://github.com/SamMorrowDrums) in [#13449](cli/cli#13449) ##### 📚 Docs & Chores - Make filtering by bot authors more discoverable by [@BagToad](https://github.com/BagToad) in [#13642](cli/cli#13642) - docs(discussion): polish help docs by [@babakks](https://github.com/babakks) in [#13632](cli/cli#13632) - Bump Go in devcontainer by [@spenserblack](https://github.com/spenserblack) in [#13674](cli/cli#13674) #####

Dependencies - chore(deps): bump golang.org/x/text from 0.37.0 to 0.38.0 by [@dependabot](https://github.com/dependabot)\[bot] in [#13640](cli/cli#13640) - chore(deps): bump charm.land/lipgloss/v2 from 2.0.3 to 2.0.4 by [@dependabot](https://github.com/dependabot)\[bot] in [#13663](cli/cli#13663) - chore(deps): bump golang.org/x/term from 0.43.0 to 0.44.0 by [@dependabot](https://github.com/dependabot)\[bot] in [#13661](cli/cli#13661) - chore(deps): bump github/codeql-action from 4.36.1 to 4.36.2 by [@dependabot](https://github.com/dependabot)\[bot] in [#13619](cli/cli#13619) - chore(deps): bump github.com/sigstore/sigstore-go from 1.1.4 to 1.2.1 by [@dependabot](https://github.com/dependabot)\[bot] in [#13662](cli/cli#13662) - chore(deps): bump golang.org/x/crypto from 0.52.0 to 0.53.0 by [@dependabot](https://github.com/dependabot)\[bot] in [#13641](cli/cli#13641) **Full Changelog**: <cli/cli@v2.94.0...v2.95.0> </details> --- ### Configuration 📅 **Schedule**: (UTC) - Branch creation - At any time (no schedule defined) - Automerge - At any time (no schedule defined) 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻ **Rebasing**: Whenever MR becomes conflicted, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this MR and you won't be reminded about this update again. --- - [ ] If you want to rebase/retry this MR, check this box --- This MR has been generated by [Mend Renovate](https://github.com/renovatebot/renovate).

docs(search): add examples for multiple qualifiers

8a6b76d

Signed-off-by: happysnaker <[email protected]>

happysnaker requested a review from a team as a code owner June 30, 2026 01:20

happysnaker requested a review from babakks June 30, 2026 01:20

github-actions Bot added external pull request originating outside of the CLI core team needs-triage needs to be reviewed unmet-requirements and removed needs-triage needs to be reviewed labels Jun 30, 2026

happysnaker mentioned this pull request Jun 30, 2026

gh search quotes a single-argument query with multiple qualifiers as one qualifier value #13678

Closed

babakks added the ready-for-review label Jun 30, 2026

babakks requested changes Jun 30, 2026

View reviewed changes

babakks removed the unmet-requirements label Jun 30, 2026

docs(search): simplify raw qualifier examples

6ee1a91

babakks requested changes Jun 30, 2026

View reviewed changes

docs(search): reword raw qualifier examples

0afaf6f

babakks approved these changes Jul 1, 2026

View reviewed changes

babakks merged commit ff4e4a2 into cli:trunk Jul 1, 2026
11 checks passed

BrewTestBot mentioned this pull request Jul 2, 2026

gh 2.96.0 Homebrew/homebrew-core#291107

Merged

	$ gh search prs review:required status:success base:main
	$ gh search prs is:merged author:monalisa

	$ gh search repos topic:artificial-intelligence stars:>5000 pushed:>2026-06-01 archived:false
	$ gh search repos topic:github 'stars:>5000'

	# Search code using multiple search syntax qualifiers as separate arguments
	# Search code using raw search qualifiers as separate arguments

Uh oh!

Conversation

happysnaker commented Jun 30, 2026

Summary

Why

Uh oh!

github-actions Bot commented Jun 30, 2026

Uh oh!

happysnaker commented Jun 30, 2026

Uh oh!

babakks left a comment

Choose a reason for hiding this comment

Uh oh!

babakks Jun 30, 2026

Choose a reason for hiding this comment

Uh oh!

babakks Jun 30, 2026

Choose a reason for hiding this comment

Uh oh!

babakks Jun 30, 2026

Choose a reason for hiding this comment

Uh oh!

happysnaker commented Jun 30, 2026

Uh oh!

happysnaker commented Jun 30, 2026

Uh oh!

babakks left a comment

Choose a reason for hiding this comment

Uh oh!

babakks Jun 30, 2026

Choose a reason for hiding this comment

Uh oh!

babakks Jun 30, 2026

Choose a reason for hiding this comment

Uh oh!

happysnaker commented Jul 1, 2026

Uh oh!

babakks left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants