How do I run a search and replace in the WordPress CLI?

Doc Summary

The WordPress Command Line Interface (CLI) search and replace function is a useful tool when you need to make global changes to your WordPress site’s content.

Some common use cases for this function include:

Changing the site URL: If you’re moving your WordPress site to a new domain or subdomain, you can use the search and replace function to replace all instances of the old URL with the new one.
Updating internal links: If you’ve made changes to the structure of your site and need to update internal links, you can use the search and replace function to find and replace those links quickly and easily.
Replacing deprecated code: If you’re using outdated code on your site, you can use the search and replace function to replace it with updated, functional code.
Updating plugin settings: If you need to update settings for a specific plugin across your site, you can use the search and replace function to make the change to all instances of the plugin’s settings in the database.
Cleaning up data: If you need to remove specific text or data from your site, you can use the search and replace function to find and replace that data with an empty string.

It’s important to understand that the search and replace function operates directly on the WordPress database, so it’s essential to back up your database before running the command to avoid any potential data loss. We’d recommend taking a snapshot of your site files and database prior to running the search and replace. Additionally, it’s recommended to test the function on a staging site before making any changes to your live site.

To use the search and replace function, you’ll need to access your website via the command line through SSH and navigate to the directory where WordPress is installed. If you’re unsure about how to connect via SSH then please see this guide: How to connect through SSH.

From there, you can run the following command:

wp search-replace old-string new-string [--network] [--dry-run]

Where:

‘old-string’ is the string you want to search for and replace.

‘new-string’ is the string you want to replace old-string with.

–network is an optional argument that, when used, will perform the search and replace operation on all sites in a WordPress network.

–dry-run is an optional argument that, when used, will perform a dry run of the search and replace operation, meaning it will show you what would be changed, but will not make any actual changes to the database.

For example, if you wanted to replace your temp URL with the live domain name, you’d enter the following:

wp search-replace domain-com.stackstaging.com domain.com

The above would immediately make all the appropriate replacements. If you’d rather perform a ‘dry run’ first then you’d need to enter the ‘–dry-run’ flag at the end of the command:

wp search-replace domain-com.stackstaging.com domain.com --dry-run

To perform the action across all sites on the WordPress Network (Multisite) then run the following:

wp search-replace domain-com.stackstaging.com domain.com --network

What are the risks involved with using Search and Replace in the WP CLI?

Data loss: if the search and replace function is not used correctly, it can result in data loss. For example, if you use the function to search for a string that’s found within another string in the database, it could result in unintended changes. It’s important to back up your database before using the function to ensure that you can restore your site if any issues arise.
Incorrect replacements: if you make a mistake in the search or replace string, it can result in incorrect replacements in the database. This can lead to broken links, incorrect display of content, or other issues on your site.
Incompatible changes: if you’re using a plugin or theme that adds custom data to the database, the search and replace function may not be compatible with that data. It may result in unexpected changes or errors.
Search and replace errors: if there are any errors in the search and replace function, it could result in incomplete replacements or other issues with the database.

In conclusion, it’s important to use the WordPress CLI search and replace function with caution and to thoroughly test the function before using it on a live site.

It’s also recommended to have a good understanding of how the function works and the potential issues that can arise. This way, you can avoid any problems and ensure a smooth and successful search and replace operation.