Improve `api` `--preview` docs #11274

jsoref · 2025-07-11T13:34:08Z

Fixes api --preview docs are still very unhelpful #11239
Implementation per api --preview docs are still very unhelpful #11239 (comment)

github-actions · 2025-07-11T13:34:22Z

Thank you for your pull request! 🎉

This PR appears to fix the following issues that are not labeled with help wanted:

api --preview docs are still very unhelpful #11239

As outlined in our Contributing Guidelines, we expect that PRs are only created for issues that have been labeled help wanted.

While we appreciate your initiative, please note that:

PRs for non-help wanted issues may not be reviewed immediately as they might not align with our current priorities
The issue might already be assigned to a team member or planned for a specific release
We may need to close this PR. For example, if it conflicts with ongoing work or architectural decisions

What happens next:

Our team will review this PR and the associated issues
We may add the help wanted label to the issues, if appropriate, and review this pull request
In some cases, we may need to close the PR. For example, if it doesn't fit our current roadmap

Thank you for your understanding and contribution to the project! 🙏

This comment was automatically generated by cliAutomation.

williammartin

Thanks for helping us improve the docs. Couple of thoughts.

williammartin · 2025-07-11T13:47:00Z

pkg/cmd/api/api.go

@@ -276,7 +279,7 @@ func NewCmdApi(f *cmdutil.Factory, runF func(*ApiOptions) error) *cobra.Command
 	cmd.Flags().StringArrayVarP(&opts.MagicFields, "field", "F", nil, "Add a typed parameter in `key=value` format")
 	cmd.Flags().StringArrayVarP(&opts.RawFields, "raw-field", "f", nil, "Add a string parameter in `key=value` format")
 	cmd.Flags().StringArrayVarP(&opts.RequestHeaders, "header", "H", nil, "Add a HTTP request header in `key:value` format")
-	cmd.Flags().StringSliceVarP(&opts.Previews, "preview", "p", nil, "GitHub API preview `names` to request (without the \"-preview\" suffix)")
+	cmd.Flags().StringSliceVarP(&opts.Previews, "preview", "p", nil, "Opt into GitHub API previews (names should exclude '-preview' and be comma separated)")


Like other slices, this can also be provided like so:

gh api --verbose --preview foo --preview bar

I'm not sure it's necessary to mention the accepted format here when we don't do it for any other flag.

I didn't ask for it, but I was surprised to learn it was a thing, without this hint I wouldn't have known.

I'm not attached to that part of the change.

I agree with your suggested change to the start. I was just copy+pasting the suggestion.

Knowing to exclude -preview seems fairly important -- although it could be included in prose instead of here...

@williammartin that was meant to address one of the example usages where the previews are comma-separated. I don't think it's a big deal, though.

williammartin · 2025-07-11T13:53:23Z

pkg/cmd/api/api.go

@@ -85,6 +85,9 @@ func NewCmdApi(f *cmdutil.Factory, runF func(*ApiOptions) error) *cobra.Command
 			any value that contains %[1]s{...}%[1]s in quotes to prevent the shell from
 			applying special meaning to curly braces.

+			This command supports invoking preview-stage API endpoints/features, when


Suggested change

This command supports invoking preview-stage API endpoints/features, when

This command supports opting into previews, which are feature-flagged, experimental API endpoints or behaviors. The API expects opt-in via the %[1]sAccept%[1]s header with format %[1]sapplication/vnd.github.<preview-name>-preview+json%[1]s and this command facilitates that via %[1]s--preview <preview-name>%[1]s.

What do you think of something like this? Happy for you to adjust a little, just trying to provide a little more detail to the purpose and use of this thing, since the api command is such a thin wrapper over the real request/responses.

I wrote a longer response on my laptop but ran out of time.

I asked for the details of --preview to be added in my issue but the staff person pushed back against it.

So I'm definitely happy to accept this proposal as it aligns with my original request.

If you're still ok with it, I'll pull it in when I get back to a computer.

I think it's hard to explain the intention of --preview without a bit of the underlying details, and I think with the intention of gh api being a thin layer over the raw requests it's not too much. If there were a GitHub docs link that explained this I would just link to that but like you, I couldn't find one that wasn't just like: "yeah here's some previews that graduated" with no real explanation. I think these are rarely used, and perhaps have become less used since the api command was first introduced.

Right. If I had a doc like that, I'd be half tempted to include it in the documentation...

Anyway, I'll fold in these suggestions and push. I'm quite happy with this as it aligns with my initial request.

If you guys think it's best to include the underlying detail, I'm sure down for it.

Signed-off-by: Josh Soref <[email protected]>

jsoref · 2025-07-23T01:47:07Z

@williammartin , @babakks : don't mean to pry, but I'm reviewing my work from 2 weeks ago and this seems to be stuck, is it waiting for something from me?

williammartin · 2025-07-23T08:42:07Z

Sorry, I just hadn't noticed you'd pushed. Thanks for the nudge and for improving things. Cheers.

This MR contains the following updates: | Package | Update | Change | |---|---|---| | [cli/cli](https://github.com/cli/cli) | minor | `v2.74.2` -> `v2.76.1` | 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.76.1`](https://github.com/cli/cli/releases/tag/v2.76.1): GitHub CLI 2.76.1 [Compare Source](cli/cli@v2.76.0...v2.76.1) #### `gh pr create` regression fix This release fixes a regression introduced in `v2.76.0` where organization teams were retrieved outside of intentional use cases. This caused problems for GitHub Enterprise Server users using the GitHub Actions automatic token that does not have access to organization teams. For more information, see cli/cli#11360 #### What's Changed ##### 🐛 Fixes - Fix: `gh pr create`, only fetch teams when reviewers contain a team by [@BagToad](https://github.com/BagToad) in cli/cli#11361 ##### 📚 Docs & Chores - add tenancy aware for san matcher by [@ejahnGithub](https://github.com/ejahnGithub) in cli/cli#11261 - Run Lint and Tests on `push` to `trunk` branch by [@andyfeller](https://github.com/andyfeller) in cli/cli#11325 - update ownership of pkg/cmd/release/shared/ by [@ejahnGithub](https://github.com/ejahnGithub) in cli/cli#11326 - Automate spam issue detection by [@babakks](https://github.com/babakks) in cli/cli#11316 - Improve `api` `--preview` docs by [@jsoref](https://github.com/jsoref) in cli/cli#11274 - Incorporate govulncheck into workflows by [@andyfeller](https://github.com/andyfeller) in cli/cli#11332 - chore(deps): bump advanced-security/filter-sarif from 1.0.0 to 1.0.1 by [@dependabot](https://github.com/dependabot)\[bot] in cli/cli#11298 - chore(deps): bump github.com/sigstore/sigstore-go from 1.0.0 to 1.1.0 by [@dependabot](https://github.com/dependabot)\[bot] in cli/cli#11307 **Full Changelog**: cli/cli@v2.76.0...v2.76.1 ### [`v2.76.0`](https://github.com/cli/cli/releases/tag/v2.76.0): GitHub CLI 2.76.0 [Compare Source](cli/cli@v2.75.1...v2.76.0) ####

Copilot Coding Agent Support GitHub Copilot Pro+ and Copilot Enterprise subscribers can now assign issues to GitHub Copilot during issue creation using: - Command-line flag: `gh issue create --assignee @copilot` - Launching web browser: `gh issue create --assignee @copilot --web` - Or interactively selecting `Copilot (AI)` as assignee in `gh issue create` metadata For more details, refer to [the full changelog post for Copilot coding agent](https://github.blog/changelog/2025-05-19-github-copilot-coding-agent-in-public-preview/). #### What's Changed ##### ✨ Features - Assign Copilot during `gh issue create` by [@andyfeller](https://github.com/andyfeller) in cli/cli#11279 - Display immutable field in `release view` command by [@bdehamer](https://github.com/bdehamer) in cli/cli#11251 ##### 🐛 Fixes - FIX: Do not fetch logs for skipped jobs by [@babakks](https://github.com/babakks) in cli/cli#11312 - Transform `extension` and `filename` qualifiers into `path` qualifier for web code search by [@samcoe](https://github.com/samcoe) in cli/cli#11211 ##### 📚 Docs & Chores - FIX: Workflow does not contain permissions by [@BagToad](https://github.com/BagToad) in cli/cli#11322 - Add automated feature request response workflow by [@BagToad](https://github.com/BagToad) in cli/cli#11299 **Full Changelog**: cli/cli@v2.75.1...v2.76.0 ### [`v2.75.1`](https://github.com/cli/cli/releases/tag/v2.75.1): GitHub CLI 2.75.1 [Compare Source](cli/cli@v2.75.0...v2.75.1) #### What's Changed ##### 🐛 Fixes - Ensure hostnames are visible in CLI website by [@andyfeller](https://github.com/andyfeller) in cli/cli#11295 - Revert "Fix: `gh pr create` prioritize `--title` and `--body` over `--fill` when `--web` is present" by [@andyfeller](https://github.com/andyfeller) in cli/cli#11300 ##### 📚 Docs & Chores - Ensure go directive is always .0 version in bump by [@williammartin](https://github.com/williammartin) in cli/cli#11259 - Minor (1-word) documentation typo in generated `~/.config/gh/config.yml` by [@kurahaupo](https://github.com/kurahaupo) in cli/cli#11246 - Automate closing of stale issues by [@babakks](https://github.com/babakks) in cli/cli#11268 - Filter the `third-party/` folder out of CodeQL results by [@BagToad](https://github.com/BagToad) in cli/cli#11278 - Exclude `third-party` source from golangci-lint by [@andyfeller](https://github.com/andyfeller) in cli/cli#11293 #####

Dependencies - Bump Go to 1.24.5 by [@github-actions](https://github.com/github-actions)\[bot] in cli/cli#11255 - chore(deps): bump github.com/sigstore/protobuf-specs from 0.4.3 to 0.5.0 by [@dependabot](https://github.com/dependabot)\[bot] in cli/cli#11263 - chore(deps): bump golang.org/x/term from 0.32.0 to 0.33.0 by [@dependabot](https://github.com/dependabot)\[bot] in cli/cli#11266 - chore(deps): bump golang.org/x/sync from 0.15.0 to 0.16.0 by [@dependabot](https://github.com/dependabot)\[bot] in cli/cli#11264 - chore(deps): bump golang.org/x/text from 0.26.0 to 0.27.0 by [@dependabot](https://github.com/dependabot)\[bot] in cli/cli#11265 - chore(deps): bump golang.org/x/crypto from 0.39.0 to 0.40.0 by [@dependabot](https://github.com/dependabot)\[bot] in cli/cli#11275 #### New Contributors - [@kurahaupo](https://github.com/kurahaupo) made their first contribution in cli/cli#11246 - [@github-actions](https://github.com/github-actions)\[bot] made their first contribution in cli/cli#11255 **Full Changelog**: cli/cli@v2.75.0...v2.75.1 ### [`v2.75.0`](https://github.com/cli/cli/releases/tag/v2.75.0): GitHub CLI 2.75.0 [Compare Source](cli/cli@v2.74.2...v2.75.0) #### What's Changed ##### ✨ Features - init release verify subcommands by [@ejahnGithub](https://github.com/ejahnGithub) in cli/cli#11018 - Embed Windows resources (VERSIONINFO) during build by [@babakks](https://github.com/babakks) in cli/cli#11048 - Support `--no-repos-selected` on `gh secret set` by [@williammartin](https://github.com/williammartin) in cli/cli#11217 ##### 🐛 Fixes - Fix: `gh pr create` prioritize `--title` and `--body` over `--fill` when `--web` is present by [@dankrzeminski32](https://github.com/dankrzeminski32) in cli/cli#10547 - fix: get token for active user instead of blank if possible by [@anuraaga](https://github.com/anuraaga) in cli/cli#11038 - Use Actions API to retrieve job run logs as a fallback mechanism by [@babakks](https://github.com/babakks) in cli/cli#11172 - Fix query object state mutation during pagination by [@babakks](https://github.com/babakks) in cli/cli#11244 - Handle `HTTP 404` when deleting remote branch in `pr merge` by [@babakks](https://github.com/babakks) in cli/cli#11234 ##### 📚 Docs & Chores - chore: fix function name by [@jinjingroad](https://github.com/jinjingroad) in cli/cli#11149 - chore: update Go version to 1.24 in devcontainer configuration and docs by [@tMinamiii](https://github.com/tMinamiii) in cli/cli#11158 - Ensure lint workflow checks whether 3rd party license and code is up to date by [@andyfeller](https://github.com/andyfeller) in cli/cli#11047 - docs: install\_linux.md: add Solus linux install instructions by [@chax](https://github.com/chax) in cli/cli#10823 - Fix missing newline in install\_linux.md by [@BagToad](https://github.com/BagToad) in cli/cli#11160 - Ensure automation uses pinned go-licenses version by [@andyfeller](https://github.com/andyfeller) in cli/cli#11161 - Add `workflow_dispatch` support to MR Help Wanted check by [@BagToad](https://github.com/BagToad) in cli/cli#11179 - Remove unused `GH_TOKEN` env variable from workflow by [@BagToad](https://github.com/BagToad) in cli/cli#11190 - Add workflow to automate go version bumping by [@williammartin](https://github.com/williammartin) in cli/cli#11189 - Fix inconsistent use of tabs and spaces by [@Stefan-Heimersheim](https://github.com/Stefan-Heimersheim) in cli/cli#11194 - Decouple arg parsing from MR finder by [@babakks](https://github.com/babakks) in cli/cli#11192 - docs: consistently use `apt` in installation instructions by [@tklauser](https://github.com/tklauser) in cli/cli#11216 - Ensure bump go script has git user configured by [@williammartin](https://github.com/williammartin) in cli/cli#11229 - Inject token into bump-go workflow by [@williammartin](https://github.com/williammartin) in cli/cli#11233 - Reinstating Primer Style CLI content within `cli/cli` repository by [@andyfeller](https://github.com/andyfeller) in cli/cli#11060 - Add setup-go to bump-go workflow by [@williammartin](https://github.com/williammartin) in cli/cli#11237 - Ensure GoReleaser does not break on Mac OS and Linux when skipping Windows `.rsyso` generation script by [@andyfeller](https://github.com/andyfeller) in cli/cli#11257 #####

Dependencies - Bump all dependencies except dev-tunnels by [@williammartin](https://github.com/williammartin) in cli/cli#11203 - Update microsoft dev-tunnels to v0.1.13 by [@williammartin](https://github.com/williammartin) in cli/cli#11205 - Consume dependabot minor versions for go modules by [@williammartin](https://github.com/williammartin) in cli/cli#11213 #### New Contributors - [@jinjingroad](https://github.com/jinjingroad) made their first contribution in cli/cli#11149 - [@tMinamiii](https://github.com/tMinamiii) made their first contribution in cli/cli#11158 - [@chax](https://github.com/chax) made their first contribution in cli/cli#10823 - [@dankrzeminski32](https://github.com/dankrzeminski32) made their first contribution in cli/cli#10547 - [@anuraaga](https://github.com/anuraaga) made their first contribution in cli/cli#11038 - [@Stefan-Heimersheim](https://github.com/Stefan-Heimersheim) made their first contribution in cli/cli#11194 **Full Changelog**: cli/cli@v2.74.2...v2.75.0 </details> --- ### Configuration 📅 **Schedule**: 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 [Renovate Bot](https://github.com/renovatebot/renovate).

jsoref requested a review from a team as a code owner July 11, 2025 13:34

jsoref requested a review from williammartin July 11, 2025 13:34

jsoref temporarily deployed to cli-automation July 11, 2025 13:34 — with GitHub Actions Inactive

cliAutomation added the external pull request originating outside of the CLI core team label Jul 11, 2025

williammartin reviewed Jul 11, 2025

View reviewed changes

Improve api --preview docs

4687f33

Signed-off-by: Josh Soref <[email protected]>

jsoref force-pushed the issue-11239 branch from d9173e3 to 4687f33 Compare July 11, 2025 16:35

williammartin approved these changes Jul 23, 2025

View reviewed changes

williammartin merged commit 43e7609 into cli:trunk Jul 23, 2025
10 checks passed

jsoref deleted the issue-11239 branch July 23, 2025 11:59

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Improve `api` `--preview` docs #11274

Improve `api` `--preview` docs #11274

Uh oh!

jsoref commented Jul 11, 2025

Uh oh!

github-actions bot commented Jul 11, 2025

Uh oh!

williammartin left a comment

Uh oh!

williammartin Jul 11, 2025

Uh oh!

jsoref Jul 11, 2025

Uh oh!

jsoref Jul 11, 2025

Uh oh!

babakks Jul 11, 2025

Uh oh!

williammartin Jul 11, 2025

Uh oh!

jsoref Jul 11, 2025

Uh oh!

williammartin Jul 11, 2025

Uh oh!

jsoref Jul 11, 2025

Uh oh!

babakks Jul 11, 2025

Uh oh!

jsoref commented Jul 23, 2025

Uh oh!

williammartin commented Jul 23, 2025

Uh oh!

Uh oh!

Uh oh!

	This command supports invoking preview-stage API endpoints/features, when
	This command supports opting into previews, which are feature-flagged, experimental API endpoints or behaviors. The API expects opt-in via the %[1]sAccept%[1]s header with format %[1]sapplication/vnd.github.<preview-name>-preview+json%[1]s and this command facilitates that via %[1]s--preview <preview-name>%[1]s.

Improve api --preview docs #11274

Improve api --preview docs #11274

Uh oh!

Conversation

jsoref commented Jul 11, 2025

Uh oh!

github-actions bot commented Jul 11, 2025

Uh oh!

williammartin left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jsoref commented Jul 23, 2025

Uh oh!

williammartin commented Jul 23, 2025

Uh oh!

Uh oh!

Uh oh!

Improve `api` `--preview` docs #11274

Improve `api` `--preview` docs #11274