Cron Command Laravel Package

Getting Started

wp-cli/cron-command ships bundled with the standard WP-CLI Phar, so there is usually nothing to install. Verify you have it and read the source of truth before anything else:

wp help cron
wp help cron event
wp help cron schedule

If you are on a stripped-down or custom WP-CLI build:

wp package install wp-cli/cron-command

It requires a bootstrapped WordPress install (WP-CLI resolves wp-config.php from the current directory or --path=) and works against the cron option — no database migration, no config file, no service to start. Think of it as the WordPress equivalent of php artisan schedule:list and php artisan schedule:run, but operating on a mutable option row rather than a PHP file.

First use case — see what is actually queued:

wp cron event list --fields=hook,next_run_relative,recurrence --format=table

This is the command you will reach for most often, because WordPress cron problems are almost never "the job didn't run" — they are "the job was never scheduled," "the job is scheduled four times," or "the job is scheduled for 1970." That single command answers all three. Pair it with wp cron schedule list to see which recurrences are even available, and wp cron test to confirm the loopback spawner works at all.

Implementation Patterns

Manual execution as a debugging primitive. wp cron event run <hook> fires the hook immediately. This is the fastest way to split "the callback is broken" from "the scheduler is broken" — run the hook by hand, and if it works, the problem is scheduling or the spawner.

wp cron event run my_project_sync
wp cron event run --due-now          # everything currently due
wp cron event run --all              # everything, due or not — be careful

Drive WP-Cron from system cron instead of page loads. The single most common production setup is to disable the loopback and run the queue deterministically:

// wp-config.php
define( 'DISABLE_WP_CRON', true );

* * * * * cd /var/www/site && wp cron event run --due-now --quiet

This is the direct analogue of Laravel's * * * * * php artisan schedule:run, and it makes failures visible in your cron mail/logs instead of hiding inside a random page request. wp cron test will report failure once DISABLE_WP_CRON is set — that is expected, not a regression.

Scripting against the output. Every list command supports --format=json|csv|yaml|table, which is what makes this package usable inside deploy pipelines and Laravel-side tooling:

wp cron event list --format=json | jq -r '.[] | select(.hook | startswith("my_plugin_")) | .hook'

From a Laravel app, wrap it with the Process facade rather than shelling out with exec:

use Illuminate\Support\Facades\Process;

$result = Process::path('/var/www/wordpress')
    ->timeout(120)
    ->run('wp cron event run my_project_sync --format=json');

if ($result->failed()) {
    report(new \RuntimeException($result->errorOutput()));
}

Always pass --timeout and always check failed() — a cron callback that fatals returns a non-zero exit code from WP-CLI, which is exactly the signal you want in a queue job or a health check.

Post-deploy hook execution. After a release that changes a plugin, run the hooks that need to catch up rather than waiting for the next tick:

wp cron event run my_plugin_import --url=https://example.com

Multisite note: cron events live per-site, so --url= is mandatory when you want to target a specific site. Loop explicitly; there is no --all-sites shortcut for cron.

Idempotent scheduling in deploy scripts. You can seed events with wp cron event schedule <hook> "+5 minutes" and clean up with wp cron event unschedule <hook>, but treat CLI scheduling as an operational escape hatch, not as application configuration. Recurring events belong in code (wp_schedule_event on activation), because a fresh environment has an empty cron option and nothing will recreate them.

Gotchas and Tips

event run is do_action, not a scoped job runner. It fires every callback attached to the hook — plugin listeners, theme listeners, unrelated add_action calls. On a busy hook this can do far more than you expect. Inspect the hook before running it in production.

--due-now means due now. A common confusion is running wp cron event run --due-now and concluding nothing happened because the events are scheduled for tomorrow. Use the explicit hook name to bypass the due check.

Timestamps are GMT. WordPress stores next_run_gmt as a UTC timestamp while wp cron event list displays relative time. When you pass a date string to wp cron event schedule, be deliberate about interpretation and confirm the result with --fields=hook,next_run_gmt,next_run_relative instead of trusting the input. Off-by-one-timezone is the #1 cause of "it runs at 3am instead of 9am."

delete and unschedule are blunt instruments. wp cron event delete <hook> removes all events for that hook, with no confirmation and no undo. Dump first:

wp cron event list --format=json > cron-backup-$(date +%F).json

Duplicate events accumulate silently. Calling wp_schedule_event without an wp_next_scheduled() guard — or running a schedule command twice in a deploy — produces duplicate entries that all fire. wp cron event list shows them plainly; look for repeated hooks with identical recurrence.

Custom recurrences can only come from PHP. wp cron schedule list shows what is registered via the cron_schedules filter. WP-CLI cannot register a new schedule, and if an event references a schedule whose filter no longer exists, it becomes effectively orphaned — the recurrence column goes blank and rescheduling behaves oddly. This is the extension point: use add_filter( 'cron_schedules', ... ) in a mu-plugin so it is always loaded.

Field names drift between versions. next_run_relative, next_run_gmt, and friends have changed across releases. Since the package has a long release cadence, pin the WP-CLI version in CI and re-check wp help cron event list when you upgrade — scripts that hardcode field names break quietly by emitting blanks.

Persistent object caches can lie. The cron option is autoloaded and object-cached. If another process (a web request) just modified the queue and you have a persistent cache backend, run wp cache flush or confirm you are seeing fresh data before drawing conclusions from a list command.

wp cron test fails on local and CI by design. It performs a loopback HTTP request to wp-cron.php; on Docker, behind basic auth, or with DISABLE_WP_CRON set, it will fail. Gate it behind an environment check so it does not poison your pipeline.