- Getting Started
- Custom Commands
- Resource Restrictions
- Audit Log
- Advanced usage
- Common errors
Most things you can do with WordPress core have an equivalent command in WP-CLI:
- Onboarding and offboarding users:
wp user create,
wp user delete
- List scheduled WP Cron tasks (asynchronous tasks in WordPress):
wp cron schedule list
- List all categories in your site:
wp term list category
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.
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 (
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.
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
-y) flag before the
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.
Note: 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.
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" >> commands.sh ' $ chmod +x commands.sh $ ./commands.sh
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
“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.