Leveraging WP-CLI Aliases in Your WordPress Development Workflow

Not to be confused with the hit TV series starring Jennifer Garner, alias support was added to WP-CLI from an update in July, 2016.

If you aren’t familiar, WP-CLI is a tool for interacting with WordPress via the command line. It allows you to perform many admin actions such as activating plugins or users and making updates. It also allows you to carry out tasks on your WordPress database that can’t be natively performed in the admin, including the ability to import/export databases, or to conduct a search & replace on your database (useful if you need to change site URLs based on environment).

If you’re already making use of WP-CLI, you may have noticed the addition of aliases in the 0.24.0 update.

WP-CLI aliases allow you to “talk” to your install. Think of it as your shortcut to Narnia. Note this is primarily useful if you are working with an install on a remote server or on a development VM (such as Trellis, VVV, Homestead) where you would normally need to SSH in to perform tasks. It’s fairly low maintenance; you just need WP-CLI to be installed on any remote server for which the alias will apply.

Setting up aliases

You can set up an alias for each of your environments in a wp-cli.yml file. If you’re using a Bedrock setup, wp-cli.yml already resides in your site repo. If you aren’t using Bedrock, you’ll need to create a file named wp-cli.yml in the root of your WordPress directory.

From here, you can define an alias with the title of your choice preceded by the @ symbol. @dev and @prod would be pretty standard and usable amongst a team. But if you’re working on your own, feel free to call it @unicorntaxidermy if it suits you. You’ll need to configure the SSH path with a user, a host and the path to the WordPress directory.

This follows the format of:

  ssh: user@host/path/to/WordPress

In a Trellis + Bedrock setup, an alias would look something like:

  ssh: admin@example.com/srv/www/example.com/current

The development alias for this site would be:

  ssh: vagrant@example.test/srv/www/example.com/current

For a VVV-based development install:

  ssh: vagrant@local.wordpress.test/srv/www/wordpress-default

Vagrant is a little fancy, so it makes you work a little harder for the good stuff. In a Vagrant instance you can’t easily just ssh in; you’d typically run vagrant ssh. We need to be able to access Vagrant without running vagrant ssh. To do so, mosey on over to the directory where your Vagrantfile exists in your terminal and run:

$ vagrant ssh-config --host example.test >> ~/.ssh/config

This will output valid configuration for an SSH config file to SSH into the running Vagrant machine from ssh directly (instead of using vagrant ssh).
— via Vagrant SSH config docs

Alright, what’s it doing?

Under the hood, WP-CLI proxies commands to the ssh executable, which then passes them to WP-CLI installed on the remote machine

Rad, right? Not sure? Just trust me.

Now that you’re in, you can play around. You can activate a plugin on production while saving yourself the hassle of ssh’ing into machines and working your way to the WordPress directory in order to get shit done.

$ wp @production plugin activate soil

Not impressed? Well, hold onto your toaster waffle, there’s more.

Cool shit you can do with WP-CLI aliases

I’m using Trellis and Bedrock for my site builds these days. Trellis is useful for maintaining parity between your development/staging and production environments. It provisions your local Vagrant box and your remote server with the same configurations. For example, you’ll be running the same versions of Nginx, PHP, and more across the board, which can’t be guaranteed without manual configuration in other setups.

Database parity can still be a prick in your pickle, particularly if you’re working in team setting. The general rule of thumb is that database changes should be made on a remote server and pulled down for local development. With aliases, you can pretty effortlessly export the database from production with:

$ wp @production db export - > sql-dump-production.sql

But that wouldn’t quite suffice. I’ve taken to putting a pretty lazy sync script in the root of my WordPress directory (same as the wp-cli.yml file) to handle the necessary steps for getting a database from production to development:

# sync-prod.sh
read -r -p "Do you solemnly swear that you have had fewer than 2 alcoholic beverages in the last hour and that you would really like to reset your development database and pull the latest from production? [y/N] " response

if [[ "$response" =~ ^([yY][eE][sS]|[yY])$ ]]; then
    wp @development db reset --yes &&
    wp @production db export - > sql-dump-production.sql &&
    wp @development db import sql-dump-production.sql &&
    wp @development search-replace https://example.com https://example.test

I don’t pretend to be an expert at writing scripts, but this seems to get the job done. So instead of logging in, navigating through the vast cavern of files and code, and trying to run all these commands without accidentally running rm -rf anywhere, I just run sync-prod.sh from my WordPress directory and eat a couple of gummy bears while magic ensues. If you prefer to do push-ups instead, by all means, do some push-ups. I’m not telling you how to live your life.

Using WP-CLI aliases

What I am telling you is that WP-CLI aliases can make your life a little easier, and are very handy with the already great Trellis and Bedrock vibe. Also ducks are pretty cool.

Read the discussion on Roots Discourse

Ready to checkout?