What is WP-CLI and how to use it?

WP-CLI is the official command-line interface for WordPress. It lets you manage almost every part of a WordPress site from a terminal, including installing plugins, updating core, creating users, exporting the database, and running search-and-replace, without opening the admin dashboard. Tasks that take several minutes of clicking can often be done with a single command in seconds.

If you manage more than one site, work with a development team, or simply want a faster workflow, WP-CLI is worth learning. In this article you will learn what WP-CLI is, how to install it, the commands you will use most often, and how to combine them into scripts that save you real time.

What Is WP-CLI?

WP-CLI (WordPress Command Line Interface) is a free, open-source tool maintained as an official WordPress project. It loads your WordPress installation in the background and runs commands directly against it, using the same core functions WordPress uses internally.

Every command starts with wp, followed by a command and usually a subcommand:

wp plugin list
wp core update
wp user create editor1 editor@example.com --role=editor

Because WP-CLI uses WordPress's own APIs, actions such as activating a plugin trigger the same hooks as clicking Activate in the dashboard.

Why Use WP-CLI?

• Speed: Update every plugin on a site with one command instead of clicking through screens.
• Automation: Put commands in shell scripts or cron jobs to handle routine maintenance.
• Recovery: Deactivate a broken plugin or reset a password even when the dashboard is inaccessible.
• Bulk operations: Change hundreds of posts, users, or options at once.
• Safe database changes: Its search-replace command handles serialized data correctly, which manual SQL does not.
• Developer workflows: Scaffold plugins and blocks, generate translation files, and run custom commands.

Requirements

WP-CLI needs:

• A Unix-like environment (Linux, macOS, or Windows via WSL). Native Windows works with some limitations.
• PHP 5.6 or later, though you should be running a current PHP 8.x version anyway for WordPress.
• WordPress 3.7 or later.
• Shell (SSH) access to your server if you want to use it on a live site.

Many managed WordPress hosts, including Kinsta, WP Engine, SiteGround, and Cloudways, have WP-CLI preinstalled. Local development tools like Local, DDEV, and wp-env also include it. Try running wp --info before installing it yourself.

How to Install WP-CLI

On Linux or macOS, the standard installation takes three commands.

• Download the Phar file:

curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar

• Check that it works:

php wp-cli.phar --info

• Make it executable and move it into your PATH:

chmod +x wp-cli.phar
sudo mv wp-cli.phar /usr/local/bin/wp

Now confirm the installation:

wp --info

On macOS you can also install it with Homebrew:

brew install wp-cli

Updating WP-CLI

If you installed the Phar file, WP-CLI can update itself:

wp cli update

Running Your First Commands

WP-CLI needs to know which WordPress site to act on. The simplest way is to cd into the WordPress root folder (the one containing wp-config.php) before running commands:

cd /var/www/example.com/public_html
wp option get siteurl

Alternatively, pass the path explicitly:

wp --path=/var/www/example.com/public_html plugin list

To see help for any command, use wp help:

wp help plugin
wp help plugin install

Managing WordPress Core

Download and Install WordPress

You can set up a brand new site entirely from the terminal:

wp core download
wp config create --dbname=wp_example --dbuser=wp_user --dbpass='strong-password' --dbhost=localhost
wp db create
wp core install --url=https://example.com --title="My Site" --admin_user=sajjad --admin_email=admin@example.com --prompt=admin_password

The --prompt=admin_password flag asks for the password interactively so it does not end up in your shell history.

Check and Update Core

wp core version
wp core check-update
wp core update
wp core update-db

wp core update-db runs any database upgrades that a new version requires, which is what the "Database Update Required" screen does in the browser.

Verify Core Files

wp core verify-checksums

This compares your core files against the official checksums from WordPress.org. It is a quick way to detect modified or injected files after a suspected hack.

Managing Plugins

Plugin management is where many people first fall in love with WP-CLI.

# List installed plugins with status and version
wp plugin list

# Install and activate a plugin from WordPress.org
wp plugin install query-monitor --activate

# Install a specific version
wp plugin install woocommerce --version=9.0.0

# Activate, deactivate, or delete
wp plugin activate classic-editor
wp plugin deactivate classic-editor
wp plugin delete classic-editor

# Update one plugin or all of them
wp plugin update wordfence
wp plugin update --all

# Preview available updates without applying them
wp plugin update --all --dry-run

Recovering from a Broken Plugin

If a plugin causes a fatal error and locks you out of the dashboard, you can disable it from the terminal:

wp plugin deactivate problem-plugin --skip-plugins --skip-themes

The --skip-plugins and --skip-themes flags stop WP-CLI from loading plugins and themes, so the broken code never runs. To deactivate everything at once:

wp plugin deactivate --all --skip-plugins --skip-themes

Managing Themes

wp theme list
wp theme install twentytwentyfive --activate
wp theme update --all
wp theme delete twentytwentythree

Managing Users

# List users
wp user list --fields=ID,user_login,user_email,roles

# Create a user
wp user create jane jane@example.com --role=editor

# Change a role
wp user set-role jane author

# Reset a password
wp user update sajjad --user_pass='new-strong-password'

# Delete a user and reassign their content to user ID 1
wp user delete jane --reassign=1

As with core install, avoid putting real passwords directly on the command line on shared servers, since they can appear in shell history. wp user reset-password sajjad sends a password reset email instead.

Managing Posts and Content

# List published posts
wp post list --post_type=post --post_status=publish --fields=ID,post_title,post_date

# Create a post
wp post create --post_title="Hello from WP-CLI" --post_status=draft

# Update a post
wp post update 42 --post_status=publish

# Delete all posts in the trash
wp post delete $(wp post list --post_status=trash --format=ids) --force

# Generate 20 dummy posts for testing
wp post generate --count=20

The --format=ids output is extremely handy for feeding one command's results into another.

Working with the Database

WP-CLI uses the credentials in your wp-config.php, so you never have to type them.

# Export the database to a file
wp db export backup-$(date +%F).sql

# Import a database file
wp db import backup.sql

# Open a MySQL shell
wp db cli

# Run a query
wp db query "SELECT ID, post_title FROM wp_posts WHERE post_status = 'draft' LIMIT 5;"

# Check database size
wp db size --tables

# Optimize tables
wp db optimize

A database export is only one part of a full backup. Your files, especially wp-content/uploads, need backing up too.

Search and Replace

wp search-replace is one of WP-CLI's most valuable commands. It updates URLs or text across the whole database and correctly handles PHP serialized data, which breaks if you use a plain SQL REPLACE.

A typical use is changing domains after moving a site:

# Always preview first
wp search-replace 'https://old-domain.com' 'https://new-domain.com' --dry-run

# Run it for real
wp search-replace 'https://old-domain.com' 'https://new-domain.com' --all-tables --precise

You can also export a copy of the database with replacements applied, without changing the live database:

wp search-replace 'https://example.com' 'https://example.test' --export=local.sql

Take a database export before any search-replace on production. It is easy to reverse with a backup and very hard without one.

Managing Options, Cache, and Cron

# Read and change options
wp option get blogname
wp option update blogname "My New Site Name"
wp option update blog_public 0

# Flush the object cache
wp cache flush

# Delete expired or all transients
wp transient delete --expired
wp transient delete --all

# Flush rewrite rules (useful after changing permalink code)
wp rewrite flush

# View and run scheduled cron events
wp cron event list
wp cron event run --due-now

Managing Multisite Networks

WP-CLI works with multisite too. Use --url to target a specific site, or loop through all of them:

wp site list --field=url

wp --url=https://example.com/shop plugin activate woocommerce

for url in $(wp site list --field=url); do
  wp --url="$url" cache flush
done

Managing Remote Sites with Aliases

You can run WP-CLI on remote servers from your own computer using SSH. Create a wp-cli.yml file in your project or ~/.wp-cli/config.yml for global settings:

@staging:
  ssh: deploy@staging.example.com/var/www/staging/public_html
@production:
  ssh: deploy@example.com/var/www/example.com/public_html

Then prefix commands with the alias:

wp @staging plugin list
wp @production core version

This is a great way to check or maintain multiple sites without logging in to each one.

Automating Tasks with Shell Scripts

Because every command is scriptable, you can combine them into a maintenance routine. Here is a simple update script that exports the database first:

#!/usr/bin/env bash
set -euo pipefail

SITE_PATH="/var/www/example.com/public_html"
BACKUP_DIR="/home/deploy/backups"

cd "$SITE_PATH"

mkdir -p "$BACKUP_DIR"
wp db export "$BACKUP_DIR/db-$(date +%F-%H%M).sql"

wp core update
wp core update-db
wp plugin update --all
wp theme update --all

wp cache flush
wp core verify-checksums

echo "Updates complete."

Test scripts like this on a staging site first. Automatic updates are convenient, but you still want to check the site afterward.

Developer Commands

WP-CLI also includes tools for building things:

# Scaffold a child theme
wp scaffold child-theme my-child --parent_theme=twentytwentyfive

# Scaffold a plugin with test files
wp scaffold plugin my-plugin

# Generate a translation template
wp i18n make-pot wp-content/plugins/my-plugin wp-content/plugins/my-plugin/languages/my-plugin.pot

# Open an interactive PHP shell with WordPress loaded
wp shell

# Evaluate a line of PHP
wp eval 'echo get_bloginfo( "version" );'

For new blocks, the official @wordpress/create-block npm package has replaced the older block scaffold command.

Creating a Custom WP-CLI Command

You can register your own commands in a plugin. This example counts posts per post status:

<?php
if ( defined( 'WP_CLI' ) && WP_CLI ) {

/**
 * Show post counts by status.
 *
 * ## OPTIONS
 *
 * [--post_type=<post_type>]
 * : The post type to count. Default: post.
 *
 * ## EXAMPLES
 *
 *     wp sajjad post-counts --post_type=page
 */
function sajjad_cli_post_counts( $args, $assoc_args ) {
$post_type = isset( $assoc_args['post_type'] ) ? sanitize_key( $assoc_args['post_type'] ) : 'post';

if ( ! post_type_exists( $post_type ) ) {
WP_CLI::error( "Post type '{$post_type}' does not exist." );
}

$counts = (array) wp_count_posts( $post_type );
$rows   = array();

foreach ( $counts as $status => $count ) {
$rows[] = array(
'status' => $status,
'count'  => $count,
);
}

WP_CLI\Utils\format_items( 'table', $rows, array( 'status', 'count' ) );
}

WP_CLI::add_command( 'sajjad post-counts', 'sajjad_cli_post_counts' );
}

Run it with wp sajjad post-counts. The doc comment automatically becomes the command's help text.

Useful Global Flags

These flags work with almost any command:

• --path=<path>: Point to a WordPress install.
• --url=<url>: Target a specific site on multisite.
• --user=<id|login>: Run the command as a specific user.
• --skip-plugins and --skip-themes: Load WordPress without plugins or themes.
• --format=<table|json|csv|ids|count>: Change output format.
• --quiet: Suppress informational messages.
• --debug: Show debug output, helpful when a command misbehaves.

---

FAQ: WP-CLI

---

Conclusion

WP-CLI turns routine WordPress administration into fast, repeatable commands. Once installed, it lets you update core and plugins, manage users and content, back up and migrate databases, and recover from broken plugins, all from the terminal and often in a fraction of the time the dashboard would take.

Start with a few everyday commands like wp plugin list, wp core update, and wp db export. As you get comfortable, try wp search-replace for migrations, aliases for remote sites, and small shell scripts for maintenance. Before long, you will wonder how you ever managed WordPress without it.