Follows #639, which handed every unrecognised argument to WP_Site_Query and so left the command accepting a good deal more than it described. The aim here is a single property: an argument works if and only if it is documented, in both directions.

Writing the set down is what turned up the problems. Five arguments were reachable but did not do what their name says, and documenting them as they stood would have promised behaviour that never happens — the silent no-op that wp-cli/wp-cli#5286 is about.

What was broken

Measured rather than assumed — every value below is a string, which is all the command line can hand over:

domain__in     = example.com  -> 3 sites (unfiltered is also 3)
domain__not_in = example.com  -> 3 sites
path__in       = /alpha/      -> 3 sites
path__not_in   = /alpha/      -> 3 sites
search_columns = domain       -> THROWS: TypeError

They are split on commas before the query runs, which is what makes them mean anything here.

meta_query and date_query

These are nested arrays, so no flat string can describe one. Utils\parse_shell_arrays() is how this package already takes such arguments — wp comment create --comment_meta and wp user update --meta_input both use it — so they are given the same way:

$ wp site list --meta_query='[{"key":"colour","value":"blue"}]'
$ wp site list --date_query='[{"column":"registered","after":"2020-01-01"}]'

parse_shell_arrays() deliberately leaves a value that is not JSON alone, which would put a string where WP_Site_Query expects an array and have it ignored without a word, so that case is an error instead.

A --date_query given directly is kept when --registered or --last_updated are given as well, so those narrow it rather than quietly winning. It is nested a level down under an outer AND rather than appended to, because a date query's relation governs whatever shares its list — appending let an OR reach the clauses --registered adds and match a site satisfying neither half of the request. Thanks to @coderabbitai for catching that; the reproduction and fix are in the thread.

Aliases

Two filters had more than one name for the same thing, so they are declared as aliases rather than separate entries:

• [--blog_id=<blog_id>|ID] — ID is WP_Site_Query's name for this command's --blog_id.
• [--network=<id>|site_id|network_id] — site_id is the column, network_id is WP_Site_Query's name. --network stays canonical because wp-cli lets the canonical name win when several are given, which is the precedence --network has always had over --site_id.

What is left withheld

count alone, and it has to be: it makes get_sites() return an integer rather than a list, and --format=count is how this command spells that.

Every other WP_Site_Query argument is documented, across 42 option entries covering 44 names. Nothing the command accepts is left undescribed, and nothing described fails to work.

The site meta filters need WordPress 5.1, which is where multisite gained the table they read and WP_Site_Query gained the meta_* parameters; the docblock says so and their scenario is tagged for it. Everything else here dates from 4.6, or 4.8 for the lang_* filters.

Why the exactness matters

wp-cli/wp-cli#6392 would reject an argument that is undocumented but within edit distance 2 of one that is documented. Checked against the full query-var list:

WP_Site_Query vars: 37 | documented names: 44
withheld: count (changes the return type)
reachable but undocumented: 0
No collisions.

--lang__in was the specific case raised on that PR; it is documented now, so it works and does not warn.

Testing

Two scenarios added, covering the newly working list arguments, the JSON arguments, the date-query nesting, the invalid-JSON errors, and the site meta filters.

Each new assertion was checked against the regression it is meant to catch, by reverting only the source change:

• Dropping the comma split makes --path__in=/alpha/,/beta/ return all three sites instead of two.
• Restoring the flat date-query merge makes the OR assertions return 1 instead of 0.

That second check earned its keep twice. The first merge assertion passed either way — both paths returned 0 for the case it used — so it proved nothing until it was rewritten. The rewritten one still used the default AND relation, which is exactly why the OR defect got through to review.

PHPCS clean. PHPStan back to the origin/main total with the same two pre-existing Site_Command.php findings; assigning parse_shell_arrays() straight back to $assoc_args widens it to mixed and cascades five errors into the explode, get_check() and array_map calls downstream, so the decoded value goes into the query arguments instead.

Two judgement calls

Both easy to change if you would rather they went the other way:

• --registered/--last_updated narrow a supplied --date_query rather than replacing it.
• The cache and paging knobs (no_found_rows, update_site_cache, update_site_meta_cache) are documented as "Accepts 1 or 0", matching the existing boolean filters, rather than being withheld as internals.

🤖 Generated with Claude Code

https://claude.ai/code/session_014SSZzqMJRDTiLiDxQEPYcL