← All posts

Managing Docket Cache With WP-CLI

By Nawawi Jamili · 3 November 2026 · 5 min read

If you look after WordPress sites from the command line, you can do almost everything in Docket Cache without opening the admin. This post shows the commands we use most, with real output from one of our test sites.

Two kinds of wp cache commands#

WP-CLI already has a wp cache command, and it works with any object cache. Docket Cache does not add a new command. It adds its own subcommands to wp cache. Type wp cache on its own to see them all.

• From WP-CLI itself. add, get, set, delete, incr, decr, replace, flush-group, patch, pluck, supports and type.
• From Docket Cache. status, and the commands that start with dropin:, flush:, reset:, run: and runtime:. Docket Cache also replaces flush with its own version.

The commands from WP-CLI itself are useful to test any object cache. Our post Is My Object Cache Working? uses wp cache type, set and get for that.

Check the cache#

wp cache status

---------------:--------------------------------
Cache Status   : Enabled
Cache Path     : /wp-content/cache/docket-cache
Cache Size     : 215K
---------------:--------------------------------

For the size and the number of files, run the stats.

wp cache run:stats

---------------:----------
Object size    : 215K
File size      : 233K
Total file     : 65
---------------:----------
Success: Executing the cache stats completed.

Object size is the size of the cached data. File size is a little bigger, because each file also holds the key, the group and the expiry time.

Clear the cache#

wp cache flush removes all cache files. Most of the time you only need to clear one part, and Docket Cache has a command for each.

For example, after you change a plugin that keeps its data in transients, clear only those.

wp cache flush:transient

Success: The transient was flushed. Total cache flushed: 16

The rest of the cache stays warm, so your site does not have to build everything again.

Run the garbage collector#

The garbage collector normally runs every 5 minutes as a WordPress scheduled task. You can also run it yourself.

wp cache run:gc

-----------------------------------:----------
Cache MaxTTL                       : 345600
Cache File Limit                   : 50000
Cache Disk Limit                   : 500M
-----------------------------------:----------
Cleanup Cache MaxTTL               : 0
Cleanup Cache File Limit           : 0
Cleanup Cache Disk Limit           : 0
-----------------------------------:----------
Total Cache Cleanup                : 0
Total Cache Ignored                : 0
Total Cache File                   : 77
-----------------------------------:----------
Success: Executing the garbage collector completed.

The first three lines are your limits. The next three show how many files were removed because they were too old, or because the cache was over its file or disk limit. On a healthy site these are often zero, as here.

Run scheduled tasks#

wp cache run:cron

This runs every WordPress scheduled task at once, whether it is due or not, and then lists them. This is the start of the output from our test site.

Executed the cron event 'docketcache_gc' in 0.02s.
Executed the cron event 'wp_privacy_delete_old_export_files' in 0.006s.
Executed the cron event 'wp_version_check' in 0.754s.
...
Success: Executed a total of 19 cron events.

It is useful when you want to check that scheduled tasks work. For a server cron job that runs every few minutes, use the WP-CLI command that runs only the tasks that are due.

wp cron event run --due-now

Clean up the database#

wp cache run:optimizedb

This deletes expired transients from the database, and then optimises every table in it. On a large database this can take some time, so run it when your site is quiet.

Fix a stuck task#

Docket Cache uses small lock files, so the same task does not run twice at the same time. If a task stopped halfway, for example because PHP ran out of time, its lock can stay behind. These two commands start fresh.

wp cache reset:lock
wp cache reset:cron

reset:lock removes the lock files, and reset:cron schedules the Docket Cache tasks again.

Manage the drop-in file#

The drop-in file wp-content/object-cache.php connects WordPress to Docket Cache.

Use dropin:update after you move a site to a new server, or when you switch to Docket Cache from another object cache plugin. Before 26.04.12, the example in the help for this command showed wp cache update, which is wrong. The command is wp cache dropin:update.

Runtime code#

wp cache runtime:install
wp cache runtime:remove

These add or remove the small piece of code in wp-config.php that lets Docket Cache set some WordPress constants from its Configuration screen. Our post Runtime Code explains what it does.

WP-CLI and OPcache#

WP-CLI runs in its own PHP process, and it does not share OPcache with your web server. So it cannot drop a file from the web server's OPcache by itself.

After a flush from WP-CLI, Docket Cache sends a short request to the web server, and the web server drops the old copies. The DOCKET_CACHE_WPCLI_OPCACHE option controls this, and it is on by default.

When WP-CLI writes a single value, for example with wp cache set, the web server finds the new file with its normal timestamp check. Up to 26.04.11, a write from WP-CLI in the same second as a write from the web could leave the old value in the web server's OPcache. Since 26.04.12, WP-CLI writes keep their real file time, so this no longer happens.

Use it in scripts#

All of these commands work in scripts. For example, this is a short script to run after you deploy a new version of your site.

wp cache dropin:update
wp cache flush
wp cache run:stats

Add --path to point WP-CLI at the right WordPress folder, or --url for a site on multisite. If you test on local sites, our post How We Test Docket Cache With WP Staging CLI shows how we run the same commands from our own terminal.

The WP-CLI page in the documentation lists every command.