WP-CLI guide: install it, learn the essential commands and automate WordPress

WP-CLI is the official command-line interface for WordPress. It lets you install WordPress, update core, plugins and themes, export and import the database, run search-and-replace on URLs, trigger cron events and manage users without opening wp-admin. For anyone who maintains more than one site, it is the difference between clicking through dashboards and running a single repeatable script.

Installing it takes a few minutes: download one PHP archive (a Phar file), make it executable and put it on your PATH. Many managed hosts already include it over SSH, and WordPress.com offers WP-CLI on its Business and Commerce plans as of October 2026.

This guide covers installation, the commands you will use every week, how to run them safely against remote sites, and patterns for automating maintenance. Command names and options below come from the official WP-CLI command reference.

Installing WP-CLI

The installation guide recommends the Phar build. On macOS or Linux:

1. Download: curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar
2. Verify (recommended): download wp-cli.phar.asc and the project's public key, then run gpg --verify wp-cli.phar.asc wp-cli.phar. The guide also documents checksum verification.
3. Test it: php wp-cli.phar --info
4. Install it on your PATH: chmod +x wp-cli.phar, then sudo mv wp-cli.phar /usr/local/bin/wp
5. Confirm: wp --info prints the PHP binary, php.ini in use and WP-CLI version.

Alternatives documented in the same guide include Homebrew (brew install wp-cli), Composer (composer global require wp-cli/wp-cli-bundle), Docker images, .deb packages and Windows setup. Update a Phar install with wp cli update; wp cli update --nightly switches to the bleeding-edge build, which the guide describes as "more or less stable enough" for local environments.

WP-CLI's own requirements are modest: the README lists PHP 7.2.24 or later and WordPress 4.9 or later, noting that versions older than the latest WordPress release "may have degraded functionality." Your site itself should be on the current WordPress release, which requires PHP 7.4 or later since WordPress 7.0.

How WP-CLI commands are structured

Every command follows the pattern wp <command> <subcommand> [arguments] [--options]. Run wp help, wp help plugin or wp help plugin install for built-in documentation. A few global parameters work with every command:

• --path=<path>: where WordPress is installed, if you are not in that directory.
• --url=<url>: which site to act on; required to target a specific site in multisite.
• --ssh=<user@host/path>: run the command on a remote server over SSH (or in a Docker container).
• --user=<id|login|email>: run as a specific WordPress user, which matters for capability checks.
• --skip-plugins and --skip-themes: load WordPress without plugins or themes, invaluable when a fatal error locks you out of wp-admin.
• --format=json (on list commands): machine-readable output for scripts.

WP-CLI refuses to run as the root user unless you add --allow-root. Run it as the same system user that owns the WordPress files instead, so files it creates keep the right ownership.

Essential commands by area

Core

wp core verify-checksums compares every core file with the official checksums, which makes it a quick first step when you suspect a hacked site. Our hacked WordPress recovery guide covers what to do next.

Plugins and themes

Database

• wp db export backup.sql: dumps the database with mysqldump, using the credentials in wp-config.php. Add --add-drop-table for a dump that can overwrite an existing database cleanly.
• wp db import backup.sql: restores a dump.
• wp db query "SELECT option_name FROM wp_options WHERE autoload = 'yes' LIMIT 20": runs SQL directly (use with care, and check the table prefix).
• wp db size --tables, wp db optimize, wp db check and wp db repair: housekeeping.
• wp db search "old-domain.com": finds strings across tables without changing anything.

Search and replace

wp search-replace is the safe way to change a domain or path in the database because, as the command reference puts it, it "intelligently handles PHP serialized data, and does not change primary key values." A typical migration sequence:

1. wp db export before-migration.sql
2. wp search-replace 'https://staging.example.com' 'https://example.com' --skip-columns=guid --dry-run
3. Review the report, then run the same command without --dry-run.
4. wp cache flush and wp rewrite flush

Useful options include --export=file.sql (write the transformed data to a file instead of the database), --network (all sites in a multisite), --all-tables-with-prefix (include tables plugins created but did not register), --precise (slower PHP-based replacement) and --regex (much slower; the reference says roughly 15 to 20 times). Skipping the guid column follows the reference's own example. For the SEO side of a domain move, see migrating a website without losing rankings.

Cron

• wp cron event list: shows scheduled events and their next run time.
• wp cron event run --due-now: runs every event that is due.
• wp cron event run my_hook: runs one hook immediately, handy for testing.
• wp cron schedule list: shows available intervals.
• wp cron test: checks that WP-Cron can spawn over HTTP. It reports an error if DISABLE_WP_CRON is set, because WP-Cron is then disabled by design.

WP-Cron normally runs when someone visits the site. On low-traffic sites it can run late; on busy ones it adds work to page requests. The Plugin Handbook describes the alternative: set define( 'DISABLE_WP_CRON', true ); in wp-config.php and run cron from the system scheduler. With WP-CLI, a crontab line such as */5 * * * * cd /var/www/example && wp cron event run --due-now --quiet does the job.

Other everyday commands

• Users: wp user list --role=administrator, wp user create, wp user reset-password jane (resets the password and sends the user an email notification unless you add --skip-email).
• Options: wp option get siteurl, wp option update blogname "New name".
• Caches and rewrites: wp cache flush, wp transient delete --expired, wp rewrite flush.
• Maintenance: wp maintenance-mode activate and deactivate.
• Media: wp media regenerate after changing image sizes.
• Scaffolding: wp scaffold plugin, wp scaffold child-theme and wp scaffold plugin-tests.
• Ad hoc PHP: wp eval 'echo get_option( "home" );' and wp shell for an interactive session.

Working with remote sites: aliases and SSH

You do not need to log in to each server. Define aliases in a wp-cli.yml file in your project (or ~/.wp-cli/config.yml) such as @staging with ssh: deploy@staging.example.com and path: /var/www/example, and @production with its own host and path. Then run wp @staging plugin list or wp @production core verify-checksums from your laptop. WP-CLI must be installed on the remote server for this to work.

Two habits prevent most accidents: keep production as an explicit alias (never the default), and use --dry-run or a database export before any command that writes. Staging copies are covered in more depth in our guide to handling version upgrades for themes and plugins.

Automating maintenance safely

A reasonable weekly maintenance script for a single site looks like this, run as the site owner user:

1. wp db export ~/backups/$(date +%F).sql --add-drop-table
2. wp core check-update and wp plugin list --update=available --format=json, saved to a log
3. wp plugin update --all --minor, then wp theme update --all
4. wp core update --minor, then wp core update-db
5. wp core verify-checksums and wp plugin verify-checksums --all
6. wp cache flush, then an HTTP check of the home page and checkout or contact page

Keep major updates (core majors, plugin major versions, WooCommerce) for a staging run first; the minor-only flags let automation handle low-risk releases. In CI pipelines, combine WP-CLI with wp-env or WordPress Playground to spin up disposable test sites. If you build plugins, WP-CLI is also how you register your own commands with WP_CLI::add_command(), so operations staff can run plugin tasks without custom admin screens.

For a broader process, see our posts on security patching and plugin update best practices and maintaining and updating WordPress.

Newer commands worth knowing

• wp plugin check: added by the official Plugin Check plugin (version 2.1.0, 10,000+ active installs as of October 2026). It runs the WordPress.org directory checks from the command line; the plugin notes that only static checks run by default from WP-CLI.
• wp ability: lists, inspects, validates and runs abilities registered through the Abilities API, for example wp ability list and wp ability run core/get-site-info --user=admin. It is documented in the command reference and included in the current development bundle; if your installed version does not have it, wp cli update --nightly or the wp-cli/ability-command package adds it. Our Abilities API guide explains what abilities are.

Conclusion

WP-CLI turns WordPress administration into commands you can repeat, script and review. Install the Phar, learn the core, plugin, theme, db, search-replace and cron commands, and use aliases to work on remote sites without logging in to each one. Export before you change anything, use --dry-run, and leave major updates to a staging pass. Explore related developer guides in our WordPress hub, including the REST API guide. If you would rather hand routine updates to a team, eSEOspace provides website maintenance services built on these workflows.

Frequently asked questions