WP-CLI: The Commands Worth Knowing

WP-CLI is WordPress without the browser. It loads the same code the dashboard loads and does the same things from a terminal — which makes routine work fast, bulk work possible, and recovery work available on a site whose admin will not load at all.

That last case is the one that converts people. A fatal error from a plugin update locks you out of the dashboard; WP-CLI deactivates the plugin in one line.

Getting it

Most managed hosts ship it. Check first:

wp --info

If it is missing and you have SSH, install it into your user directory:

curl -O https://raw.githubusercontent.com/wp-cli/wp-cli/v2.11.0/utils/wp-cli.phar
php wp-cli.phar --info
chmod +x wp-cli.phar && mv wp-cli.phar ~/bin/wp

Run everything from the WordPress root — the directory containing wp-config.php — or pass --path=/var/www/site. If commands fail as root, add --allow-root, understanding that you are then writing files as root.

Reading the site

Start here, because these cannot break anything:

wp core version                      # WordPress version
wp core check-update                 # is an update available
wp plugin list --status=active       # what is actually running
wp theme list
wp user list --role=administrator    # who has full access
wp option get siteurl
wp db size --tables --human-readable # what is large

wp plugin list alone answers questions that take five clicks in the dashboard, and wp user list --role=administrator is the first command to run on a site you have inherited or suspect has been compromised.

Plugins and themes

wp plugin update --all --dry-run     # see what would change
wp plugin update --all
wp plugin deactivate akismet
wp plugin deactivate --all           # the recovery hammer
wp plugin activate akismet
wp theme activate twentytwentyfour

wp plugin deactivate --all followed by reactivating one at a time is the fastest possible version of the plugin conflict bisect, and it works when the dashboard does not.

Run updates on a staging copy first — the discipline is the same as in updating plugins safely, only faster.

Users

wp user create editor2 ed@example.com --role=editor
wp user update 5 --user_pass='a-long-unique-passphrase'
wp user list --field=user_login

Resetting a password here avoids the whole email-delivery question, which matters when password reset emails are not sending. Creating an admin user from the command line is also the clean alternative to doing it in phpMyAdmin.

The database

The most powerful commands, and the ones that need a backup first.

wp db export backup-before-change.sql
wp search-replace 'http://example.com' 'https://example.com' --all-tables --dry-run
wp search-replace 'http://example.com' 'https://example.com' --all-tables --report-changed-only
wp db optimize

wp search-replace understands PHP serialisation, which a raw SQL REPLACE does not — that is the entire reason to use it. A plain SQL replace corrupts serialised options silently, and the damage appears weeks later. It is the correct tool for fixing mixed content and for rewriting URLs during a migration.

Always run --dry-run first, and always export before the live run.

Rewrites, cron and transients

wp rewrite flush --hard
wp rewrite list --format=table | head

wp cron event list
wp cron event run --due-now

wp transient delete --expired
wp cache flush

wp rewrite flush is the command-line version of saving the Permalinks screen, and it is the first thing to try for permalinks not working or a custom post type returning 404s.

wp cron event run --due-now is what a real system cron calls after you disable WP-Cron — without it, scheduled posts and renewals stop happening.

Recovering a site that will not load

This is the sequence that earns WP-CLI its place. On a white screen or a fatal error:

wp plugin list --status=active          # what was running
wp plugin deactivate --all              # get the site back
wp theme activate twentytwentyfour      # rule out the theme
wp config set WP_DEBUG true --raw       # turn on error reporting
wp config set WP_DEBUG_LOG true --raw

Then reactivate plugins one at a time until the error returns. The full diagnostic ladder is in how to fix the WordPress white screen, and what these constants do is in how to enable debug mode and wp-config.php explained.

Output formats and scripting

Every list command takes --format and --field, which is what makes WP-CLI scriptable:

wp plugin list --field=name --status=active > active-plugins.txt
wp post list --post_type=page --format=csv --fields=ID,post_title,post_name
wp option get blogname --format=json

--porcelain returns bare IDs, which is what you want when piping one command into another.

Common mistakes

• Running write commands without a backup. There is no undo and no confirmation prompt.
• Skipping --dry-run on search-replace, then discovering it matched more than intended.
• A bare domain as the search string. Include the scheme, or you will rewrite text you meant to keep.
• Running as root by habit, leaving files WordPress cannot write to afterwards.
• Forgetting --all-tables on multisite, so per-site tables are silently skipped — see multisite explained.
• Assuming the host's PHP CLI matches its web PHP. Two different versions produce two different results; check wp --info.

Where it pays off most

Bulk operations the dashboard cannot do at all: updating fifty sites from one script, exporting a content inventory to CSV, rewriting URLs across a whole database, and getting into a site whose admin is a blank page. If you manage more than one WordPress install, the time it saves in the first month is larger than the time it takes to learn.