wp-cli · swissspidy · Aug 17, 2026 · Aug 17, 2026 · Aug 17, 2026 · Aug 17, 2026
@@ -5443,41 +5443,60 @@ These fields are optionally available:
 Lists all sites in a multisite installation.
 
 ~~~
-wp site list [--network=<id>] [--<field>=<value>] [--site__in=<value>] [--site_user=<value>] [--site-path=<path>] [--blog_id=<blog_id>] [--site_id=<site_id>] [--domain=<domain>] [--registered=<date>] [--last_updated=<date>] [--public=<public>] [--archived=<archived>] [--mature=<mature>] [--spam=<spam>] [--deleted=<deleted>] [--lang_id=<lang_id>] [--field=<field>] [--fields=<fields>] [--format=<format>]
+wp site list [--network=<id>|site_id|network_id] [--<field>=<value>] [--site__in=<value>] [--site__not_in=<value>] [--site_user=<value>] [--site-path=<path>] [--path__in=<value>] [--path__not_in=<value>] [--blog_id=<blog_id>|ID] [--network__in=<value>] [--network__not_in=<value>] [--domain=<domain>] [--domain__in=<value>] [--domain__not_in=<value>] [--registered=<date>] [--last_updated=<date>] [--public=<public>] [--archived=<archived>] [--mature=<mature>] [--spam=<spam>] [--deleted=<deleted>] [--lang_id=<lang_id>] [--lang__in=<value>] [--lang__not_in=<value>] [--search=<string>] [--search_columns=<columns>] [--meta_key=<meta_key>] [--meta_value=<meta_value>] [--meta_compare=<meta_compare>] [--meta_type=<meta_type>] [--meta_query=<meta_query>] [--date_query=<date_query>] [--number=<number>] [--offset=<offset>] [--no_found_rows=<no_found_rows>] [--update_site_cache=<update_site_cache>] [--update_site_meta_cache=<update_site_meta_cache>] [--orderby=<field>] [--order=<order>] [--field=<field>] [--fields=<fields>] [--format=<format>]
 ~~~
 
 **OPTIONS**
 
-	[--network=<id>]
-		The network to which the sites belong.
+	[--network=<id>|site_id|network_id]
+		The network to which the sites belong. `--site_id` is the name of the
+		column this filters, `--network_id` is WP_Site_Query's name for it, and
+		both are accepted as aliases. `--network` wins when more than one is given.
 
 	[--<field>=<value>]
 		Filter by one or more fields (see "Available Fields" section), or pass any
-		other argument accepted by WP_Site_Query, such as 'search', 'site__not_in',
-		'number', 'offset', 'orderby' or 'order'. However, 'url' isn't an available
+		other argument accepted by WP_Site_Query. However, 'url' isn't an available
 		filter, as it comes from 'home' in wp_options.
 		Note: '--path' conflicts with the global parameter of the same name; use
 		'--site-path' to filter by path instead.
 
 	[--site__in=<value>]
 		Only list the sites with these blog_id values (comma-separated).
 
+	[--site__not_in=<value>]
+		Exclude the sites with these blog_id values (comma-separated).
+
 	[--site_user=<value>]
 		Only list the sites with this user.
 
 	[--site-path=<path>]
 		Filter by path. Avoids conflict with the global `--path` parameter.
 
-	[--blog_id=<blog_id>]
-		Filter by site ID.
+	[--path__in=<value>]
+		Only list the sites with these paths (comma-separated).
+
+	[--path__not_in=<value>]
+		Exclude the sites with these paths (comma-separated).
+
+	[--blog_id=<blog_id>|ID]
+		Filter by site ID. `--ID` is WP_Site_Query's name for the same filter
+		and is accepted as an alias.
+
+	[--network__in=<value>]
+		Only list the sites belonging to these network IDs (comma-separated).
 
-	[--site_id=<site_id>]
-		Filter by the ID of the network the site belongs to. `--network` is an
-		alias for this, and takes precedence when both are given.
+	[--network__not_in=<value>]
+		Exclude the sites belonging to these network IDs (comma-separated).
 
 	[--domain=<domain>]
 		Filter by domain.
 
+	[--domain__in=<value>]
+		Only list the sites with these domains (comma-separated).
+
+	[--domain__not_in=<value>]
+		Exclude the sites with these domains (comma-separated).
+
 	[--registered=<date>]
 		Filter by the date the site was registered. Accepts a timestamp or a
 		date; a value carrying no time of day matches that whole day.
@@ -5504,6 +5523,72 @@ wp site list [--network=<id>] [--<field>=<value>] [--site__in=<value>] [--site_u
 	[--lang_id=<lang_id>]
 		Filter by language ID.
 
+	[--lang__in=<value>]
+		Only list the sites with these language IDs (comma-separated).
+
+	[--lang__not_in=<value>]
+		Exclude the sites with these language IDs (comma-separated).
+
+	[--search=<string>]
+		Only list the sites matching this search term. Searches the domain and
+		path columns unless `--search_columns` narrows it.
+
+	[--search_columns=<columns>]
+		Comma-separated list of columns `--search` looks in. Accepts 'domain'
+		and 'path'.
+
+	[--meta_key=<meta_key>]
+		Filter by this site meta key. The site meta arguments need WordPress 5.1
+		or later, which is where multisite gained the table they read.
+
+	[--meta_value=<meta_value>]
+		Filter by this site meta value. Used together with `--meta_key`.
+
+	[--meta_compare=<meta_compare>]
+		Operator to test the meta value against. Accepts the operators
+		WP_Meta_Query supports, such as '=', '!=', 'LIKE' or 'IN'.
+
+	[--meta_type=<meta_type>]
+		Cast the meta value to this type, such as 'NUMERIC' or 'DATE'.
+
+	[--meta_query=<meta_query>]
+		A WP_Meta_Query clause list, as JSON, for conditions the meta_* arguments
+		above cannot express.
+
+	[--date_query=<date_query>]
+		A WP_Date_Query clause list, as JSON, for ranges `--registered` and
+		`--last_updated` cannot express. Giving those as well narrows this further
+		rather than replacing it.
+
+	[--number=<number>]
+		Limit the number of sites returned.
+
+	[--offset=<offset>]
+		Number of sites to skip. Used together with `--number`.
+
+	[--no_found_rows=<no_found_rows>]
+		Whether to skip counting the total rows the query matches. Accepts 1 or 0.
+
+	[--update_site_cache=<update_site_cache>]
+		Whether to prime the object cache with the sites found. Accepts 1 or 0.
+		Turning it off saves work when listing a large network once.
+
+	[--update_site_meta_cache=<update_site_meta_cache>]
+		Whether to prime the object cache with the site meta of the sites found.
+		Accepts 1 or 0.
+
+	[--orderby=<field>]
+		Order the results by this field, such as 'blog_id', 'domain', 'path',
+		'registered', 'last_updated' or 'site__in'.
+
+	[--order=<order>]
+		Whether to order the results ascending or descending.
+		---
+		options:
+		  - asc
+		  - desc
+		---
+
 	[--field=<field>]
 		Prints the value of a single field for each site.
 

@@ -1087,6 +1087,199 @@ Feature: Manage sites in a multisite installation
       1
       """
 
+  Scenario: List sites using the WP_Site_Query arguments that take a list
+    Given a WP multisite install
+
+    When I run `wp site create --slug=alpha --porcelain`
+    Then STDOUT should be a number
+    And save STDOUT as {ALPHA_ID}
+
+    When I run `wp site create --slug=beta --porcelain`
+    Then STDOUT should be a number
+    And save STDOUT as {BETA_ID}
+
+    # WP_Site_Query reads these through is_array(), so before they were split
+    # they were skipped without a word and every site came back.
+    When I run `wp site list --path__in=/alpha/,/beta/ --field=blog_id`
+    Then STDOUT should be:
+      """
+      {ALPHA_ID}
+      {BETA_ID}
+      """
+
+    When I run `wp site list --path__not_in=/alpha/,/beta/ --field=blog_id`
+    Then STDOUT should be:
+      """
+      1
+      """
+
+    When I run `wp site list --domain__in=example.com --format=count`
+    Then STDOUT should be:
+      """
+      3
+      """
+
+    When I run `wp site list --domain__not_in=example.com --format=count`
+    Then STDOUT should be:
+      """
+      0
+      """
+
+    # --search_columns reaches array_intersect(), which is fatal on a string.
+    When I run `wp site list --search=alpha --search_columns=path --field=blog_id`
+    Then STDOUT should be:
+      """
+      {ALPHA_ID}
+      """
+
+    When I run `wp site list --search=alpha --search_columns=domain --format=count`
+    Then STDOUT should be:
+      """
+      0
+      """
+
+    # The remaining newly documented filters.
+    When I run `wp site list --network__in=1 --format=count`
+    Then STDOUT should be:
+      """
+      3
+      """
+
+    When I run `wp site list --network__not_in=1 --format=count`
+    Then STDOUT should be:
+      """
+      0
+      """
+
+    When I run `wp site list --lang__in=0 --format=count`
+    Then STDOUT should be:
+      """
+      3
+      """
+
+    When I run `wp site list --ID={ALPHA_ID} --field=blog_id`
+    Then STDOUT should be:
+      """
+      {ALPHA_ID}
+      """
+
+    When I run `wp site list --network_id=1 --format=count`
+    Then STDOUT should be:
+      """
+      3
+      """
+
+    # --date_query is a nested array, so it is given as JSON.
+    When I run `wp site list --date_query='[{"column":"registered","after":"1999-01-01"}]' --format=count`
+    Then STDOUT should be:
+      """
+      3
+      """
+
+    When I run `wp site list --date_query='[{"column":"registered","before":"1999-01-01"}]' --format=count`
+    Then STDOUT should be:
+      """
+      0
+      """
+
+    # --registered narrows a --date_query of its own rather than replacing it. The
+    # date on its own has to match first, or the pair below would prove nothing.
+    When I run `wp site list --blog_id={ALPHA_ID} --field=registered`
+    Then save STDOUT as {ALPHA_REGISTERED}
+
+    When I run `wp site list --blog_id={ALPHA_ID} --registered='{ALPHA_REGISTERED}' --format=count`
+    Then STDOUT should be:
+      """
+      1
+      """
+
+    When I run `wp site list --blog_id={ALPHA_ID} --date_query='[{"column":"registered","before":"1999-01-01"}]' --registered='{ALPHA_REGISTERED}' --format=count`
+    Then STDOUT should be:
+      """
+      0
+      """
+
+    # The relation of a given --date_query governs only its own clauses. Appending
+    # to the same list would let an 'OR' reach the clause --registered adds and
+    # match a site that satisfies neither half of what was asked for.
+    When I run `wp site list --blog_id={ALPHA_ID} --date_query='{"relation":"OR","0":{"column":"registered","before":"1999-01-01"},"1":{"column":"registered","before":"1998-01-01"}}' --registered='{ALPHA_REGISTERED}' --format=count`
+    Then STDOUT should be:
+      """
+      0
+      """
+
+    When I run `wp site list --blog_id={ALPHA_ID} --field=last_updated`
+    Then save STDOUT as {ALPHA_UPDATED}
+
+    When I run `wp site list --blog_id={ALPHA_ID} --last_updated='{ALPHA_UPDATED}' --format=count`
+    Then STDOUT should be:
+      """
+      1
+      """
+
+    When I run `wp site list --blog_id={ALPHA_ID} --date_query='{"relation":"OR","0":{"column":"last_updated","before":"1999-01-01"},"1":{"column":"last_updated","before":"1998-01-01"}}' --last_updated='{ALPHA_UPDATED}' --format=count`
+    Then STDOUT should be:
+      """
+      0
+      """
+
+    When I try `wp site list --meta_query=notjson`
+    Then STDERR should contain:
+      """
+      Invalid JSON passed to --meta_query.
+      """
+    And the return code should be 1
+
+    When I try `wp site list --date_query=notjson`
+    Then STDERR should contain:
+      """
+      Invalid JSON passed to --date_query.
+      """
+    And the return code should be 1
+
+  # WP_Site_Query gained the meta_* parameters, and multisite gained the site meta
+  # table they read, in WordPress 5.1.
+  @require-wp-5.1
+  Scenario: Filter the site list by site meta
+    Given a WP multisite install
+
+    When I run `wp site create --slug=alpha --porcelain`
+    Then STDOUT should be a number
+    And save STDOUT as {ALPHA_ID}
+
+    When I run `wp site create --slug=beta --porcelain`
+    Then STDOUT should be a number
+    And save STDOUT as {BETA_ID}
+
+    When I run `wp site meta add {ALPHA_ID} colour blue`
+    Then STDOUT should not be empty
+
+    When I run `wp site list --meta_key=colour --meta_value=blue --field=blog_id`
+    Then STDOUT should be:
+      """
+      {ALPHA_ID}
+      """
+
+    When I run `wp site list --meta_key=colour --meta_value=red --format=count`
+    Then STDOUT should be:
+      """
+      0
+      """
+
+    # --meta_query is a nested array, so it is given as JSON.
+    When I run `wp site list --meta_query='[{"key":"colour","value":"blue"}]' --field=blog_id`
+    Then STDOUT should be:
+      """
+      {ALPHA_ID}
+      """
+
+    When I run `wp site list --meta_query='[{"key":"colour","compare":"NOT EXISTS"}]' --field=blog_id`
+    Then STDOUT should be:
+      """
+      1
+      {BETA_ID}
+      """
+
   Scenario: Existing site list filters keep working against WP_Site_Query
     Given a WP multisite install