Extend Commands Cookbook with PHPDoc edge-cases: aliases, repeating flags, sensitive args, global arg conflicts

[Copilot]

The Commands Cookbook lacked documentation for several PHPDoc features around argument definition edge-cases, leaving command authors to discover behavior through trial and error.

Added documentation

Repeating flags ([--status=<status>...])

When ellipsis syntax is used, passing the same flag multiple times collects values into an array ($assoc_args['status'] === ['active', 'inactive']). Without ..., repeated flags use last-wins. Boolean flags always use last-wins regardless.

Argument aliases ([--with-dependencies|w])

Pipe-separated aliases in the synopsis token map alternative names to the canonical key in $assoc_args. Works for flags, single-char short-forms, and value-carrying args:

 * [--with-dependencies|w]
 * [--verbose|v|wordy]
 * [--format=<format>|f]

Sensitive arguments (sensitive: true)

New YAML annotation in the parameter block. When --prompt is used, WP-CLI redacts the value in the echoed command line ([REDACTED]):

 * [--******
 * ---
 * sensitive: true
 * ---

@skipglobalargcheck docblock tag

WP-CLI now warns at registration time when a command argument name collides with a global argument (--debug, --user, --quiet, etc.). Add @skipglobalargcheck to the PHPdoc to suppress the warning intentionally.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Extends documentation about commands' phpdoc possibilities/limitations</issue_title>
<issue_description>- [x] Yes, I reviewed the contribution guidelines.

Describe your use case and the problem you are facing

Commands cookbook is lacking some edge-cases about commands' options and I didn't find my answer in any other place either.

Describe the solution you'd like

I'd like to find answers to the following topics regarding phpdoc definition of a command:

1. Handling short option. Why aren't they supported? Is there known workarounds?
2. Handling options expecting a comma-separated list of values (like in --foo=bar,baz). It's another common case and I failed to find any example. It's sad options couldn't be used and one can't know if some utils already exist within wp-cli to handle them.
3. Multiple occurrences of the same option (like in --regex=ab --regex=cd) is another case where documentation is lacking.
   </issue_description>

<agent_instructions>Document the new API additions to the Commands cookbook docs:

• Add support for argument aliases wp-cli#6176
  *Add support for multiple flag values via repeated flags using ellipsis syntax wp-cli#6198
• Mask sensitive argument values in --prompt output wp-cli#6145
• Warn when commands override global arguments wp-cli#6174</agent_instructions>

Comments on the Issue (you are @copilot in this section)

@swissspidy Short options will be supported by https://github.com/wp-cli/wp-cli/pull/6176 if we decide to add it.

2 and 3 are covered by wp-cli/wp-cli#6198

wp-cli/wp-cli#6145 is another good addition for the documentation

wp-cli/wp-cli#6174 too</comment_new>

• Fixes Extends documentation about commands' phpdoc possibilities/limitations #580

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[Copilot]

Pull request overview

This PR expands the WP-CLI Commands Cookbook documentation to cover additional PHPDoc/synopsis edge-cases and metadata that affect how command arguments are parsed and validated.

Changes:

• Documented repeating associative flags via ellipsis ([--status=<status>...]) and clarified last-wins behavior.
• Added documentation for synopsis argument aliases using | (including short forms).
• Added documentation for sensitive: true YAML parameter metadata and the @skipglobalargcheck docblock tag.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.