2026年11月12日

WP-CLI cron Commands: wp cron event run and Server Cron

Customization

This article is a localized edition of the Japanese original. Read the Japanese original

With WP-CLI's wp cron event run, you can run WordPress scheduled tasks (WP-Cron) manually whenever you like. On top of that, if you stop the on-visit automatic execution with DISABLE_WP_CRON and run wp cron event run --due-now regularly from the server's cron, scheduled posts, backups and other tasks run regardless of how much traffic you get. This article covers the commands for listing, running, scheduling and deleting events, the steps for switching to server cron, and how to keep logs.

How WP-Cron Works and Why It Causes Trouble

WP-Cron does not run at fixed times the way real cron does. When someone visits the site, it checks "are there any events whose run time has passed?" and, if there are, runs them on the spot. That leads to problems like these:

On low-traffic sites, publishing scheduled posts and sending emails gets delayed
On high-traffic sites, the check runs frequently and adds load to the server
Depending on the server configuration, the request WordPress sends to itself (the loopback) fails, and events never run at all

WP-CLI's cron commands are useful both for investigating these problems and for fixing them.

Check the Registered Events

First, check which events are scheduled to run and when.

# List events (hook name, next run time, recurrence)
wp cron event list

# Show specific columns
wp cron event list --fields=hook,next_run_relative,recurrence

# List the registered recurrence intervals
wp cron schedule list

If next_run_relative shows "now" or times in the past, events whose run time has passed are piling up unprocessed. wp cron schedule list shows the standard WordPress intervals such as hourly, twicedaily, daily and weekly, as well as intervals added by plugins.

You can check whether WP-Cron can be triggered by site visits with the following command.

wp cron test

If the loopback request is failing, this shows an error. It is also reported as an error when you have set DISABLE_WP_CRON (covered below), but in that case it is fine, because you are planning to run it from server cron.

Run Events with wp cron event run

# Run a specific hook right now
wp cron event run wp_scheduled_delete

# Run all events whose run time has passed
wp cron event run --due-now

# Run all registered events, regardless of time
wp cron event run --all

When you specify a hook name, the events registered to that hook run without waiting for their scheduled time. This is handy when you want to confirm that a scheduled task in your own plugin works correctly.

For day-to-day operation, use --due-now. It does from the command line what WP-Cron is supposed to do: "run only the events whose time has passed." --all also runs events scheduled for later, so heavy tasks such as backups or bulk email sends may run at unexpected times. In production, check what will run with wp cron event list before you use it.

Schedule and Delete Events

# Schedule an hourly event starting now
wp cron event schedule my_custom_hook now hourly

# Schedule a one-time event at a specified time
wp cron event schedule my_custom_hook '+1 hour'

# Delete the events registered to a hook
wp cron event delete my_custom_hook

wp cron event schedule takes the hook name, the first run time and the recurrence, in that order. For the first run time, you can use relative expressions such as now or +1 hour, or a UNIX timestamp. If you omit the recurrence, the event runs only once. Scheduling an event does nothing by itself: you need to attach your task to that hook with add_action().

Deleting is useful for cleaning up events left behind by deactivated plugins. However, deleting an event that an active plugin uses stops that feature, and some plugins re-register the event the next time they load. Do not delete events when you cannot tell from the hook name what they do. You can check the details of arguments and options with wp help cron event schedule.

Replace It with DISABLE_WP_CRON and Server Cron

If you stop the on-visit automatic execution and run it regularly from the server's cron instead, the run interval becomes stable and the per-visit load disappears.

1. Stop the automatic execution in wp-config.php

define( 'DISABLE_WP_CRON', true );

Add it above the /* That's all, stop editing! */ line. As soon as you add this setting, WP-Cron via site visits stops working. If you forget to set up the server cron in the next step, scheduled posts and similar tasks will not run at all, so always do the two tasks together.

2. Register it in the server’s cron

*/5 * * * * /usr/local/bin/wp cron event run --due-now --path=/var/www/example.com/public_html >> /var/log/wp-cron/example.log 2>&1

This setting processes the events whose run time has passed every 5 minutes. Common pitfalls:

The cron environment has a minimal PATH, so write the full path to wp. You can find its location with which wp.
Specify the WordPress folder with --path. Without it, you get an error saying WordPress cannot be found.
Running it from root's crontab requires --allow-root, and files it creates end up owned by root. Running it as the web server user is safer.
Create the log output folder in advance and make sure the user running cron can write to it.

If you cannot edit the crontab directly on a shared hosting server, register the same command in the cron settings of the hosting control panel. On servers where WP-CLI is not available, you can also access wp-cron.php directly, for example with curl -s 'https://example.com/wp-cron.php?doing_wp_cron' > /dev/null.

If you have heavy events that take more than 5 minutes, you can also prevent overlapping runs with flock, so the next run does not start before the previous one finishes.

*/5 * * * * flock -n /tmp/wp-cron-example.lock /usr/local/bin/wp cron event run --due-now --path=/var/www/example.com/public_html >> /var/log/wp-cron/example.log 2>&1

Check That It Works in the Logs

After setting it up, check that the results are being recorded in the log. wp cron event run outputs a message for each event it runs and, at the end, the number of events executed.

tail -n 50 /var/log/wp-cron/example.log

If the count is 0 every time but wp cron event list still shows events with past times, either cron itself is not running or it is pointing at a different WordPress installation. If PHP errors appear in the log, you can narrow down the cause by running that event on its own with wp cron event run hook-name. Logs grow large if left alone, so clean them up regularly with logrotate or a similar tool.

On multisite, --due-now processes only the events of the main site (or the site specified with --url). To process every site, register a script in cron that runs the command with --url for each URL retrieved with wp site list --field=url.

(As of October 2026) The commands introduced here work in the current version of WP-CLI, but option details may differ between versions. Check with wp help cron event run in your own environment.

Summary

Check the schedule with wp cron event list, and use wp cron test to see whether triggering via site visits works
Use wp cron event run hook-name to run a single hook, --due-now to run only overdue events, and check what --all will run before using it
Schedule and delete events with wp cron event schedule / wp cron event delete
Always set up DISABLE_WP_CRON together with wp cron event run --due-now --path=... in server cron
Run cron as the web server user, keep logs, and check the execution count and errors

Questions about WordPress? The publisher of this site is based in Japan and replies in Japanese. Contact (Japanese)