One of the more advanced features of WP-CLI is its powerful search and replace function. Search-replace is very handy when changing a site's URL or other frequently appearing text inside a WordPress database. It can save a vast amount of time over manually updating these values and is much easier than crafting a raw MySQL query to do the same thing.
First, SSH in to your server as your WordPress app's system user; do not use root with WP-CLI as it could break your app.
Then, navigate to your app's public directory by entering the following commands, replacing "APPNAME" with your app's name:
cd apps cd APPNAME cd public
Now, type wp search-replace and press Enter. WP-CLI will offer the acceptable arguments for this command:
usage: wp search-replace <old> <new> [<table>...] [--dry-run] [--network] [--all-tables-with-prefix] [--all-tables] [--export[=<file>]] [--export_insert_size=<rows>] [--skip-columns=<columns>] [--include-columns=<columns>] [--precise] [--recurse-objects] [--verbose] [--regex] [--regex-flags=<regex-flags>]
You can also use wp help search-replace for additional help.
Even though many options are possible with wp search-replace, this tutorial will cover the most common use: changing all instances of one domain to another.
A very useful feature of wp search-replace is its ability to not only scan the entire database but also unpack JSON payloads within the database, performing its tasks on them as well.
The wp search-replace function is somewhat peculiar in its case sensitivity; for the best results, match cases exactly and search for other capitalization instances using the --dry-run option.
One of the most notable and helpful flags for wp search-replace is the --dry-run switch. This will show you what would be changed by the command you have entered, giving you the opportunity to correct potential mistakes without making changes or causing damage to your WordPress app.
If the --dry-run flag is not used, all instances of the first value will be replaced by the second.
First, do a dry run for safety:
wp search-replace olddomain.com newdomain.com --dry-run
The output will display the database table names, columns, how many replacements would be made within each table, and what type of data each table contains; however, no changes will actually be made.
+------------------------+-----------------+--------------+------+ | Table | Column | Replacements | Type | +------------------------+-----------------+--------------+------+ | wp_c7734cd387_comments | comment_content | 0 | SQL | | wp_c7734cd387_links | link_url | 0 | SQL | | wp_c7734cd387_links | link_image | 0 | SQL | | wp_c7734cd387_options | option_value | 2 | SQL | | wp_c7734cd387_posts | post_content | 1 | SQL | | wp_c7734cd387_posts | post_title | 0 | SQL | | wp_c7734cd387_posts | guid | 2 | SQL | | wp_c7734cd387_users | display_name | 0 | SQL | +------------------------+-----------------+--------------+------+ Success: 5 replacements to be made.
In the sample above, the output shows "5 replacements to be made"; if the --dry-run flag was not used, the output would show "made X replacements."
After verifying the changes look correct in your dry run, it's time to actually make the changes by running the wp search-replace without the --dry-run flag:
wp search-replace olddomain.com newdomain.com
This time, the output is almost identical with the exception of the Success message as shown in the example below:
+------------------------+-----------------+--------------+------+ | Table | Column | Replacements | Type | +------------------------+-----------------+--------------+------+ | wp_c7734cd387_comments | comment_content | 0 | SQL | | wp_c7734cd387_links | link_url | 0 | SQL | | wp_c7734cd387_links | link_image | 0 | SQL | | wp_c7734cd387_options | option_value | 2 | SQL | | wp_c7734cd387_posts | post_content | 1 | SQL | | wp_c7734cd387_posts | post_title | 0 | SQL | | wp_c7734cd387_posts | guid | 2 | SQL | | wp_c7734cd387_users | display_name | 0 | SQL | +------------------------+-----------------+--------------+------+ Success: Made 5 replacements.
As mentioned earlier, many options exist for wp search-replace. You can use the function on any string within the database, including email addresses and image names.
Use the following command, followed by any flags and arguments you wish to provide:
wp search-replace EXISTING-STRING NEW-STRING
More information can be found in the official WP-CLI documentation.