Posted in

What is WP-CLI

by WP95/
WP-CLI
WP-CLI

Imagine managing your entire WordPress site — installing plugins, updating themes, creating users, and even backing up your database — without ever opening your browser. Sounds like magic? That’s exactly what WP-CLI lets you do.

WP-CLI (short for WordPress Command Line Interface) is a powerful tool that allows you to interact with your WordPress website using simple text-based commands, right from your terminal or command prompt.

In other words, it’s like having a direct hotline to your WordPress site — no clicking through menus, no waiting for the dashboard to load. Just fast, clean, and efficient control over everything under the hood.

💡 Think of WP-CLI like this: If the WordPress admin dashboard is the steering wheel and touchscreen of your car, WP-CLI is the engine bay. It’s where the pros go to get serious work done.

⚙️ Who Is WP-CLI For?

  • 👩‍💻 Developers who want to automate tasks and work faster
  • 🧑‍🔧 System administrators managing multiple WordPress installations
  • 📦 Hosting providers who integrate WP-CLI into their backend tools
  • 🧠 Power users looking to supercharge their WordPress skills

But even if you’re not a developer, don’t be intimidated! You only need to learn a few basic commands to start benefiting from WP-CLI’s speed and convenience.

🧭 What Can You Do With WP-CLI?

Here’s just a taste of what’s possible:

  • 🔄 Update WordPress core, plugins, and themes — instantly
  • 🧪 Install or remove plugins without logging in
  • 👥 Create, delete, and manage users
  • 🧹 Clear transients, rewrite rules, and regenerate thumbnails
  • 💾 Export or import your site’s database with a single line

WP-CLI is open-source, officially supported by the WordPress project, and continuously updated by a global community of contributors.

In this guide, we’ll take you from “What is WP-CLI?” to confidently using it in your workflow — with plenty of visuals, real-world examples, and friendly tips along the way.

⚡ Why Use WP-CLI?

If you’ve ever felt slowed down by the WordPress dashboard — waiting for pages to load, clicking through layers of menus — then you’ll love what WP-CLI brings to the table.

With WP-CLI, you can perform essential site tasks in seconds, often with a single command. No GUI, no mouse, just pure productivity.

🚀 The Power of the Command Line

  • ⚡ Speed: WP-CLI is lightning fast. Want to update all your plugins? Just type one command and it’s done in seconds.
  • 💡 Clarity: Every command is direct and purposeful. No distractions. No loading screens.
  • 🔁 Repetition: Need to perform the same task across multiple sites? WP-CLI lets you script and repeat tasks like a pro.

🧩 Real-World Use Cases

Here are just a few common things WP-CLI helps you do better:

  • 🔄 Update WordPress core and all plugins with a single command
  • 🚫 Deactivate a problematic plugin if your dashboard is inaccessible
  • 📦 Install and activate a theme or plugin without downloading ZIP files
  • 🔍 Search and replace URLs in the database (great for migrations)
  • 👥 Create or delete users instantly
  • 💽 Backup and export your site database

💬 Example: Let’s say your site breaks after a plugin update. You can disable the plugin via WP-CLI even if you’re locked out of the admin dashboard.

wp plugin deactivate plugin-name

👨‍🔧 Ideal for Developers & Sysadmins

WP-CLI is a dream tool for:

  • 🛠️ Local development environments like Local, DevKinsta, or Laravel Valet
  • 📁 Managing multisite installations
  • 🔗 Automating tasks in CI/CD pipelines
  • 🎯 Handling headless WordPress setups

In short: WP-CLI turns your workflow from slow and reactive to fast and efficient — perfect for serious WordPress work.

🛠️ How to Install WP-CLI

Getting started with WP-CLI is surprisingly easy — no need to be a Linux guru. In just a few minutes, you can have it installed and ready to use on macOS, Linux, or Windows.

🧠 Heads-up: WP-CLI requires PHP 5.6+ and WordPress 3.7+. Make sure your hosting environment meets these requirements.

💻 Step-by-Step Installation (Linux & macOS)

  1. Download the Phar (PHP Archive) file:
    curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar
  2. Check that it works:
    php wp-cli.phar --info
  3. Make it globally accessible:
    chmod +x wp-cli.phar
    sudo mv wp-cli.phar /usr/local/bin/wp
  4. Now run it:
    wp --info (🎉 You’re in!)

Installing WP-CLI on Windows

Windows users can install WP-CLI via tools like Homebrew (WSL), Composer, or Scoop.

Here’s the Scoop method:

  1. scoop install wp
  2. Open a new terminal and run: wp --info
  3. Done!

🔎 Verifying Your Installation

Run the following command to confirm WP-CLI is installed:

wp --info

If you see details like PHP version, WP-CLI version, and OS environment — you’re all set!

💡 Quick Troubleshooting Tips

  • 🔐 If sudo fails, check your user permissions.
  • 🔍 If wp isn’t found, make sure /usr/local/bin is in your $PATH.
  • 🧪 Still stuck? Visit the WP-CLI support page.

With WP-CLI installed, you’re ready to start exploring powerful commands that save you time and headaches — coming up in the next section!

🧪 Getting Started with WP-CLI Commands

With WP-CLI successfully installed, you’re ready to unlock its power. Don’t worry — the learning curve is gentle. WP-CLI uses plain English-like commands that make sense and are easy to remember.

📌 WP-CLI Command Structure

WP-CLI commands follow a predictable structure:

wp <command-group> <command> [options]

Example:

wp plugin install contact-form-7 --activate

This tells WP-CLI to: Install the “Contact Form 7” plugin and activate it immediately.

💡 Pro Tip:

You can run WP-CLI commands from the root of your WordPress installation — the folder where wp-config.php lives.

🧰 Common Beginner Commands

  • wp core update – Update WordPress core
  • wp plugin list – List installed plugins
  • wp theme install astra --activate – Install & activate the Astra theme
  • wp user create john john@example.com --role=editor – Create a new user with the Editor role
  • wp search-replace 'http://oldsite.com' 'https://newsite.com' – Replace all URLs in your database (great for migrations)

🔎 Learning More About Any Command

WP-CLI has built-in help for every command. Just add --help to see usage and options.

wp plugin --help

You’ll get a detailed breakdown of available plugin-related commands like install, activate, delete, and more.

✅ Best Practices

  • 💾 Backup first: Especially before running database commands.
  • 📂 Run from the right directory: WP-CLI needs access to your WordPress files.
  • 🧱 Test in staging: When trying new scripts or commands, use a staging environment first.

Now that you’ve dipped your toes in, you’re ready to explore some of WP-CLI’s most powerful and time-saving commands next!

🔧 Most Useful WP-CLI Commands (With Examples)

Now that you’ve learned the basic structure of WP-CLI commands, it’s time to level up. Below, we’ll explore some of the most commonly used WP-CLI commands, along with examples of how they can speed up your workflow.

1. 🆙 Updating WordPress Core, Plugins, and Themes

Keeping your WordPress site up to date is crucial for security and performance. With WP-CLI, you can update WordPress core, themes, and plugins in no time.

  • wp core update – Updates WordPress to the latest version.
  • wp plugin update --all – Updates all plugins.
  • wp theme update --all – Updates all themes.

Example: Let’s say you want to update just one plugin — perhaps the “Yoast SEO” plugin. You can do it like this:

wp plugin update yoast-seo

2. ⚙️ Installing and Activating Plugins/Themes

Installing plugins and themes is a breeze with WP-CLI. You don’t need to leave your terminal at all.

  • wp plugin install plugin-name --activate – Installs and activates a plugin in one step.
  • wp theme install theme-name --activate – Installs and activates a theme.

Example: Want to install and activate the “Jetpack” plugin? Simply run:

wp plugin install jetpack --activate

3. 🔎 Listing Plugins, Themes, and Users

When you need an overview of your WordPress setup, WP-CLI lets you list installed plugins, themes, and users without having to dig through the admin dashboard.

  • wp plugin list – Lists all installed plugins.
  • wp theme list – Lists all installed themes.
  • wp user list – Lists all users on your site.

Example: Let’s say you need to check which plugins are activated:

wp plugin list --status=active

4. 📦 Managing the Database

WP-CLI makes managing your database a breeze. From exports to imports, it handles it all without ever needing the browser.

  • wp db export – Exports your database to a file.
  • wp db import filename.sql – Imports a database file.
  • wp db reset – Resets your database (use with caution!).

Example: If you want to back up your database to a file called “backup.sql,” simply run:

wp db export backup.sql

5. 👥 Managing Users

WP-CLI makes creating, updating, and deleting users as simple as running a command. This is great for administrators who manage large sites.

  • wp user create username email --role=role – Creates a new user with a specific role.
  • wp user delete user-id – Deletes a user from your site.
  • wp user update user-id --user_pass=new-password – Updates a user’s password.

Example: To create a new user with the role “Editor,” run:

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

6. 🔄 Search and Replace in the Database

This one is incredibly useful when migrating sites. WP-CLI lets you search and replace content in your database quickly and safely.

  • wp search-replace old-url new-url – Replaces all instances of an old URL with a new one.

Example: When moving a site from http://oldsite.com to https://newsite.com, use:

wp search-replace 'http://oldsite.com' 'https://newsite.com'

💡 Bonus Tip: Use a Dry Run First

Before performing a search and replace operation, you can use the --dry-run flag to see what changes will be made without actually modifying the database:

wp search-replace 'http://oldsite.com' 'https://newsite.com' --dry-run

With these essential WP-CLI commands, you’re ready to tackle almost any task on your WordPress site quickly and efficiently.

⚡ Advanced WP-CLI Usage

Once you’ve mastered the basic commands, it’s time to supercharge your workflow with advanced WP-CLI features. These powerful tools and options will help you automate tasks, manage large sites, and extend WP-CLI’s functionality.

1. 📜 WP-CLI Aliases

WP-CLI aliases allow you to manage multiple WordPress sites more easily. You can create shortcuts for commonly used commands, making it faster to manage different environments (e.g., staging, production) from a single terminal window.

Define an Alias: You can define an alias by editing your ~/.wp-cli/config.yml file and adding something like this:

aliases:
  production:
    url: 'https://example.com'
    path: '/var/www/html/production'
  staging:
    url: 'https://staging.example.com'
    path: '/var/www/html/staging'

Once defined, you can use these aliases in commands like this:

wp @production plugin list

2. 🛠️ WP-CLI Commands with Scripts

Automate repetitive tasks by creating WP-CLI scripts. With scripts, you can bundle multiple commands into one action — a huge time-saver for common maintenance tasks like backups, updates, or user management.

Example: Create a backup script that updates WordPress, plugins, and themes, then exports the database:

#!/bin/bash
wp core update
wp plugin update --all
wp theme update --all
wp db export backup.sql

Save this as wp-backup.sh and execute it with ./wp-backup.sh.

3. 📡 WP-CLI and Cron Jobs

WP-CLI can be integrated with cron jobs for regular tasks like backups, updates, or email notifications. This allows you to automate these tasks on a scheduled basis without needing to intervene manually.

  • Example: Set up a cron job to back up the database every night at midnight:
0 0 * * * wp db export /path/to/backup.sql

With this in place, WP-CLI will automatically back up your database every night without you lifting a finger!

4. 🧑‍💻 WP-CLI for Multi-Site Networks

If you’re managing a WordPress multisite network, WP-CLI makes it easy to work with individual sites within the network.

  • wp site list – Lists all sites in the network.
  • wp site create --slug=site-slug – Creates a new site within the multisite network.
  • wp site delete site-id – Deletes a site from the network.

Example: To list all sites on a multisite network:

wp site list

5. 🚀 WP-CLI and WP-CLI Extensions

WP-CLI can be extended with plugins to add custom functionality. There are numerous community-created extensions that you can install to further enhance your WP-CLI experience.

  • wp package install package-name – Installs a WP-CLI package.
  • wp package list – Lists installed WP-CLI packages.

Example: Install the “wp-cli/cache-command” package:

wp package install git@github.com:wp-cli/cache-command.git

6. 📝 WP-CLI Configuration

You can configure WP-CLI to behave the way you want by setting options in a configuration file. WP-CLI looks for a configuration file in your home directory (~/.wp-cli/config.yml) or in the root of your WordPress installation.

Common Configurations:

  • alias: Set up WP-CLI aliases.
  • cache_dir: Specify a custom cache directory.
  • require: Automatically load a PHP file before running any command.

Example: If you want to change the default cache directory to /var/www/.wp-cli/cache/, add the following to ~/.wp-cli/config.yml:

cache_dir: '/var/www/.wp-cli/cache/'

These advanced features of WP-CLI will help you automate, scale, and customize your workflow to meet the unique needs of your WordPress site.

🛠️ Troubleshooting and Common Errors in WP-CLI

While WP-CLI is incredibly reliable, like any tool, issues can arise. In this section, we’ll cover some of the most common WP-CLI errors and offer solutions to keep you on track.

1. 🔴 Error: “WP-CLI not installed” or “Command not found”

If you encounter the error “wp: command not found”, it usually means WP-CLI is either not installed properly or not available in your system’s PATH.

Solution: Ensure WP-CLI is installed by running the following command:

which wp

If this returns nothing, try installing WP-CLI again by following the official installation instructions. If you installed it via Composer, you may need to add ~/.composer/vendor/bin to your system’s PATH.

2. ⚠️ Error: “Access Denied” or “Permission Issues”

If you receive permission errors, especially when trying to run WP-CLI commands that modify files or directories (like wp plugin install), it’s likely a file permission issue.

Solution: Check file and directory permissions using:

ls -l

If necessary, adjust the permissions using chmod or chown commands:

sudo chown -R www-data:www-data /path/to/your/wordpress/directory

Be cautious when using sudo, as running WP-CLI as root can create file permission issues later. It’s best to run WP-CLI with the same user that owns your WordPress files.

3. 🔄 Error: “Database Connection Failed”

If you receive an error about the database connection (e.g., “Error establishing a database connection”), this indicates an issue with your wp-config.php file or your database credentials.

Solution: Double-check your wp-config.php file for the correct database settings:

define('DB_NAME', 'your_db_name');
define('DB_USER', 'your_db_user');
define('DB_PASSWORD', 'your_db_password');
define('DB_HOST', 'localhost');

If you are sure your credentials are correct but are still facing issues, verify that your MySQL server is running by using:

sudo service mysql status

4. ⏳ Error: “Command Times Out”

If a WP-CLI command takes longer than expected or times out, it may be due to large databases or complex operations (e.g., search and replace). The default PHP execution time limit might be too short.

Solution: Try increasing the max_execution_time limit in your php.ini file:

max_execution_time = 300

Alternatively, run the command with a higher memory limit by adding the --memory-limit flag:

wp search-replace 'old-url' 'new-url' --memory-limit=512M

5. ❓ Error: “Unknown Command”

If WP-CLI returns an error saying it can’t recognize a command, it could be due to a typo or missing plugin/extension.

Solution: Double-check the command syntax and ensure the required plugin or package is installed. Use the --help flag to see the correct usage:

wp plugin --help

6. 🧹 Clearing Cache or Resetting WP-CLI

If WP-CLI is acting unexpectedly (e.g., commands are not reflecting recent changes), clearing its cache or resetting it may help resolve the issue.

Solution: Clear the cache by running:

wp cache flush

If that doesn’t resolve the issue, try resetting WP-CLI’s state:

wp cli reset

7. 🛑 Debugging WP-CLI Errors

If you encounter persistent issues, WP-CLI offers a debug mode that provides detailed information about what’s going wrong.

  • --debug – Enables debugging mode for a command. Example:
wp plugin install jetpack --debug

By running WP-CLI with the --debug flag, you’ll get more insight into the errors, including stack traces and PHP errors.

Tip: If you continue to experience issues, check the WP-CLI GitHub repository or ask for help on the WP-CLI Slack channel or WordPress StackExchange.

By following these troubleshooting steps, you’ll be able to quickly resolve most common issues with WP-CLI and continue managing your WordPress sites with confidence.

🏁 Final Thoughts

WP-CLI is an indispensable tool for WordPress developers, site administrators, and advanced users. Whether you’re managing a single site or a network of hundreds, WP-CLI streamlines your workflow and automates repetitive tasks, saving time and effort. From simple installations to complex migrations and backups, WP-CLI has got you covered.

In this guide, we’ve walked through everything you need to get started with WP-CLI, including:

  • The Basics: Installing WP-CLI and running simple commands.
  • Advanced Features: Automating tasks with scripts, cron jobs, and aliases.
  • Troubleshooting: How to resolve common errors and handle command failures.

By now, you should have a solid understanding of WP-CLI’s capabilities and how to use it effectively. The power of the command line is at your fingertips, giving you the ability to execute tasks faster, manage multiple sites, and streamline your development process.

Happy WordPressing!