Document all accepted fields for the catch-all write commands

[swissspidy]

Opened to make the documentation side of wp-cli/wp-cli#5286 concrete. Pairs with wp-cli/wp-cli#6392, which adds the typo detection itself — but this PR stands on its own and is useful without it.

Why this first

Every approach discussed on #5286 needs the same foundation: an accurate list of what each command actually accepts. Typo detection matches an unknown argument against the documented ones, so an incomplete docblock means either missed typos or false positives. comment update documented no fields at all.

On its own this PR does not change validation. The catch-all still suppresses unknown-parameter checking, so the added parameters only improve wp help output today. They are what gives the matcher something accurate to work with.

Where the lists come from

The wp_insert_user(), wp_insert_post() and wp_update_comment() docblocks in core trunk, rather than the 2019 list on the issue — that one predates user_activation_key / spam (5.3) and meta_input (5.9).

Command	Added
user update	syntax_highlighting, comment_shortcuts, admin_color, use_ssl, user_activation_key, spam, show_admin_bar_front, locale, meta_input
post create	page_template, import_id
post update	page_template
comment create	full column set (15 fields; previously catch-all only)
comment update	full column set (15 fields; previously none)

Two changes that are not documentation

Flagged separately because they are easy to drop if you'd rather keep this PR pure.

1. user application-password update advertised --<field>=<value> while its own text said only name was supported. Core's WP_Application_Passwords::update_application_password() only ever reads $update['name'], so extra keys were silently ignored. Replaced the catch-all with [--name=<name>]. That command is now validated immediately, without depending on the framework PR.

2. --meta_input and --comment_meta take arrays, so they go through Utils\parse_shell_arrays() the way Post_Command::update() already does. Without it a JSON value reaches core as a string. Documenting them without this would have meant documenting parameters that don't work.

The second one originally tripped PHPStan, because parse_shell_arrays() was annotated array<string, string> while Comment_Command correctly declares array<string, mixed>. That turned out to be an upstream annotation bug and is fixed in wp-cli/wp-cli#6393, so all four call sites in this repo are now the same plain one-liner. No release is needed for that — composer.json sets minimum-stability: dev and requires ^3.0, which resolves to dev-main.

Verification

comment_author_IP and comment_post_ID are mixed-case, so they depend on #6388. Against the parser before that fix they register truncated:

!! TRUNCATED: --comment_author_ parsed from <comment_author_IP>

Against current main all seven commands parse cleanly, with no truncated names and no unknown tokens:

user update                         assoc=21  flags=1  generic=1
post create                         assoc=28  flags=2  generic=1
post update                         assoc=26  flags=1  generic=1
comment create                      assoc=15  flags=1  generic=1
comment update                      assoc=15  flags=0  generic=1
user application-password update    assoc=1   flags=0  generic=0

Two things I noticed but did not change

Both are pre-existing and orthogonal, and both now have tests and fixes in #637.

• post update --post_modified / --post_modified_gmt are documented but ignored. wp_insert_post() computes both itself and never reads them from $postarr.
• user create documents --user_nicename and --rich_editing but never applies them. User_Command::create() builds an explicit stdClass and neither property is set. That command has no catch-all, so it is strictly validated and still silently drops the value — the same failure as #5286, from the other direction.

🤖 Generated with Claude Code

https://claude.ai/code/session_014SSZzqMJRDTiLiDxQEPYcL

Summary by CodeRabbit

• Documentation

  • Expanded comment command documentation with supported fields for creating and updating comments.
  • Documented additional post options, including page templates and import IDs.
  • Clarified user application password updates with a dedicated name option.
  • Added documentation for more user update fields, including preferences, status, locale, and metadata.

• Bug Fixes

  • Improved handling of shell-array metadata when creating or updating comments and users.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: fd53f032-0cd5-47d6-9236-6546d10cd7ae

📥 Commits

Reviewing files that changed from the base of the PR and between 41a409d and 54c2ae5.

📒 Files selected for processing (4)

• src/Comment_Command.php
• src/Post_Command.php
• src/User_Application_Password_Command.php
• src/User_Command.php

Included review availability: Your plan includes up to 2 reviews per rolling hour; 1 remains after this review.

---

📝 Walkthrough

Walkthrough

The CLI documentation now lists additional comment, post, user, and application-password options. Comment and user update commands parse shell-array metadata before applying WordPress slashing and persistence.

Changes

CLI command updates

Layer / File(s)	Summary
Comment fields and metadata handling src/Comment_Command.php	Comment creation and update documentation lists supported fields and metadata. Both flows parse comment_meta before slashing and persistence.
Post and application-password options src/Post_Command.php, src/User_Application_Password_Command.php	Post documentation lists page_template and import_id. Application-password documentation exposes the name option.
User update fields and metadata src/User_Command.php	User update documentation lists additional fields and JSON meta_input. The update flow parses meta_input before calling wp_update_user.

Estimated code review effort: 2 (Simple) | ~10 minutes

Merge Risk: ⚪ Minimal · up to 54c2a

This PR documents accepted command fields and corrects array parsing and application-password argument handling without introducing an identified merge-blocking risk; it is merge-ready after normal checks and review.

Possibly related PRs

• wp-cli/entity-command#624: Both changes update wp user update field definitions and meta_input handling.

Suggested labels: command:ability

Suggested reviewers: brianhenryie

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: documenting accepted fields for catch-all write commands.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/wp-cli-issue-5286-n50evd

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.