WP-CLI: The Commands That Make WordPress Administration Bearable

Q: How do I fix a WordPress white screen with WP-CLI?

Run wp plugin deactivate --all to turn everything off, confirm the site loads, then reactivate plugins one at a time until the failure returns. That identifies the culprit in minutes without editing the database or renaming directories over SFTP.

Q: Should I skip the guid column in search-replace?

Yes. The guid is a permanent identifier used by feed readers rather than a URL to fetch. Changing it makes every post look new to RSS subscribers, which can mail your entire list about years-old content. Use --skip-columns=guid.

WP-CLI is the official command-line interface for WordPress. It updates plugins, manages users, runs database operations, and does search-replace across serialised data that a plain SQL UPDATE would corrupt. Two things make it more than a convenience: it works when the dashboard is broken — a white screen from a bad plugin is fixed with one wp plugin deactivate — and it makes WordPress administration scriptable.

The command surface is large. This is the subset that covers most real work, plus the two commands that are genuinely dangerous.

Install and verify
Plugins and themes
Users
Database, and the search-replace that matters
Options, cache, and cron
Scripting and output formats
When there is no shell
How this fits the rest of the stack
FAQ

Install and verify

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
sudo mv wp-cli.phar /usr/local/bin/wp

wp --info
wp core version

Run commands from the WordPress root, or pass --path=/var/www/html. WP-CLI loads WordPress itself, so it needs to find wp-config.php and can reach the database.

It refuses to run as root by default, since files it creates would be owned by root and then unwritable by the web server. Run as the web user instead:

sudo -u www-data wp plugin list --path=/var/www/html

--allow-root exists and is the wrong habit. Ownership problems introduced this way surface later as plugins that cannot update themselves.

Plugins and themes

wp plugin list
wp plugin list --status=active --field=name
wp plugin list --update=available

wp plugin install wordpress-seo --activate
wp plugin update --all
wp plugin deactivate akismet
wp plugin delete hello

wp theme list
wp theme activate twentytwentyfive

The white-screen recovery is the one to remember. A fatal error from a plugin locks you out of the dashboard, including the plugins page, so you cannot deactivate the plugin through the interface that the plugin broke.

# Turn everything off
wp plugin deactivate --all

# Reactivate one at a time until it breaks again
wp plugin activate woocommerce
wp plugin activate wordpress-seo

Two minutes rather than an afternoon, and no database editing. This alone justifies having WP-CLI installed before you need it.

Users

wp user list
wp user list --role=administrator --field=user_email

wp user create alice [email protected] --role=editor
wp user update 3 --user_pass='new-password'
wp user add-role 3 administrator
wp user delete 5 --reassign=1

# Locked out? Create an admin and log in
wp user create rescue [email protected] --role=administrator --user_pass='temp-password'

The rescue account is the standard recovery for a lost admin password when email is not working — which is common, since a site that cannot send mail also cannot send a reset link.

Delete it afterwards. A temporary admin account that nobody removed is one of the more common findings in a WordPress security review.

Database, and the search-replace that matters

wp db export backup.sql
wp db import backup.sql
wp db size --tables
wp db optimize

# An interactive MySQL session with the site's credentials
wp db cli

wp search-replace is the command that justifies the tool for anyone who migrates sites. WordPress stores serialised PHP arrays in the database, and serialised strings carry their own byte length — so a plain SQL UPDATE that changes a URL leaves every length prefix wrong and silently corrupts widget settings and theme options.

# ALWAYS dry run first
wp search-replace 'http://old.example.com' 'https://new.example.com' --dry-run

# Then for real
wp search-replace 'http://old.example.com' 'https://new.example.com'

# Include all tables, not just WordPress core ones
wp search-replace 'old' 'new' --all-tables

# Skip the columns that should never change
wp search-replace 'old' 'new' --skip-columns=guid

Skip guid. It is a permanent identifier for feed readers, not a URL to follow. Changing it makes every post appear new in RSS readers, which mails your whole subscriber list about years-old content.

Always --dry-run first, and always take wp db export before a real run. Search-replace has no undo.

Options, cache, and cron

wp option get siteurl
wp option update blogname 'New Site Name'
wp option list --search='*_transient_*' --format=count

wp cache flush
wp transient delete --expired

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

WordPress cron is triggered by page visits, so a low-traffic site runs scheduled tasks late or not at all. The fix is to disable the visitor-triggered version and run it on a real schedule:

<?php
// wp-config.php
define('DISABLE_WP_CRON', true);

# Then a real scheduled job every five minutes
*/5 * * * * cd /var/www/html && wp cron event run --due-now --quiet

This also removes cron work from the request path, so visitors are not the ones paying for your scheduled tasks.

Scripting and output formats

# Machine-readable output
wp plugin list --format=json
wp plugin list --format=csv --fields=name,status,version
wp post list --format=ids

# Compose commands
wp post delete $(wp post list --post_type=revision --format=ids) --force

# Run arbitrary PHP with WordPress loaded
wp eval 'echo get_option("siteurl");'
wp eval-file cleanup.php

--format=ids piping into another command is the pattern that makes bulk operations tractable. Deleting thousands of revisions through the dashboard is not realistic; here it is one line.

A useful health-check script:

#!/bin/bash
set -euo pipefail
cd /var/www/html

echo "core:    $(wp core version)"
echo "updates: $(wp plugin list --update=available --format=count) plugins"
echo "db:      $(wp db size --size_format=mb)MB"
echo "admins:  $(wp user list --role=administrator --format=count)"
wp core verify-checksums || echo 'WARNING: modified core files'

wp core verify-checksums compares core files against the official release. Unexpected modifications there are one of the clearest signs of a compromise, and it costs nothing to check regularly.

When there is no shell

Everything above assumes SSH access, which a lot of WordPress hosting does not provide. That is the practical limit on WP-CLI, and it is why so much WordPress administration is still done by clicking.

The gap it leaves is worth naming: without a shell you cannot deactivate a plugin that has broken the dashboard, you cannot export the database, and you cannot run a safe search-replace. The recovery paths all require the interface that is broken.

A dashboard file manager and database browser cover a good part of that gap — editing wp-config.php to enable debug output, renaming a plugin directory to disable it, or exporting a table, without SFTP or phpMyAdmin. That is what WordPress on RunxBuild includes, on a plan ladder starting at $3/month, and it means the white-screen recovery does not depend on having set up SSH access before the incident.

How this fits the rest of the stack

Install WP-CLI before you need it. wp plugin deactivate --all is the white-screen fix, wp user create is the lockout fix, and wp search-replace --dry-run is the only correct way to change URLs across a WordPress database. Skip the guid column, export the database first, and never run as root.

Disable WP-Cron and run it on a real schedule so visitors are not paying for your scheduled tasks. If you are working out what a WordPress site with real administration access costs, the RunxBuild hosting calculator shows the plan, storage, and bandwidth as separate line items.

Useful related references:

FAQ

What is WP-CLI used for?

Managing WordPress from the command line — installing and updating plugins and themes, managing users, importing and exporting the database, running search-replace, and executing arbitrary PHP with WordPress loaded. Its most valuable property is that it works when the dashboard is broken.

How do I fix a WordPress white screen with WP-CLI?

Run wp plugin deactivate --all to turn everything off, confirm the site loads, then reactivate plugins one at a time until the failure returns. That identifies the culprit in minutes without editing the database or renaming directories over SFTP.

Why should I use wp search-replace instead of SQL?

WordPress stores serialised PHP arrays in the database, and serialised strings encode their own byte length. A plain SQL UPDATE changes the text but not the length prefix, corrupting widget and theme settings silently. wp search-replace unserialises, replaces, and reserialises correctly.

Should I skip the guid column in search-replace?

Yes. The guid is a permanent identifier used by feed readers rather than a URL to fetch. Changing it makes every post look new to RSS subscribers, which can mail your entire list about years-old content. Use --skip-columns=guid.

Can I run WP-CLI as root?

You should not. Files created as root are owned by root and become unwritable by the web server, which breaks plugin updates and uploads later. Run as the web server user with sudo -u www-data wp ... instead of using --allow-root.