CLI Feedback

What have you loved?

Love the ability to opt-in to api preview features!

What was confusing or gave you pause?

Docs for the api --preview flag is a little unclear. The extent of the manpage docs for --preview is:

-p, --preview=[]      Opt into GitHub API previews

And an example:

# opt into GitHub API previews
$ gh api --preview baptiste,nebula ...

My confusion is that listing of available preview features use foo-preview as the full name for the preview (including the -preview suffix). But the examples in the docs do not. It isn't clear if the -preview suffix is required, optional or disallowed.

After digging up the initial PR: #3077, (in particular the description):

Before:
gh api -H 'Accept: application/vnd.github.nebula-preview+json, application/vnd.github.baptiste-preview, application/vnd.github.squirrel-girl-preview'
Now:
gh api -p nebula,baptiste -p squirrel-girl

It starts to become clear that the baptiste,nebula examples in the manpage docs are not just placeholders but examples of actual preview features, and so presumably the -preview suffix may be omitted. But I'm still not entirely sure if it's optional or actually disallowed. If I do gh api --preview foo-preview will that end up using a preview header of application/vnd.github.foo-preview-preview+json? 🤷

Are there features you'd like to see added?

I would suggest clarifying the docs for the --preview option that the preview strings may (or must?) omit the -preview suffix.

I would even suggest including a link to the Preview Features listing right in the docs for that flag. It would be super handy to be able to jump straight there from the terminal. https://docs.github.com/en/rest/overview/api-previews

Followup

After some experimentation it seems the -preview suffix must be omitted. (My api calls using --preview ant-man-preview seemed to operate as if wasn't using the preview flag at all.) So a followup request would be to make the -preview suffix optional but still acceptable if provided. I expect it will be quite likely for people to copy the preview feature names directly from the list and paste them; without carefully trimming the suffix.