How to Debug WordPress with WP-CLI

Published 16/09/25 · Read 4 minute

Debugging is an essential part of running a WordPress site. While plugins and the WordPress dashboard offer tools for troubleshooting, developers and advanced users often prefer WP-CLI (WordPress Command Line Interface).

It’s a powerful tool that lets you manage and debug your WordPress site directly from the command line—faster, cleaner, and without relying on the admin interface.

Here’s a step-by-step guide on how to debug WordPress with WP-CLI.

What is WP-CLI?

WP-CLI is a command-line tool that allows you to manage your WordPress installation. Instead of navigating through the admin dashboard, you can:

  • Install and update plugins/themes.

  • Manage users and posts.

  • Perform database operations.

  • Run debugging commands.

For developers and sysadmins, it’s one of the most efficient ways to troubleshoot issues in WordPress.

1. Check WordPress Environment

Before debugging, confirm that your WordPress installation is running correctly.

wp core check-update

This command checks if your WordPress core needs updating.

To see the current WordPress version:

wp core version

2. Debug Plugin and Theme Issues

Conflicts between plugins or themes often cause site errors.

List all active plugins:

wp plugin list --status=active

Deactivate a plugin:

wp plugin deactivate plugin-slug

Switch to a default theme:

wp theme activate twentytwentyfive

By deactivating plugins and switching themes via WP-CLI, you can quickly isolate what’s causing issues without needing the dashboard.

3. Enable Debugging in WordPress

Enable debugging mode in wp-config.php:

wp config set WP_DEBUG true --raw
wp config set WP_DEBUG_LOG true --raw

This will log errors into wp-content/debug.log. You can then view the log directly with WP-CLI:

wp log tail

(If you don’t have wp log, use standard Linux tail command: tail -f wp-content/debug.log)

4. Inspect Database Issues

If your site has database errors, WP-CLI can help.

Repair the database:

wp db repair

Optimize tables:

wp db optimize

Run a SQL query for debugging:

wp db query "SELECT * FROM wp_options WHERE autoload='yes' LIMIT 10;"

5. Check Site Health

WP-CLI can run WordPress health checks.

wp site check

(If not available, plugins like Health Check & Troubleshooting can be combined with WP-CLI to generate detailed reports.)

6. Manage Caches

Caching problems often cause outdated content or display issues.

Clear WordPress cache with WP-CLI (depends on your caching plugin):

  • WP Super Cache:

wp super-cache flush

  • W3 Total Cache:

wp w3-total-cache flush

  • Object Cache (if using Redis/Memcached):

wp cache flush

7. Debug Cron Jobs

WordPress cron jobs sometimes fail and cause issues with scheduled tasks.

List cron jobs:

wp cron event list

Run a cron job manually:

wp cron event run hook-name

8. Check Site Logs and Errors

Sometimes server-level errors need investigation.

  • Check recent PHP errors:

wp eval 'error_log("Debugging WordPress with WP-CLI at " . date("Y-m-d H:i:s"));'

  • View server logs (depending on hosting environment):

tail -f /var/log/apache2/error.log

or

tail -f /var/log/nginx/error.log

FAQ:

Q: Do I need coding skills to use WP-CLI?
Not necessarily. Basic command-line knowledge is enough for most debugging tasks.

Q: Can WP-CLI break my site if used incorrectly?
Yes, certain commands (like deleting data) can cause issues. Always back up before debugging.

Q: How do I install WP-CLI?
Download from wp-cli.org or use your hosting provider’s pre-installed version.

Q: Can I debug multisite with WP-CLI?
Yes. WP-CLI fully supports multisite installations with commands like --url=site.com.

Q: Is WP-CLI faster than using the WordPress dashboard?
Yes, especially for bulk operations, database queries, and debugging tasks.

👉 With WP-CLI, WordPress debugging becomes faster, more precise, and less dependent on plugins. It’s an essential tool for developers and site administrators who want to keep their WordPress sites running smoothly.