Describe the bug

"GitHub API preview names to request (without the "-preview" suffix)"

Means nothing to me.

I can't tell if this means that requests for certain apis will be sent without -preview. If that's the goal, then, the text should say "Send requests without -preview", but I don't think that's what's going on.

If it means "Include specific preview mime types in accepts request", then it should say something like that. My guess is that the goal is more like "GitHUB API preview names to include in request accept headers (names should omit -preview, but requests will include the suffix)."

Affected version

gh version 2.74.2 (2025-06-17)
https://github.com/cli/cli/releases/tag/v2.74.2

Steps to reproduce the behavior

1. Run gh api --help|grep -A1 preview
2. View the output:

   gh api --help|grep -A1 preview
     -p, --preview names         GitHub API preview names to request (without the "-preview" suffix)
     -f, --raw-field key=value   Add a string parameter in key=value format
   --
     # Opt into GitHub API previews
     $ gh api --preview baptiste,nebula ...
   

Expected vs actual behavior

A clear and concise explanation of what preview does

• Docs improvement for api --preview option #3433 asked for an improvement here
• Misc. docs improvements #5223 supposedly changed something, but it didn't improve things
• Note that while `names` is present in the code, the `s are lost in the help output:
  

  cli/pkg/cmd/api/api.go

  Line 279 in df5e6d9

  cmd.Flags().StringSliceVarP(&opts.Previews, "preview", "p", nil, "GitHub API preview `names` to request (without the \"-preview\" suffix)")