WP-CLI

Overview #

WP-CLI is a powerful and extensible way to interact with WordPress from the command line. WP-CLI is supported on VIP via our VIP-CLI tool.

Most things you can do with WordPress core have an equivalent command in WP-CLI:

↑ Top ↑

Getting Started #

To get started, first install the latest version of VIP-CLI:

npm i -g @automattic/vip

Interactive Shell #

The easiest way to use WP-CLI is to use the interactive shell mode provided by VIP-CLI. This feature provides a terminal-like interface into your WordPress site:

vip @my-site -- wp

my-site.production:~$ wp option get home
https://example.com
my-site.production:~$ wp cache delete my-cache-key my-cache-group
Success: Object deleted.
my-site.production:~$ 

Using the interactive shell mode is a convenient way to run multiple commands on the same environment and behaves much like a standard terminal or SSH session would. While it does look and act like a standard terminal, it does not currently support bash operators or commands (such as xargs, variable substitution, etc). You can use those in the Direct Command approach below if required.

↑ Top ↑

Direct Commands #

WP-CLI commands can also be run directly just like any normal command:

vip @my-site.production -- wp option get home
vip @my-site.staging -- wp post list --posts_per_page=100 --url=example.com/fr
vip @my-site.develop -- wp cache delete some-key

Running commands directly allows the output to be redirected and piped for creating powerful workflows and tools:

vip @my-site.develop -- wp user list --format=json | jq
vip @my-site.staging -- wp term list category --format=csv &> category.csv

Note: In the examples above, the double dash (--) before wp separates arguments of the vip command from those of the wp command. You should always include them to avoid unexpected issues due to parameter conflicts.

↑ Top ↑

Custom Commands #

While the core WP-CLI commands offer a multitude of ways to interact with a WordPress site, there are times when custom functionality is required. A good use case is transforming large amounts of site data.

You can create a custom command to help accomplish this. We also have a guide that outlines best practices when working with custom commands. Finally, please be mindful of the “Resource Restrictions” noted below.

↑ Top ↑

Resource Restrictions #

In order to maintain the integrity of your sites and various services it requires, commands that utilize excessive CPU, memory,  or I/O may be terminated. See the WP-CLI Best Practices section for ways to monitor for and avoid this scenario.

There is also a limitation on the number of commands that can be run concurrently. Production environments are limited to a maximum of four concurrent commands and non-production environments are limited to two.

↑ Top ↑

Audit Log #

For greater visibility into how WP-CLI is being used, the VIP Dashboard includes a log of all WP-CLI commands run on your applications and environments. To view it, log in to the Dashboard and select “WP-CLI” when from the sidebar of an application.

The filter, top right, will help you to find completed, running, cancelled, or errorred commands.

↑ Top ↑

Advanced usage #

↑ Top ↑

Skipping command confirmation #

When trying to run a command on a production environment, we prompt you to confirm your actions. If you want to skip this confirmation step (e.g. using the command as part of a script), you can bypass it by passing the --yes (or -y) flag before the wp command.

vip @my-site.develop --yes -- wp option get siteurl

↑ Top ↑

Cancelling a command #

To cancel a command, you have two options:

  • From the VIP CLI: You can hit CTRL + C.
  • From the Dashboard: From the WP-CLI Log, click on the red cross button to cancel the command.

Note: In both cases, only the user who started a command can cancel it.

↑ Top ↑

Writing command output to a file #

All WP-CLI commands are run on a remote web server. Any file operations during a command will occur on the remote server as well with no way to retrieve the file.

If you do need to write to a file, we suggest writing the output to the console first (using helpers like WP_CLI::line() and WP_CLI::log()) and then redirecting it to your desired file:

vip @my-site.develop -- wp option get home > output.txt

↑ Top ↑

Nested Commands #

When running more complex WP CLI commands such as loops or nested commands, you need to ensure that each reference to wp uses the remote execution pattern:

This will not work:

$ vip @app.env -- wp post delete $(wp post list --post_type='page' --format=ids)
-bash: xyz: command not found

This is actually two commands, (1) a post list that retrieves a list of ids that is then (2) passed into a delete command. This will not work as intended because the command inside the $() is referencing the local version of wp (i.e. on your computer).

At best, a message will appear indicating  wp doesn’t exist locally. At worst, if run from a local WordPress site directory, it will get post_ids from the local WordPress site that will then be passed to the delete command to be run against the remote site.

This will work:

$ vip @app.env -- wp post delete $(vip @app.env -- wp post list --post_type='page' --format=ids)

↑ Top ↑

Looping #

Due to the way that shell utilities handle stdin, commands like xargs may not always work with WP-CLI as expected. In these cases it might be easier to write the commands to a file and then execute that file.

This will not work:

$ vip @app.env -- wp post list --fields=ID --format=csv --posts_per_page=5 | xargs -I % 'vip @app.env -- wp post update % --post_category=NewCategory ' 

This will work:

$ vip @app.env -- wp post list --fields=ID --format=csv --posts_per_page=5 | xargs -I % sh -c 'echo "vip @app.env -- wp post update % --post_category=NewCategory" >> commands.sh ' 
$ chmod +x commands.sh
$ ./commands.sh

 

↑ Top ↑

Common errors #

↑ Top ↑

“The command is not permitted at this time” #

In certain cases, we block some core and other commands for security, performance, and other reasons. To see a full list of the commands which are available to you, you can use wp help.

↑ Top ↑

“Command cancelled” #

This error is received when the command is cancelled either by you or automatically by our systems for exceeding resource limits.

↑ Top ↑

“Connection lost, retrying…” #

If your internet connection drops while running a command, we’ll keep trying to reconnect in the background. During this process, you may get a “Connection lost, retrying…” message logged to your console. If we can’t make a connection in the span of 1 minute, we’ll stop trying and you’ll be disconnected from the command.

↑ Top ↑

“Maximum running command count has been reached for the site” #

This indicates that there aren’t enough available resources to run the commands or you’ve currently exceeded the maximum number of concurrent commands that can be run. You can use the dashboard to view (and cancel) running commands.

↑ Top ↑

“Error during Handshake” #

This typically is due to cases where stdin input is being manipulated through a shell utility such as xargs. See the “Looping” section under “Advanced Usage” for more details.

Ready to get started?

Drop us a note.

No matter where you are in the planning process, we’re happy to help, and we’re actual humans here on the other side of the form. 👋 We’re here to discuss your challenges and plans, evaluate your existing resources or a potential partner, or even make some initial recommendations. And, of course, we’re here to help any time you’re in the market for some robust WordPress awesomeness.