Hey @SRNissen, sorry it's taken so long to get round to this issue after the Christmas break. Some team changes and a large backlog. Thanks for opening this. The help text for run list is definitely pretty sparse. I've labelled this help wanted so our community can contribute. Cheers.

When you say:

including output in error cases.

It hints that you might have run into an unexpected error, was there something specific that you ran into?

God yes

Chronologically it goes like:

• A devops consultant at our company was making changes to the pipeline and that included a scripted call using gh to get the run number
• Trying to reproduce it on my machine before sending it into prod, I got an error.
• It was unclear to me if I was getting an error because the consultant had made a mistake, or if it was because my distro's gh was behind the official one.
• in particular: gh run list --json number printed Unknown JSON field: "number".

And that's when I took a look at the docs.

My thinking was along the lines of

my distro's gh is pretty far behind, if it does the field validation clientside and the "number" field is new, maybe that's why it doesn't work for me.

Seeing the docs had no info on this at all, I opened the issue.

(I solved the problem by building from source. With a new gh, the consultant's script ran just fine.)

Thanks for providing the extra context, it'll be useful to anyone that wants to open a PR.

@williammartin I just pushed a PR for this.

I also checked a few other list subcommands, and they also need a list of available JSON fields in their docs. If you were okay with the changes in my PR, I can replicate the same for other lists.

Thank you, it's great to see this happen.

@SRNissen In the next release, there'll be a JSON Fields section in the --help output which will list the available fields. Check out the latest captures in PR #8934.