Document the meta, time, password and ordering arguments too

Sweeping the rest of WP_Query's query vars turned up more that work here and
nothing writes down. Each was tried with a value shaped the way the command
line delivers it, and only the ones that changed the result are documented:

- meta_key and meta_value, which is how you filter on a custom field
- hour, minute and second, which finish the date family that already had
  year, monthnum, day, m and w
- has_password and post_password
- orderby and order

Left alone for cause: 'sentence', 'perm', 'preview', 'error', 'tb', 'paged',
'embed' and 'sticky' change nothing when passed, and 'page_id' filters but
sits within two edits of 'paged' and 'tag_id', so documenting it would add
two false positives to wp-cli/wp-cli#6392 the way 'tag_id' would.

All three of hour, minute and second together is deliberately not asserted.
That path compares a DATE_FORMAT() string rather than separate HOUR() and
MINUTE() clauses, and the SQLite integration plugin does not emulate it the
way MySQL does: the same query matches on MariaDB and matches nothing on
SQLite. Two units at a time behaves the same on both and is covered.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014SSZzqMJRDTiLiDxQEPYcL

Author: claude

README.md

@@ -3150,7 +3150,7 @@ wp post get <id> [--field=<field>] [--fields=<fields>] [--format=<format>]
 Gets a list of posts.
 
 ~~~
-wp post list [--<field>=<value>] [--p=<id>|ID] [--title=<title>|post_title] [--name=<slug>|post_name] [--author=<author>|post_author] [--author_name=<author_name>] [--cat=<cat>] [--category_name=<category_name>] [--tag=<tag>] [--post_type=<post_type>] [--post_status=<post_status>] [--post_parent=<post_parent>] [--post_mime_type=<post_mime_type>] [--menu_order=<menu_order>] [--comment_status=<comment_status>] [--ping_status=<ping_status>] [--comment_count=<comment_count>] [--s=<string>] [--year=<year>] [--monthnum=<monthnum>] [--day=<day>] [--m=<yearmonth>] [--w=<week>] [--field=<field>] [--fields=<fields>] [--format=<format>]
+wp post list [--<field>=<value>] [--p=<id>|ID] [--title=<title>|post_title] [--name=<slug>|post_name] [--author=<author>|post_author] [--author_name=<author_name>] [--cat=<cat>] [--category_name=<category_name>] [--tag=<tag>] [--post_type=<post_type>] [--post_status=<post_status>] [--post_parent=<post_parent>] [--post_mime_type=<post_mime_type>] [--menu_order=<menu_order>] [--comment_status=<comment_status>] [--ping_status=<ping_status>] [--comment_count=<comment_count>] [--s=<string>] [--year=<year>] [--monthnum=<monthnum>] [--day=<day>] [--hour=<hour>] [--minute=<minute>] [--second=<second>] [--m=<yearmonth>] [--w=<week>] [--meta_key=<meta_key>] [--meta_value=<meta_value>] [--has_password=<has_password>] [--post_password=<post_password>] [--orderby=<orderby>] [--order=<order>] [--field=<field>] [--fields=<fields>] [--format=<format>]
 ~~~
 
 Display posts based on all arguments supported by [WP_Query()](https://developer.wordpress.org/reference/classes/wp_query/).
@@ -3236,12 +3236,43 @@ Only shows post types marked as post by default.
 	[--day=<day>]
 		Filter by day of the month, 1 to 31.
 
+	[--hour=<hour>]
+		Filter by hour, 0 to 23.
+
+	[--minute=<minute>]
+		Filter by minute, 0 to 59.
+
+	[--second=<second>]
+		Filter by second, 0 to 59.
+
 	[--m=<yearmonth>]
 		Filter by year and month together, e.g. 202401.
 
 	[--w=<week>]
 		Filter by week of the year, 0 to 53.
 
+	[--meta_key=<meta_key>]
+		Filter by posts having this meta key. Pair it with `--meta_value` to
+		filter on the value as well.
+
+	[--meta_value=<meta_value>]
+		Filter by this meta value. Needs `--meta_key` to say which key it
+		belongs to.
+
+	[--has_password=<has_password>]
+		Filter by whether the post has a password. Accepts 1 or 0.
+
+	[--post_password=<post_password>]
+		Filter by the post's password, matched in full.
+
+	[--orderby=<orderby>]
+		Order the results by this field. Accepts what WP_Query accepts, e.g.
+		'date', 'title', 'ID', 'menu_order', 'rand', or 'meta_value' alongside
+		`--meta_key`.
+
+	[--order=<order>]
+		Direction to order by. Accepts 'ASC' or 'DESC'.
+
 	[--field=<field>]
 		Prints the value of a single field for each post.
 

features/post.feature

@@ -723,3 +723,72 @@ Feature: Manage WordPress posts
       """
       1
       """
+
+  Scenario: Filtering by meta, time of day, password and order
+    When I run `wp post create --post_title='Timed' --post_status=publish --post_date='2020-03-04 05:06:07' --porcelain`
+    Then STDOUT should be a number
+    And save STDOUT as {TIMED_ID}
+
+    When I run `wp post meta add {TIMED_ID} color blue`
+    Then STDOUT should not be empty
+
+    When I run `wp post create --post_title='Locked' --post_status=publish --post_password=secret --porcelain`
+    Then STDOUT should be a number
+
+    # Time of day, alongside the year/month/day filters already documented.
+    # Two units at once exercises the combined path; all three of hour, minute
+    # and second together is left out on purpose, because that path compares a
+    # DATE_FORMAT() string and the SQLite integration plugin does not emulate
+    # it the way MySQL does, so it matches nothing there.
+    When I run `wp post list --hour=5 --minute=6 --field=post_title`
+    Then STDOUT should be:
+      """
+      Timed
+      """
+
+    When I run `wp post list --second=7 --field=post_title`
+    Then STDOUT should be:
+      """
+      Timed
+      """
+
+    # A meta key on its own, then narrowed by its value.
+    When I run `wp post list --meta_key=color --field=post_title`
+    Then STDOUT should be:
+      """
+      Timed
+      """
+
+    When I run `wp post list --meta_key=color --meta_value=red --format=count`
+    Then STDOUT should be:
+      """
+      0
+      """
+
+    When I run `wp post list --has_password=1 --field=post_title`
+    Then STDOUT should be:
+      """
+      Locked
+      """
+
+    When I run `wp post list --post_password=secret --field=post_title`
+    Then STDOUT should be:
+      """
+      Locked
+      """
+
+    When I run `wp post list --orderby=title --order=ASC --field=post_title`
+    Then STDOUT should be:
+      """
+      Hello world!
+      Locked
+      Timed
+      """
+
+    When I run `wp post list --orderby=title --order=DESC --field=post_title`
+    Then STDOUT should be:
+      """
+      Timed
+      Locked
+      Hello world!
+      """

src/Post_Command.php

@@ -694,12 +694,43 @@ protected function delete_callback( $post_id, $assoc_args ) {
 	 * [--day=<day>]
 	 * : Filter by day of the month, 1 to 31.
 	 *
+	 * [--hour=<hour>]
+	 * : Filter by hour, 0 to 23.
+	 *
+	 * [--minute=<minute>]
+	 * : Filter by minute, 0 to 59.
+	 *
+	 * [--second=<second>]
+	 * : Filter by second, 0 to 59.
+	 *
 	 * [--m=<yearmonth>]
 	 * : Filter by year and month together, e.g. 202401.
 	 *
 	 * [--w=<week>]
 	 * : Filter by week of the year, 0 to 53.
 	 *
+	 * [--meta_key=<meta_key>]
+	 * : Filter by posts having this meta key. Pair it with `--meta_value` to
+	 * filter on the value as well.
+	 *
+	 * [--meta_value=<meta_value>]
+	 * : Filter by this meta value. Needs `--meta_key` to say which key it
+	 * belongs to.
+	 *
+	 * [--has_password=<has_password>]
+	 * : Filter by whether the post has a password. Accepts 1 or 0.
+	 *
+	 * [--post_password=<post_password>]
+	 * : Filter by the post's password, matched in full.
+	 *
+	 * [--orderby=<orderby>]
+	 * : Order the results by this field. Accepts what WP_Query accepts, e.g.
+	 * 'date', 'title', 'ID', 'menu_order', 'rand', or 'meta_value' alongside
+	 * `--meta_key`.
+	 *
+	 * [--order=<order>]
+	 * : Direction to order by. Accepts 'ASC' or 'DESC'.
+	 *
 	 * [--field=<field>]
 	 * : Prints the value of a single field for each post.
 	 *