11 min. read

WP-CLI: The Complete Guide to Managing WordPress from the Command Line

WP-CLI is the official command-line tool for managing WordPress installations directly from your terminal, without ever opening a browser. If you’ve ever spent an afternoon clicking through the WordPress admin dashboard to update plugins across multiple sites, you already know why this tool exists.

In this guide, you’ll learn everything from installing WP-CLI on Linux, macOS, and Windows to automating complex maintenance tasks with scripts and configuration files. Whether you’re managing a single blog or dozens of client sites, mastering WP-CLI will fundamentally change how you work with WordPress.

What you will learn:

  • How to install and configure WP-CLI across different operating systems
  • Essential commands for managing plugins, themes, users, and content
  • Database operations including exports, imports, and safe search-replace
  • Automation techniques using scripts, aliases, and cron jobs
  • Best practices to avoid common pitfalls when working from the terminal

What is WP-CLI? (Quick Explanation First)

WP-CLI stands for WordPress Command Line Interface—an open-source tool that lets you manage WordPress sites entirely from the terminal. Instead of logging into wp-admin and navigating through menus, you run commands like wp plugin update --all and watch your entire plugin stack update in seconds.

The project started around 2011, created by developers who wanted a faster way to manage WordPress at scale. In 2017, it moved under the official WordPress.org umbrella and is now maintained by a dedicated team of contributors including Alain Schlesser and Daniel Bachhuber.

Here’s what you need to know about WP-CLI:

  • Current stable version: WP-CLI 2.x series
  • WordPress compatibility: Works with WordPress 5.x through 6.x (and historically back to 3.7)
  • PHP requirements: PHP 7.4+ or 8.x recommended for security and performance
  • Command ecosystem: Over 40 parent commands covering virtually every WordPress operation
  • Primary users: Developers, agencies, DevOps engineers, and power users managing complex or multiple sites
  • Distribution: Available as a PHAR file, through package managers, or pre-installed on many managed WordPress hosts

Key Benefits of Using WP-CLI

Once you understand why WP-CLI exists, the learning curve becomes much easier to justify. This section explains the concrete advantages that make this tool worth your time.

Time savings on repetitive tasks
Updating 20 plugins through the WordPress dashboard means 20 page loads, 20 clicks, and watching 20 progress bars. With WP-CLI, you run wp plugin update --all once and move on. For agencies managing multiple client sites, this difference compounds into hours saved every week.

Bulk and automated operations
Consider a scenario where you’re preparing 15 WooCommerce stores for Black Friday. You need to update plugins, clear caches, and verify database integrity on each site. WP-CLI lets you script this entire sequence and execute it across all sites in minutes rather than hours. Key automation capabilities include:

  • Updating all plugins across multiple installations with a single script
  • Creating users in bulk with predefined roles
  • Running nightly maintenance via cron (database optimization, transient cleanup)
  • Deploying identical WordPress configurations to new environments

Reliability over browser-based operations
Browser operations hit HTTP timeouts. Large database imports fail mid-process. Search-replace operations corrupt serialized data when done with raw SQL. WP-CLI avoids all of these problems because it runs directly on the server with no timeout constraints, and its search-replace command correctly handles serialized data structures.

Direct control over core WordPress systems
From one terminal, you can:

  • Export and import the WordPress database
  • Modify wp-config.php settings
  • Inspect and trigger wp-cron events
  • Toggle maintenance mode on and off
  • Run arbitrary PHP code in the WordPress context

Reduced load on wp-admin
On busy production servers, every admin dashboard page load consumes resources. Running maintenance operations via WP-CLI keeps that load off the web server, which matters during high-traffic periods.

WP-CLI Requirements and Supported Environments

Before installing WP-CLI, you need to confirm your server or local environment meets the basic requirements. The good news is that most modern WordPress setups already qualify.

PHP version requirements:

  • Minimum: PHP 5.6 (though this is outdated)
  • Recommended: PHP 7.4, 8.0, 8.1, 8.2, 8.3, 8.4 or 8.5 for security and performance in 2026

WordPress version compatibility:

  • Historical support: WordPress 3.7 and newer
  • Modern target: WordPress 5.0 through 6.7+ for current projects

Operating system expectations:

  • Best support: UNIX-like systems (Ubuntu 22.04 LTS, Debian 12, CentOS Stream, macOS)
  • Windows: Supported via WSL (Windows Subsystem for Linux) or native PHP installation

Additional requirements:

  • PHP available on the command line (the php binary must be in your PATH)
  • cURL or wget for downloading the wp-cli.phar file
  • SSH access for remote servers (most managed WordPress hosting plans include this by default)

Many popular hosts like Kinsta, SiteGround, and DreamHost now ship with WP-CLI pre-installed. WordPress.com also includes WP-CLI for sites with SSH access enabled.

How to Install WP-CLI on Linux and macOS

The standard installation method uses the official PHAR (PHP Archive) file. This process works on Ubuntu, Debian, CentOS, Fedora, and macOS terminals.

Step 1: Download the PHAR file
Open your terminal and download wp-cli.phar using curl:

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

Alternatively, use wget:

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

Step 2: Verify the download (optional but recommended)
Check the SHA-256 checksum against the official value published in the WP-CLI documentation to ensure the file wasn’t tampered with during download:

sha256sum wp-cli.phar

Compare the output to the checksum listed on the official WP-CLI website.

Step 3: Test the PHAR file
Confirm that the php file works:

php wp-cli.phar --info

You should see output displaying WP-CLI version, PHP version, and system information.

Step 4: Make it executable and move to PATH
Mark the file as executable and move it to a directory in your system PATH:

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

The sudo command is typically required because /usr/local/bin is a system directory. Avoid installing WP-CLI as root if you’ll primarily run it as a regular user.

Step 5: Verify global installation
Confirm WP-CLI is now globally available:

wp --info
wp cli version

You should see output confirming the wp cli version, PHP binary location, and operating system details. At this point, you have WP-CLI installed and ready to use.

How to Install WP-CLI on Windows

Windows users have two main paths: using Windows Subsystem for Linux (WSL) or setting up a native Windows installation. WSL provides a more Linux-like experience and is generally recommended.

Option 1: Using WSL (Recommended)
First, enable WSL on Windows 10 or 11:

wsl --install

Install Ubuntu from the Microsoft Store, then launch the Ubuntu terminal. From there, follow the exact same Linux installation steps outlined in the previous section—download the phar file, make it executable, and move it to /usr/local/bin/wp.

Option 2: Native Windows Installation
For a native setup, you need PHP for Windows installed with the php executable available in your system PATH.

  1. Download and install PHP from the official PHP for Windows site
  2. Add the PHP directory to your Windows PATH environment variable
  3. Confirm PHP works by opening Command Prompt and running php -v

Next, download the WP-CLI PHAR file:

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

Windows includes curl by default since 2018, so this should work without additional setup. Create a folder for WP-CLI (e.g., C:\wp-cli) and move the downloaded file there.

Then create a batch wrapper file named wp.bat in the same folder:

@echo off
php "C:\wp-cli\wp-cli.phar" %*

Add C:\wp-cli to your system PATH environment variable. Now open a new Command Prompt or PowerShell window and verify:

wp --info

You should see the WP-CLI version and environment details confirming that WP-CLI is properly installed.

Basic WP-CLI Usage and Getting Help

With WP-CLI installed, you need to understand the basic command pattern before diving into specific operations. All WP-CLI commands follow this structure:

wp <command> <subcommand> [options]

Commands are executed from within a WordPress installation directory—the folder containing wp-config.php. If you’re elsewhere, you can specify the path with --path=/var/www/html/mysite.

Checking your environment
Start by confirming your setup:

wp --info

This displays your WP-CLI version, PHP version, PHP binary path, operating system, and other environment details. To see just the WP-CLI version:

wp cli version

Exploring available commands
To list all available wp cli commands:

wp help

For help on a specific command:

wp help plugin
wp help core update

You can also append --help to any command:

wp user --help

The help output displays in a pager similar to Unix man pages. Press q to exit.

First commands to try:

  • wp core version — displays your WordPress version
  • wp plugin list — shows all installed WordPress plugins with their status
  • wp theme list — shows installed themes
  • wp user list — lists all users on the site

These read-only commands let you explore your WordPress site without changing anything, which is perfect for getting comfortable with the interface.

Installing and Configuring WordPress with WP-CLI

WP-CLI can perform a complete fresh WordPress installation faster than the traditional web-based installer. This is especially valuable when spinning up development environments or deploying new sites programmatically.

Prerequisites
Before running the install commands, you need a MySQL or MariaDB database ready. For this example, assume you’ve created:

  • Database name: wpsite_db
  • Database user: wpsite_user
  • Password: securepassword123
  • Host: localhost

Step 1: Download WordPress core files
Navigate to your desired installation directory and download WordPress core:

wp core download

This fetches the latest WordPress version. To specify a version or locale:

wp core download --version=6.4.2 --locale=fr_FR

After completion, you’ll see confirmation that WordPress was downloaded successfully.

Step 2: Generate wp-config.php
Create the configuration file using wp config create:

wp config create --dbname=wpsite_db --dbuser=wpsite_user --dbpass=securepassword123 --dbhost=localhost

This generates a complete wp-config.php with your database credentials and automatically generated security salts.

Step 3: Run the installation
Now install WordPress with your site details:

wp core install --url=https://example.com --title="My New Site" --admin_user=admin --admin_password=strongpassword [email protected]

You’ll see the message “WordPress installed successfully” and your site is ready to use.

Multisite installation
For WordPress multisite networks, use the multisite variant. WP-CLI can configure multisite installations with:

wp core multisite-install --url=https://example.com --title="My Network" --admin_user=admin --admin_password=strongpassword [email protected]

Managing Themes with WP-CLI

WP-CLI handles all theme operations without requiring access to the WordPress admin dashboard. You can list, install, activate, update, and delete themes directly from your terminal.

Listing installed themes
To see all themes currently installed:

wp theme list

Sample output:

namestatusupdateversion
twentytwentyfouractivenone1.0
twentytwentythreeinactivenone1.2
astrainactiveavailable4.5.0

Activating a theme
Switch to a different theme:

wp theme activate astra

This immediately changes the active theme. Switching back to a default theme is useful for troubleshooting theme-related issues:

wp theme activate twentytwentyfour

Installing new themes
Install a theme from the WordPress.org repository:

wp theme install astra

Install and activate in one command:

wp theme install astra --activate

Updating themes
Update a specific theme:

wp theme update astra

Or update all themes at once:

wp theme update --all

Deleting themes
Remove a theme you no longer need:

wp theme delete twentytwentythree

Managing Plugins with WP-CLI

Plugin management is where WP-CLI saves the most time. You can perform bulk operations that would take dozens of clicks in the dashboard.

Listing plugins

wp plugin list

Sample output:

namestatusupdateversion
woocommerceactivenone8.5.1
yoast-seoactiveavailable21.0
elementorinactivenone3.18.0

Installing plugins
Install a plugin by its slug:

wp plugin install woocommerce

Install and activate:

wp plugin install yoast-seo --activate

Activating and Deactivating
Activate a plugin:

wp plugin activate elementor

Deactivate a plugin (useful for debugging):

wp plugin deactivate elementor

Deactivate all plugins at once (lifesaver for “White Screen of Death” debugging):

wp plugin deactivate --all

Updating plugins
Update a specific plugin:

wp plugin update yoast-seo

Update all plugins:

wp plugin update --all

You can also exclude specific plugins from a bulk update:

wp plugin update --all --exclude=woocommerce

Updating and Repairing WordPress Core

Keeping WordPress updated is critical for security. WP-CLI makes this process transparent and controllable.

Checking for updates

wp core check-update

Updating WordPress
Update to the latest version:

wp core update

After a core update, it’s good practice to update the database schema:

wp core update-db

Verifying checksums
If you suspect your site has been hacked, you can verify that core files haven’t been modified:

wp core verify-checksums

This compares your files against the official WordPress repository checksums.

Reinstalling Core
If files are corrupted, you can force a reinstall without affecting your content:

wp core download --force --skip-content

Managing Content, Users, and Database

WP-CLI allows you to interact with your site’s data directly.

User Management
List users:

wp user list

Create a new administrator:

wp user create newadmin [email protected] --role=administrator --user_pass=securepass123

Update a user password:

wp user update 1 --user_pass=newpassword

Delete a user and reassign their content:

wp user delete 5 --reassign=1

Database Operations
Export the database to a file:

wp db export backup.sql

Import a database from a file:

wp db import backup.sql

Optimize the database:

wp db optimize

Open a MySQL console directly connected to your WordPress database:

wp db cli

Search and Replace (The Right Way)

Moving a WordPress site to a new domain manually is risky because data is often serialized in the database. A simple SQL find-and-replace will break widgets and theme options. WP-CLI handles serialization correctly.

Standard Search-Replace

wp search-replace 'http://old-domain.com' 'https://new-domain.com'

Dry Run (Preview)
Always check what will change before running the command:

wp search-replace 'http://old-domain.com' 'https://new-domain.com' --dry-run

Exporting with replacement
You can export a database with the replacements made in the file, leaving the live database untouched:

wp search-replace 'old.com' 'new.com' --export=migrated-db.sql

Advanced Maintenance: Cron and Object Cache

Managing Cron Jobs
View scheduled events:

wp cron event list

Run all due cron events immediately:

wp cron event run --due-now

Managing Transients and Cache
Clear the object cache:

wp cache flush

Delete all expired transients:

wp transient delete --expired

Automating Tasks with Scripts

You can combine WP-CLI commands into Bash scripts for automated maintenance.

Example: Weekly Maintenance Script
Create a file named maintain.sh:

#!/bin/bash
# Update everything
wp core update
wp core update-db
wp plugin update --all
wp theme update --all

# Cleanup
wp transient delete --expired
wp cache flush
wp db optimize

echo "Maintenance complete."

Make it executable (chmod +x maintain.sh) and run it to perform full site maintenance in seconds.

Using WP-CLI Remotely via SSH

You don’t need to log into the server to run commands if you configure aliases.

In your local wp-cli.yml file:

@prod:
  ssh: [email protected]/var/www/html
@dev:
  ssh: [email protected]/var/www/html

Now you can run commands on the remote server from your local machine:

wp @prod plugin list
wp @dev core version

Best Practices

  • Always Backup: Before running bulk updates or search-replace commands, run wp db export.
  • Use Dry Run: For search-replace, always use --dry-run first.
  • Don’t run as Root: WP-CLI warns you if you run as root. It’s safer to run as the web server user (e.g., www-data) or your specific user account.
  • Test on Staging: Use WP-CLI to clone your production site to staging, test your update scripts there, and then apply to production.

Conclusion

WP-CLI transforms WordPress management from a series of clicks into streamlined, scriptable operations. Starting with simple commands like checking versions and listing plugins builds the foundation for advanced automation. Integrating WP-CLI into your workflow today will save countless hours across your WordPress projects.