Merge pull request #565 from wp-cli/add/handbook-2.12

ernilambar · web-flow · commit ad034c4af1fc · 2025-05-13T14:36:52.000+05:45
Update handbook after v2.12 release
diff --git a/bin/commands-manifest.json b/bin/commands-manifest.json
@@ -2119,6 +2119,22 @@
         "markdown_source": "https:\/\/github.com\/wp-cli\/handbook\/blob\/main\/commands\/transient\/list.md",
         "repo_url": "https:\/\/github.com\/wp-cli\/cache-command"
     },
+    "transient\/patch": {
+        "title": "transient patch",
+        "slug": "patch",
+        "cmd_path": "transient\/patch",
+        "parent": "transient",
+        "markdown_source": "https:\/\/github.com\/wp-cli\/handbook\/blob\/main\/commands\/transient\/patch.md",
+        "repo_url": "https:\/\/github.com\/wp-cli\/cache-command"
+    },
+    "transient\/pluck": {
+        "title": "transient pluck",
+        "slug": "pluck",
+        "cmd_path": "transient\/pluck",
+        "parent": "transient",
+        "markdown_source": "https:\/\/github.com\/wp-cli\/handbook\/blob\/main\/commands\/transient\/pluck.md",
+        "repo_url": "https:\/\/github.com\/wp-cli\/cache-command"
+    },
     "transient\/set": {
         "title": "transient set",
         "slug": "set",
diff --git a/commands/cache/patch.md b/commands/cache/patch.md
@@ -0,0 +1,66 @@
+# wp cache patch
+
+Update a nested value from the cache.
+
+### OPTIONS
+
+&lt;action&gt;
+: Patch action to perform.
+\---
+options:
+  - insert
+  - update
+  - delete
+\---
+
+&lt;key&gt;
+: Cache key.
+
+&lt;key-path&gt;...
+: The name(s) of the keys within the value to locate the value to patch.
+
+[&lt;value&gt;]
+: The new value. If omitted, the value is read from STDIN.
+
+[\--group=&lt;group&gt;]
+: Method for grouping data within the cache which allows the same key to be used across groups.
+\---
+default: default
+\---
+
+[\--expiration=&lt;expiration&gt;]
+ : Define how long to keep the value, in seconds. `0` means as long as possible.
+ ---
+ default: 0
+ ---
+
+[\--format=&lt;format&gt;]
+: The serialization format for the value.
+\---
+default: plaintext
+options:
+  - plaintext
+  - json
+\---
+
+### GLOBAL PARAMETERS
+
+These [global parameters](https://make.wordpress.org/cli/handbook/config/) have the same behavior across all commands and affect how WP-CLI interacts with WordPress.
+
+| **Argument**    | **Description**              |
+|:----------------|:-----------------------------|
+| `--path=<path>` | Path to the WordPress files. |
+| `--url=<url>` | Pretend request came from given URL. In multisite, this argument is how the target site is specified. |
+| `--ssh=[<scheme>:][<user>@]<host\|container>[:<port>][<path>]` | Perform operation against a remote server over SSH (or a container using scheme of "docker", "docker-compose", "docker-compose-run", "vagrant"). |
+| `--http=<http>` | Perform operation against a remote WordPress installation over HTTP. |
+| `--user=<id\|login\|email>` | Set the WordPress user. |
+| `--skip-plugins[=<plugins>]` | Skip loading all plugins, or a comma-separated list of plugins. Note: mu-plugins are still loaded. |
+| `--skip-themes[=<themes>]` | Skip loading all themes, or a comma-separated list of themes. |
+| `--skip-packages` | Skip loading all installed packages. |
+| `--require=<path>` | Load PHP file before running the command (may be used more than once). |
+| `--exec=<php-code>` | Execute PHP code before running the command (may be used more than once). |
+| `--context=<context>` | Load WordPress in a given context. |
+| `--[no-]color` | Whether to colorize the output. |
+| `--debug[=<group>]` | Show all PHP errors and add verbosity to WP-CLI output. Built-in groups include: bootstrap, commandfactory, and help. |
+| `--prompt[=<assoc>]` | Prompt the user to enter values for all command arguments, or a subset specified as comma-separated values. |
+| `--quiet` | Suppress informational messages. |
diff --git a/commands/cache/pluck.md b/commands/cache/pluck.md
@@ -0,0 +1,49 @@
+# wp cache pluck
+
+Get a nested value from the cache.
+
+### OPTIONS
+
+&lt;key&gt;
+: Cache key.
+
+&lt;key-path&gt;...
+: The name(s) of the keys within the value to locate the value to pluck.
+
+[\--group=&lt;group&gt;]
+: Method for grouping data within the cache which allows the same key to be used across groups.
+\---
+default: default
+\---
+
+[\--format=&lt;format&gt;]
+: The output format of the value.
+\---
+default: plaintext
+options:
+  - plaintext
+  - json
+  - yaml
+\---
+
+### GLOBAL PARAMETERS
+
+These [global parameters](https://make.wordpress.org/cli/handbook/config/) have the same behavior across all commands and affect how WP-CLI interacts with WordPress.
+
+| **Argument**    | **Description**              |
+|:----------------|:-----------------------------|
+| `--path=<path>` | Path to the WordPress files. |
+| `--url=<url>` | Pretend request came from given URL. In multisite, this argument is how the target site is specified. |
+| `--ssh=[<scheme>:][<user>@]<host\|container>[:<port>][<path>]` | Perform operation against a remote server over SSH (or a container using scheme of "docker", "docker-compose", "docker-compose-run", "vagrant"). |
+| `--http=<http>` | Perform operation against a remote WordPress installation over HTTP. |
+| `--user=<id\|login\|email>` | Set the WordPress user. |
+| `--skip-plugins[=<plugins>]` | Skip loading all plugins, or a comma-separated list of plugins. Note: mu-plugins are still loaded. |
+| `--skip-themes[=<themes>]` | Skip loading all themes, or a comma-separated list of themes. |
+| `--skip-packages` | Skip loading all installed packages. |
+| `--require=<path>` | Load PHP file before running the command (may be used more than once). |
+| `--exec=<php-code>` | Execute PHP code before running the command (may be used more than once). |
+| `--context=<context>` | Load WordPress in a given context. |
+| `--[no-]color` | Whether to colorize the output. |
+| `--debug[=<group>]` | Show all PHP errors and add verbosity to WP-CLI output. Built-in groups include: bootstrap, commandfactory, and help. |
+| `--prompt[=<assoc>]` | Prompt the user to enter values for all command arguments, or a subset specified as comma-separated values. |
+| `--quiet` | Suppress informational messages. |
diff --git a/commands/cli/check-update.md b/commands/cli/check-update.md
@@ -21,7 +21,7 @@ Queries the GitHub releases API. Returns available versions if there are updates
 : Prints the value of a single field for each update.
 
 [\--fields=&lt;fields&gt;]
-: Limit the output to specific object fields. Defaults to version,update_type,package_url.
+: Limit the output to specific object fields. Defaults to version,update_type,package_url,status,requires_php.
 
 [\--format=&lt;format&gt;]
 : Render output in a particular format.
diff --git a/commands/cli/update.md b/commands/cli/update.md
@@ -39,7 +39,7 @@ Only works for the Phar installation mechanism.
 
     # Update CLI.
     $ wp cli update
-    You have version 0.24.0. Would you like to update to 0.24.1? [y/n] y
+    You are currently using WP-CLI version 0.24.0. Would you like to update to 0.24.1? [y/n] y
     Downloading from https://github.com/wp-cli/wp-cli/releases/download/v0.24.1/wp-cli-0.24.1.phar...
     New version works. Proceeding to replace.
     Success: Updated WP-CLI to 0.24.1.
diff --git a/commands/comment/meta/get.md b/commands/comment/meta/get.md
@@ -10,6 +10,9 @@ Get meta field value.
 &lt;key&gt;
 : The name of the meta field to get.
 
+[\--single]
+: Whether to return a single value.
+
 [\--format=&lt;format&gt;]
 : Get value in a particular format.
 \---
diff --git a/commands/core/is-installed.md b/commands/core/is-installed.md
@@ -13,14 +13,14 @@ Determines whether WordPress is installed by checking if the standard database t
 
     # Bash script for checking if WordPress is not installed.
 
-    if ! wp core is-installed 2&gt;/dev/null; then
+    if ! wp core is-installed 2>/dev/null; then
         # WP is not installed. Let's try installing it.
         wp core install
     fi
 
     # Bash script for checking if WordPress is installed, with fallback.
 
-    if wp core is-installed 2&gt;/dev/null; then
+    if wp core is-installed 2>/dev/null; then
         # WP is installed. Let's do some things we should only do in a confirmed WP environment.
         wp core verify-checksums
     else
diff --git a/commands/core/verify-checksums.md b/commands/core/verify-checksums.md
@@ -24,6 +24,9 @@ If you experience issues verifying from this command, ensure you are passing the
 [\--insecure]
 : Retry downloads without certificate validation if TLS handshake fails. Note: This makes the request vulnerable to a MITM attack.
 
+[\--exclude=&lt;files&gt;]
+: Exclude specific files from the checksum verification. Provide a comma-separated list of file paths.
+
 ### EXAMPLES
 
     # Verify checksums
@@ -45,6 +48,10 @@ If you experience issues verifying from this command, ensure you are passing the
     Warning: File doesn't verify against checksum: wp-config-sample.php
     Error: WordPress installation doesn't verify against checksums.
 
+    # Verify checksums and exclude files
+    $ wp core verify-checksums --exclude="readme.html"
+    Success: WordPress installation verifies against checksums.
+
 ### GLOBAL PARAMETERS
 
 These [global parameters](https://make.wordpress.org/cli/handbook/config/) have the same behavior across all commands and affect how WP-CLI interacts with WordPress.
diff --git a/commands/db/export.md b/commands/db/export.md
@@ -32,6 +32,9 @@ Runs `mysqldump` utility using `DB_HOST`, `DB_NAME`, `DB_USER` and `DB_PASSWORD`
 [\--porcelain]
 : Output filename for the exported database.
 
+[\--add-drop-table]
+: Include a `DROP TABLE IF EXISTS` statement before each `CREATE TABLE` statement.
+
 [\--defaults]
 : Loads the environment's MySQL option files. Default behavior is to skip loading them to avoid failures due to misconfiguration.
 
diff --git a/commands/db/search.md b/commands/db/search.md
@@ -70,6 +70,15 @@ default: 40
 
 [\--format=&lt;format&gt;]
 : Render output in a particular format.
+\---
+options:
+  - table
+  - csv
+  - json
+  - yaml
+  - ids
+  - count
+\---
 
 The percent color codes available are:
 
@@ -105,6 +114,16 @@ The percent color codes available are:
 
 They can be concatenated. For instance, the default match color of black on a mustard (dark yellow) background `%3%k` can be made black on a bright yellow background with `%Y%0%8`.
 
+### AVAILABLE FIELDS
+
+These fields will be displayed by default for each result:
+
+* table
+* column
+* match
+* primary_key_name
+* primary_key_value
+
 ### EXAMPLES
 
     # Search through the database for the 'wordpress-develop' string
diff --git a/commands/dist-archive.md b/commands/dist-archive.md
@@ -30,6 +30,9 @@ Use one distribution archive command for many projects, instead of a bash script
 [\--create-target-dir]
 : Automatically create the target directory as needed.
 
+[\--force]
+: Forces overwriting of the archive file if it already exists.
+
 [\--plugin-dirname=&lt;plugin-slug&gt;]
 : Set the archive extract directory name. Defaults to project directory name.
 
diff --git a/commands/i18n/make-json.md b/commands/i18n/make-json.md
@@ -16,6 +16,12 @@ See https://make.wordpress.org/core/2018/11/09/new-javascript-i18n-support-in-wo
 [&lt;destination&gt;]
 : Path to the destination directory for the resulting JSON files. Defaults to the source directory.
 
+[\--domain=&lt;domain&gt;]
+: Text domain to use for the JSON file name. Overrides the default one extracted from the PO file.
+
+[\--extensions=&lt;extensions&gt;]
+: Additional custom JS extensions, comma separated list. By default searches for .min.js and .js extensions.
+
 [\--purge]
 : Whether to purge the strings that were extracted from the original source file. Defaults to true, use `--no-purge` to skip the removal.
 
diff --git a/commands/network/meta/get.md b/commands/network/meta/get.md
@@ -10,6 +10,9 @@ Get meta field value.
 &lt;key&gt;
 : The name of the meta field to get.
 
+[\--single]
+: Whether to return a single value.
+
 [\--format=&lt;format&gt;]
 : Get value in a particular format.
 \---
diff --git a/commands/plugin/install.md b/commands/plugin/install.md
@@ -13,6 +13,9 @@ Installs one or more plugins.
 [\--force]
 : If set, the command will overwrite any installed version of the plugin, without prompting for confirmation.
 
+[\--ignore-requirements]
+:If set, the command will install the plugin while ignoring any WordPress or PHP version requirements specified by the plugin authors.
+
 [\--activate]
 : If set, the plugin will be activated immediately after install.
 
diff --git a/commands/plugin/list.md b/commands/plugin/list.md
@@ -66,6 +66,8 @@ These fields are optionally available:
 * file
 * author
 * tested_up_to
+* requires
+* requires_php
 * wporg_status
 * wporg_last_updated
 
diff --git a/commands/post/meta/get.md b/commands/post/meta/get.md
@@ -10,6 +10,9 @@ Get meta field value.
 &lt;key&gt;
 : The name of the meta field to get.
 
+[\--single]
+: Whether to return a single value.
+
 [\--format=&lt;format&gt;]
 : Get value in a particular format.
 \---
diff --git a/commands/role/delete.md b/commands/role/delete.md
@@ -14,7 +14,7 @@ Deletes an existing role.
     Success: Role with key 'approver' deleted.
 
     # Delete productadmin role.
-    wp role delete productadmin
+    $ wp role delete productadmin
     Success: Role with key 'productadmin' deleted.
 
 ### GLOBAL PARAMETERS
diff --git a/commands/scaffold/plugin.md b/commands/scaffold/plugin.md
@@ -54,6 +54,7 @@ default: circle
 options:
   - circle
   - gitlab
+  - bitbucket
   - github
 \---
 
diff --git a/commands/site/meta/get.md b/commands/site/meta/get.md
@@ -10,6 +10,9 @@ Get meta field value.
 &lt;key&gt;
 : The name of the meta field to get.
 
+[\--single]
+: Whether to return a single value.
+
 [\--format=&lt;format&gt;]
 : Get value in a particular format.
 \---
diff --git a/commands/term/meta/get.md b/commands/term/meta/get.md
@@ -10,6 +10,9 @@ Get meta field value.
 &lt;key&gt;
 : The name of the meta field to get.
 
+[\--single]
+: Whether to return a single value.
+
 [\--format=&lt;format&gt;]
 : Get value in a particular format.
 \---
diff --git a/commands/theme/install.md b/commands/theme/install.md
@@ -13,6 +13,9 @@ Installs one or more themes.
 [\--force]
 : If set, the command will overwrite any installed version of the theme, without prompting for confirmation.
 
+[\--ignore-requirements]
+: If set, the command will install the theme while ignoring any WordPress or PHP version requirements specified by the theme authors.
+
 [\--activate]
 : If set, the theme will be activated immediately after install.
 
diff --git a/commands/transient/patch.md b/commands/transient/patch.md
diff --git a/commands/transient/pluck.md b/commands/transient/pluck.md
diff --git a/commands/user/remove-cap.md b/commands/user/remove-cap.md
diff --git a/commands/user/signup/list.md b/commands/user/signup/list.md
