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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
wp @local option get siteurl
http://local.tech-otaku
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.
