Whether you’re switching to Secure Sockets Layer (SSL) or changing domain names entirely, it can be a daunting task to use MySQL to try and replace all of the old instances of your domain name. For example, should you search for a reliable plugin, or directly manage the database with software such as phpMyAdmin?
There’s actually a third way: you can use the WordPress Command Line Interface (WP-CLI) to change domain names in under a minute within your console. You don’t need to know anything about MySQL, and as long as you’re okay with the idea of using the command line, this is a great option. Plus, if your hosting company offers WP-CLI as a feature, you may already be able to use it without any extra hassle.
In this article, we’ll firstly explain to you what the WP-CLI project is all about. Then, we’ll show you how to quickly backup your database and switch domain names with two simple commands.
An Introduction to the WP-CLI Project
Traditional WordPress development involves manual management within the admin or writing PHP code for most solutions. The ever-growing WP-CLI streamlines this process by giving you shorthand for handling many tasks, which circumvents the need for additional maintenance plugins that clutter your dashboard.
Once you get the hang of it, using the WP-CLI can dramatically speed up your development process. For instance, you can make database changes, install plugins, or manage your themes within a few keystrokes. You can even manage comments, options, and menus!
One task the WP-CLI makes simple is to search and replace specific text on your entire WordPress site. You would normally need a plugin or have good working knowledge of MySQL to do this. This feature comes in handy when you change domain names (or install an SSL certificate) and need to replace all mentions of the old domain name with the new one.
Changing the domain name within your site used to be a tedious, multistep process with many moving parts. With the WP-CLI, updating mentions of the old domain on your entire site can take less than a minute.
How to Use the WP-CLI Search-Replace Command to Change Domain Names (in 3 Simple Steps)
Before proceeding, let’s clear up what this tutorial will and won’t help you do. What we’re covering is one step in a much bigger process, and it can be easy to mix things up.
By the end of this tutorial, you’ll know how to use the WP-CLI to search and replace your old domain with your new domain. This process includes all of your content and settings within the WordPress database. This is something you need to do whenever you switch domain names, or if you decide to move from HTTP to HTTPS.
However, this tutorial does not purchase and setup a new domain, install SSL and make HTTPS work, or get you started with SSH – you’ll need to make sure that any new domains or secure configurations are already in place before proceeding.
When it comes to technical prerequisites, you’ll need SSH access to your WordPress server, and have a working copy of the WP-CLI installed on it. We previously produced a guide on the latter. Once you’re logged in via SSH, we can get started!
Step 1: Back up Your Database
While it’s not completely necessary to back up using the WP-CLI, we highly recommended you carry out a full backup before altering the database. Of course, you should be backing up your site on a regular basis, but it’s especially crucial when you are about to make a big change.
If you already have a backup system or plugin in place, feel free to continue using it. However, let’s show you how a WordPress backup can be achieved with the WP-CLI.
Firstly, let’s check that the WP-CLI is able to detect your WordPress site. Try running the following command:
wp core is-installed
If you receive any kind of error message, make sure WordPress is up and running, and that you’re in the correct WordPress directory within the console. Once you’re set, initiating the backup is as simple as typing:
wp db export
This command should generate a database backup, and you should receive a success message if it runs correctly. If all goes well, you can simply ignore this file. However, it will come in handy if something goes wrong – we’ll touch on how to import your database by typing the appropriate command later.
Step 2: Find and Replace Your Old Domain Name
Before proceeding, ensure that search-replace is active on your server, especially if you’ve followed one of our older guides on the WP-CLI. You’ll need to check the wp-cli.yml file to ensure search-replace is not under the disabled commands list. If it is, simply remove it and save the settings file.
Now, it’s time to search and replace all old instances of your domain. The search-replace command follows a formula of wp search-replace ‘old text string’ ‘new text string’. In the real-world, it’ll look more like this:
wp search-replace 'http://olddomain.com' 'http://newdomain.com'
Of course, be sure to replace the old and new domain examples with your own. We recommend doing a dry run first to make sure the results are as expected. This means the command will detect all of the old strings and report back, but not actually replace them. You can do this by adding the —dry-run flag to your command:
wp search-replace 'http://olddomain.com' 'http://newdomain.com' --dry-run
If everything looks good, simply remove the —dry-run flag and run your command. After this, you should be good to go!
Step 3: Test Everything is Working
As simple as this process has been, changing domain names can introduce some weird quirks on a misconfigured site. At this point, make sure you can still access your website in a browser, and visit the different pages to ensure that all references to the old domain have been properly updated.
One strength of the WP-CLI is that, even if your site goes down in the browser due to a PHP-related or redirect conflict, you can always access it from the command line. This gives you the chance to make small tweaks as necessary to regain normal access.
In the worst case scenario, if something goes wrong and you can’t seem to fix it, simply reset your site to the backup you made at the beginning by typing:
wp db import
Using this command will completely override any changes you made after exporting the database. Of course, if you’re happy with your tweaks, it’s best to steer clear of it.
As you can see, the WP-CLI makes changing domain names an unbelievably simple process. Once it’s configured on your server, many previously complex tasks can be handled with a few choice commands. It may take some adjusting to forgo a graphical user interface, but the power benefit you’ll gain will likely redress the balance.
In this post, we’ve shown you shown you how to change your domain name within your site’s content in a matter of minutes. You can use the export, search-replace, and import commands to completely manage this switch in seconds, with very little risk and no extraneous front-end plugins.
Do you have any questions about how to use the WP-CLI search-replace command to change domains? Let us know in the comments section below!
Image Credits: Eric Bailey