Skip to content

How-to Guides

Technical References

Tools for Site Management /


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 of the things you can do with WordPress core have an equivalent command in WP-CLI:

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
my-site.production:~$ wp cache delete my-cache-key my-cache-group
Success: Object deleted.

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 (e.g. xargs, variable substitution, etc). You can use those in the Direct Command approach below if required.

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
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


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.

Disallowed commands

There are a selection of built-in and VIP mu-plugin commands (and/or subcommands) that are blocked for VIP clients to ensure the safety of the site:

admin: *

cache: flush

cli: alias, cache, check-update, cmd-dump, completions, has-command, info, param-dump, update

comment: generate

config: *

core: check-update, download, install, is-installed, multisite-convert, multisite-install, update, update-db, verify-checksums

cron-control: *

cron-control-fixer: *

db: *

dist-archive: *

eval: *

eval-file: *

find: *

i18n: *

import: *

jetpack: *

jetpack-start: *

jetpack-start-provision: *

media: import, regenerate

package: *

plugin: delete, install, update


  • core: install, uninstall, update
  • plugin: install, uninstall, update
  • theme: install, uninstall, update
  • post: edit, generate

profile: *

scaffold: *

search-replace: *

server: *

shell: *

site: empty

term: generate

theme: delete, install, update

user: generate, import-csv

vaultpress: *

vipsupport: *

vip: cache, files, fixers, migration, plugin, two-factor, utf8mb4

If you need assistance with one of these commands, please open a support ticket and we will be happy to assist.

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.

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.

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.

Advanced usage

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

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.


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

Referencing a file input

If you have uploaded a file to your GitHub repository that you’d like to use in a CLI command, you can reference the path of the file via /var/www/wp-content/<path to file>.

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

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)


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" >> '
$ chmod +x
$ ./

Common errors

“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.

“Command cancelled”

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

“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.

“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.

“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.

Last updated: November 23, 2020