Installing and Configuring WP-CLI on macOS

I

WP-CLI is the command-line interface for WordPress. It allows you to manage your WordPress site from the command line without using a web browser. I currently use WP-CLI to temporarily disable the WordPress Google Authenticator plugin, create and configure a version of this site to run in a local AMP environment on my Mac and periodically change the posts that appear in the slider on this site’s home page.

 

 

Installing WP-CLI

There are several ways of installing WP-CLI. I chose the Homebrew method as Homebrew is already installed on my Mac. In Terminal or similar terminal emulator type:

Dummy Content
brew install wp-cli

 

 

The Homebrew method creates the following directory structure:

/usr/local/bin/wp -> /usr/local/Cellar/wp-cli/2.2.0/bin/wp
/usr/local/Cellar/wp-cli
/usr/local/Cellar/wp-cli/2.2.0
/usr/local/Cellar/wp-cli/2.2.0/.brew
/usr/local/Cellar/wp-cli/2.2.0/.brew/wp-cli.rb
/usr/local/Cellar/wp-cli/2.2.0/bin
/usr/local/Cellar/wp-cli/2.2.0/bin/wp
/usr/local/Cellar/wp-cli/2.2.0/INSTALL_RECEIPT.json
/usr/local/opt/wp-cli -> /usr/local/Cellar/wp-cli/2.2.0
/usr/local/var/homebrew/linked/wp-cli -> /usr/local/Cellar/wp-cli/2.2.0

 

 

To show information on WP-CLI, in Terminal type:

Dummy Content
wp cli info
OS:	Darwin 18.6.0 Darwin Kernel Version 18.6.0: Thu Apr 25 23:16:27 PDT 2019; root:xnu-4903.261.4~2/RELEASE_X86_64 x86_64
Shell:	/bin/bash
PHP binary:	/usr/bin/php
PHP version:	7.1.23
php.ini used:
WP-CLI root dir:	phar://wp-cli.phar/vendor/wp-cli/wp-cli
WP-CLI vendor dir:	phar://wp-cli.phar/vendor
WP_CLI phar path:	/Users/steve
WP-CLI packages dir:
WP-CLI global config:
WP-CLI project config:
WP-CLI version:	2.2.0

 

 

A WP-CLI Command Example

The basic format for using WP-CLI is wp <command> <sub-command> <options>. For example, to get a site’s url, in Terminal type:

Dummy Content
wp option get siteurl
Error: This does not seem to be a WordPress installation.
Pass --path=`path/to/wordpress` or run `wp core download`.

 

 

However – as can be seen from the output – this throws an error as wp is looking for a non-existent WordPress installation in the current directory. To remedy this we need to supply the path to the WordPress installation to wp. This will most likely be the same as the site’s DocumentRoot as defined in the Apache configuration files.

To get the url for a site running in a local AMP environment, in Terminal type:

Dummy Content
wp option get siteurl --path=/local/path/to/wordpress/install
http://local.tech-otaku

 

 

When getting a url for a remote site we need to pass SSH login details in the form of name, address and port to wp along with the remote path to the WordPress installation:

Dummy Content
wp option get siteurl --ssh=ben@12.34.56.789:2222 --path=/remote/path/to/wordpress/install
https://www.tech-otaku.com

 

 

NOTE: When accessing WordPress data on a remote host, WP-CLI must also be installed on that remote host. For a Linux host use the recommended install method.

In the examples above, --ssh and --path are two of WP-CLI’s global parameters. When used on the command line they should be placed at the end of the command string or immediately after wp.

For a complete list of WP-CLI commands see WP-CLI Commands.

 

 

Creating an Alias to a WordPress Installation

Passing global parameters on the command line can prove cumbersome. Fortunately, we can create a one-word alias to each site we want to access and use that alias on the command line instead of passing global parameters. Each alias along with its relevant information is stored in the WP-CLI global configuration file: ~/.wp-cli/config.yml.

On a fresh WP-CLI installation this global configuration file doesn’t exist. You can create and edit it using a text editor or – as I prefer – create it from the command line and then use WP-CLI to create each alias. In Terminal type:

Dummy Content
mkdir ~/.wp-cli && touch ~/.wp-cli/config.yml

 

 

An alternative to creating this global configuration file in your home directory is to create the structure in a directory of a file sharing service like iCloud Drive or Dropbox, then create a symbolic link to the directory containing the configuration file in your home directory. This way you’re able to share a single global configuration with more than one Mac.

In this instance I name the directory .wp-cli_shared and the symbolic link .wp-cli.

To create the global configuration file in iCloud Drive, in Terminal type:

Dummy Content
mkdir ~/Library/Mobile\ Documents/com~apple~CloudDocs/.wp-cli_shared && touch ~/Library/Mobile\ Documents/com~apple~CloudDocs/.wp-cli_shared/config.yml

 

 

To create the the symbolic link in your home drectory, in Terminal type:

Dummy Content
ln -s ~/Library/Mobile\ Documents/com~apple~CloudDocs/.wp-cli_shared .wp-cli

 

 

Having created the global configuration file, we can now create each alias. To create an alias named @local for a local WordPress installation, in Terminal type:

Dummy Content
wp cli alias add @local --set-path=/local/path/to/wordpress/install --set-user=emily

 

 

To create an alias named @production for a remote WordPress installation, in Terminal type:

Dummy Content
wp cli alias add @production --ssh=ben@12.34.56.789:2222 --path=/remote/path/to/wordpress/install --set-user=chikako

 

 

To view the contents of the global configuration file, in Terminal type:

Dummy Content
cat ~/.wp-cli/config.yml
---
@local:
  path: /local/path/to/wordpress/install
  user: emily
@production:
  ssh: ben@12.34.56.789:2222
  path: /remote/path/to/wordpress/install
  user: chikako

 

 

To get either the local or remote site’s url I can now use the appropriate alias:

Dummy Content
wp @local option get siteurl
http://local.tech-otaku

 

 

Dummy Content
wp @production option get siteurl
https://www.tech-otaku.com

 

 

NOTE: When using an alias on the command line it can only be placed immediately after wp.

About the author

A native Brit exiled in Japan, Steve spends too much of his time struggling with the Japanese language, dreaming of fish & chips and writing the occasional blog post he hopes others will find helpful.

Add comment

Steve

Recent Comments

Recent Posts