Standardise on a means of exposing allowed field values

[johnbillion]

Many commands in WP-CLI accept the [--<field>=<value>] [--field=<field>] [--fields=<fields>] group of flags (or a variation thereof, including --by), for example wp post list, wp term get, and wp taxonomy list.

When using the help docs for these commands:

• Some commands show the full list of available fields as separate parameters, for example wp post update and wp post create.
• Some list the default and optional fields in an "Available Fields" section of the command docblock, for example wp site list.
• Some commands only list the default returned fields, for example wp post-type list.
• Some also link to relevant developer documentation on the available fields, for example wp user list.
• Some commands refer to a WordPress function that includes documentation on the available fields, for example wp comment create.

It would be great to standardise on a means of exposing:

• Which field names are available for the --<field> flags.
• Which values are available for the --field and --fields flags.
• Which values are available for the --by flag.

In addition, it would be great to decide on whether the full list of available fields should be shown as separate parameters, as is the case currently with wp post update and wp post create, or whether they should switch to using the --<field> syntax.

However, what we don't want to introduce is a burden on WP-CLI to ensure that the available field names are up to date with WordPress core. The best form of documentation would be to list every available field, but that would introduce a potential maintenance overhead with each new release of WordPress. It may be preferable to link to the relevant developer.wordpress.org reference for the corresponding function in WordPress which documents the available parameters.

Thoughts welcome.

[swissspidy]

Related:

• wp user update silently ignores typo'ed --user_pass flag wp-cli#5286
• Validate Parameter Names in wp user update Command entity-command#528