Just about a month ago as I was preparing to board my flight to WordCamp US I came across a tweet from Alain Schlesser about using aliases in WP-CLI.
Unfortunately the knowledge of WP-CLI aliases came too late for me. Our team had already installed Gutenberg Ramp across all of the client sites we host and maintain. And I was boarding a flight to Nashville. Not the best time for digging in.
What Are Aliases
Aliases can be used in the WP-CLI to allow you to remotely run commands on WordPress installs. Say, for example, if you want to remotely install and activate a plugin.
Then to kick things up a notch you can set up alias groups that allow you to run a single command across multiple aliases. Perhaps if you were to need to remotely install and activate that plugin across 60+ client sites.
Or maybe your team has a penchant for not disabling discourage search engines1 and you want to confirm it’s off for all live sites.
Setting up your first alias
First, if you haven’t gotten the WP-CLI installed yet you’re going to need to do that. You can install it locally on your system and run commands from there. Back when I initially setup the WP-CLI while working on MAMP I followed Tom McFarlin’s guide. Just skip the MAMP bits if you’ve moved on, but it’s a good explanation of what’s going on.
Wherever you have the WP-CLI installed you’ll need to track down your
config.yml file in your
.wp-cli directory. Note the
. before that directory making it a hidden directory.
Let’s take a look at a sample alias connecting to a site via SSH over port 2222.
Note: You’ll need your SSH key added to the server for this to work as you’ll want to connect without the need for a password.
# Aliases to other WordPress installs (e.g. `wp @staging rewrite flush`)
# An alias can include 'user', 'url', 'path', 'ssh', or 'http'
We first give our alias a name of
@siteone. Then we set the SSH command in the format of
[email protected]. Lastly we set the path to the WordPress install on the server.
And then we repeat for
@sitetwo with one different. We’re also passing a port number to the end of our SSH command as
This gives us aliases we can access with commands like
wp @siteone plugin install easy-footnotes or
wp @sitetwo flush cache.
Creating an Alias Group
Single aliases are good for running a command on a single install. But things get really powerful once you get alias groups setup.
Say we have sites spread out across different hosts that we mainatin. sLet’s take a look at that.
With this we’re creating an alias group named
@wpengine and one named
@spinupwp. We then indicate which aliases are part of each group with
Now we can run commands like
wp @wpengine plugin list to see all the plugins on our WP Engine sites.
Help I Forgot My Alias
Rather than track down and open our
config.yml every time you forget an alias you can run
wp cli alias. This will list all of your aliases and groups like so:
@all: Run command against every registered alias.
You may notice the addition of
@all at the top of that list and thought, “Wait a second. I didn’t define that.” And that’s correct. You don’t need to. Once you have aliases setup you can run commands like
wp @all option get blog_public to see if you have Discourage Search Engines disabled on all sites.
WP-CLI aliases can be used to run commands remotely across multiple WordPress installs. This gives you great power to automate your WordPress workflows. Especially tedious tasks like checking settings, running updates, and more.