Feature request: allow selecting fields for human-readable list output #14413

What would you like to be added?

Add a --fields option to list commands such as gh pr list to allow users to select which fields are displayed in the human-readable table.

For example:

gh pr list --fields number,title,author,state

could produce:

NUMBER  TITLE                    AUTHOR   STATE
123     Fix authentication      alice    OPEN
124     Update dependencies     bob      MERGED
125     Improve documentation   carol    OPEN

The order of the fields would determine the order of the columns.

Motivation

Today, gh pr list provides a predefined human-readable table, while --json provides field selection for structured output.

If a user wants a slightly different human-readable table, they currently need to move to --json and then use --jq or --template to construct the output.

For example, selecting a few fields is straightforward:

gh pr list --json number,title,author,state

but turning those fields back into a table requires additional formatting:

gh pr list \
  --json number,title,author,state \
  --template '{{range .}}{{tablerow .number .title .author.login .state}}{{end}}'

There seems to be a useful middle ground between the fixed default table and fully programmable output:

gh pr list --fields number,title,author,state

The intention is to make common table customization simple without introducing another query or formatting language.

Proposed behavior

--fields would select fields that have a defined, human-readable representation suitable for a single table cell.

Scalar fields would be supported directly, for example:

number
title
state
isDraft
createdAt
updatedAt
closedAt
mergedAt
additions
deletions
changedFiles

Some non-scalar fields also have an obvious single-value representation and could potentially be supported. For example:

author           → author.login
mergedBy         → mergedBy.login
milestone        → milestone.title
headRepository   → headRepository.nameWithOwner
mergeCommit      → mergeCommit.oid

The exact set of supported fields and their representations would be part of the design.

Fields representing collections such as labels, assignees, comments, commits, files, reviews, etc. could initially be excluded rather than introducing arbitrary serialization rules.

For structured or custom transformations, users would continue to use --json, --jq, or --template.

Why not make this a general JSON/field-path selector?

The goal would intentionally be to keep --fields simple.

For example, this proposal is not intended to introduce expressions such as:

gh pr list --fields 'labels[].name'

or arbitrary JSON traversal/transformation.

That functionality is already better served by --json together with --jq or --template.

Instead, --fields would expose a curated set of fields that gh knows how to render naturally in a table.

Open questions

I'd be interested in maintainer/community feedback on:

1. Is there a specific reason this functionality does not currently exist?
2. Is --fields a suitable name, or would another name be preferable?
3. Should the option be limited to scalar fields?
4. Which non-scalar fields have sufficiently obvious representations to include?
5. Should fields such as author, milestone, and headRepository have predefined representations as proposed above?
6. Should collection fields such as labels and assignees be excluded, or should they have a simple representation such as comma-separated values?
7. Should this functionality be available consistently across other list commands (gh issue list, gh run list, etc.), or should it initially be specific to gh pr list?
8. Should the set of --fields values exactly match the fields available to --json, or should the two have separate field sets?
9. Is there an existing internal abstraction for field selection/rendering that this could build on?

Alternatives

The existing --json, --jq, and --template options can accomplish this today, so this proposal is primarily about making the common case more discoverable and concise.

The proposed feature would not replace those options; it would provide a simpler interface for selecting predefined human-readable fields.

Example

Instead of:

gh pr list \
  --json number,title,author,state \
  --template '{{range .}}{{tablerow .number .title .author.login .state}}{{end}}'

allow:

gh pr list --fields number,title,author,state

while retaining the existing structured-output options for users who need more control.