WP-CLI

Before you start

• Caching Out Pro, switched on. The command ships in the Pro add-on: with the free plugin alone, WP-CLI answers Error: 'cachingout' is not a registered wp command. From 1.26.0 it also waits for the licence: on a site where Pro is installed but not switched on yet (see Licensing), every command stops with Error: Caching Out Pro is not switched on on this site: validate a licence on the License tab. (exit code 1), except wp cachingout version and wp cachingout settings export, which always run.
• Check it is there: wp cachingout version prints two lines, the free plugin's version and then Pro <version>.
• Exit codes: every command exits 0 when it succeeds and 1 when it prints an Error: line, so a script can stop on failure. A few commands exit 0 with a message when there is nothing to do; each section below says which.
• Activity: every wp cachingout command is recorded on the site's Activity page as one cli.command row (the command and subcommand only, never a value, because a value can be a key), and each setting it changes gets its own row there, revertible like any other change.

Every command at a glance

purge

wp cachingout purge
wp cachingout purge --post_id=42

Without arguments it clears every cached page of the site and prints Success: All page cache purged. With --post_id it clears that post's cached page and prints Success: Cache purged for post 42.; an id that does not exist ends with Error: Post 42 does not exist. There is no --all flag: the plain command already purges everything. Pages are rebuilt on their next visit, or by preload.

preload

wp cachingout preload
wp cachingout preload --batch_size=8

Reads the site's sitemaps, queues every page that may be cached, crawls the first batch at once and leaves the rest to WordPress cron, a batch at a time, exactly as the Preload tab does. --batch_size changes the batch size for this run only. It prints Starting cache preloading... and Success: Preloading complete.

That success line means the command finished, not that pages were queued: it is printed too when Preload or Page Caching is switched off, when no sitemap was found, or when a crawl that made progress in the last hour is still running. If nothing gets cached, check the Preload tab.

settings

wp cachingout settings
wp cachingout settings cache --format=json

Shows the stored settings, one row per setting (Section, Key, Value; on / off for switches, lists comma-joined, (empty) for nothing). API keys and credentials print as [redacted] (the Cloudflare, Sucuri and Insights keys: the same list the Activity record redacts); add --reveal to print them, and keep that output out of logs and tickets (1.26.0 and later). Sections: cache, browser_cache, media, file_optimization, heartbeat, insights, preload, database, addons, cdn. --format takes table (default), json, yaml or csv. An unknown section ends with Error: Unknown settings section: <name>.

This command shows every value in full, including the PageSpeed, Cloudflare and Sucuri keys you saved. The settings screens mask them; the terminal does not, because anyone who can run WP-CLI can already read the database. Do not paste its output into a support message: use settings export, which leaves the keys out.

settings export

wp cachingout settings export > settings.json
wp cachingout settings export cache > cache.json
wp cachingout settings export --format=json

Prints the settings as JSON to standard output (redirect it to a file; there is no --file option). Give a section name to export one section. --format=json prints compact JSON for piping; the default is indented. Licence keys, API keys and add-on credentials are left out unless you add --sensitive, which puts the API keys and credentials back in: keep such a file private. The Import / Export page lists what is included.

settings import

wp cachingout settings import settings.json --preview
wp cachingout settings import settings.json

Reads an exported file, validates it, and applies it section by section. With --preview it changes nothing and prints each setting that would change as key: old -> new under its section (switches as true / false, lists as JSON, the same way Activity shows them; an API key or credential prints as [redacted] -> [redacted]), or Success: No changes would be made when the file matches. Without it, it prints Success: Settings imported: N sections updated, M keys changed., where M counts the settings whose value differed from the file, not every key the file holds (1.26.0 and later). A file that cannot be read or is not a Caching Out export ends with an Error: line and changes nothing. Every changed setting is recorded on Activity, where it can be reverted.

audit (the Activity record)

wp cachingout audit list
wp cachingout audit list --problems --format=json
wp cachingout audit list --type=settings.change --actor=1 --limit=100
wp cachingout audit export --file=activity.json --since=7d
wp cachingout audit revert 4213
wp cachingout audit revert 4213 --yes

• list prints the newest changes first: id, when, actor, type, target, change (old -> new) and result. --limit defaults to 50 and stops at 500; --problems keeps the refused and failed changes; --type takes a row type such as settings.change (an unknown type is ignored); --actor takes a value from the actor column, such as a user id; --format takes the usual WP-CLI formats. An empty record prints No changes recorded.
• export prints the same JSON document as the Download button on the Activity page; --file=<path> writes it to a file instead, and --since=7d keeps the last seven days.
• revert <id> first prints the change, each setting with its current value and the value it would restore, and any warning (the setting changed again since; settings that are never restored, such as keys). Then it stops: Nothing changed. Re-run with --yes to apply this revert. With --yes it applies the revert and prints Success: Change #4213 reverted (recorded as #4214).; the revert is itself recorded. A row that is gone, or a change that cannot be reverted, ends with an Error: line saying why. More on reading the record: Activity.

assets (Unused CSS/JS)

wp cachingout assets scan --pages=10
wp cachingout assets scan --page=https://example.com/shop/
wp cachingout assets list
wp cachingout assets list --page=https://example.com/shop/
wp cachingout assets rules
wp cachingout assets preview
wp cachingout assets suggest
wp cachingout assets revert --id=r7f3a91
wp cachingout assets revert --all

• scan fetches a sample of the site's pages (up to 50; --pages=<n> takes fewer) and records which stylesheets and scripts each one loads. --page=<url> scans that one page instead of the sample (1.26.0 and later). It prints one row per page with the number of files, or the error for a page it could not fetch.
• list prints the files one scanned page loads (handle, type, bytes, deps, src): the page named by --page=<url>, or the first scanned page without it. A page the last scan did not visit ends with Error: That page is not in the last scan.
• rules lists the stored unload rules; preview shows, for each scanned page, which files the rules would unload and which they keep (and why), with a total; suggest lists the rules the built-in catalogue proposes from the last scan. All three change nothing; a suggestion is accepted on the Unused CSS/JS tab, after its preview.
• revert switches one rule (--id) or every rule (--all) off without deleting it, and prints Success: Switched off N rule(s): .... When no enabled rule matches it prints Nothing to revert and exits 0.

list, preview and suggest need a scan first and end with Error: No scan results. Run 'wp cachingout assets scan' first. without one.

The page option is --page, not --url. --url is WP-CLI's own option (it chooses the site, see below), so WP-CLI takes it before Caching Out sees it: assets scan --url=<page> scans the usual sample and assets list --url=<page> lists the first scanned page, whatever page you name. Name the page with --page=<url> instead. The File Optimization page has the rules themselves.

walkback (the Troubleshooting tab)

wp cachingout walkback changes --since=3d
wp cachingout walkback changes --since=2026-11-01T10:00 --format=json
wp cachingout walkback suspects --since=3d --symptom=layout
wp cachingout walkback suspects --since=3d --symptom=function --page=/shop/ --format=json
wp cachingout walkback check /shop/

The three steps of the Troubleshooting tab's walk-back (1.27.0 and later; see the tab's own page for the guided version), from the command line. All three are read-only: to undo a change, use audit revert <id> --yes above, which confirms first.

• changes prints every change recorded since --since, newest first: id, when (site timezone), who, type, target, change (old -> new), group (changes made together share one group id) and where (site, or network for a change made by the network owner on a multisite network). Routine rows (preload runs, filesystem rechecks, other troubleshooting cases) are left out and counted in a final N routine events hidden line. If the record does not reach back as far as --since, a first line says where it starts.
• suspects ranks the same window for a symptom: rank, score, events (the Activity ids of the change; use them with audit revert), when, who, change in plain words and reasons (why it scored). --symptom takes one of the tab's keys: layout (the page looks broken), function (something stopped working), stale (visitors see old content), slow, images, private, other. --page narrows the ranking to one page of this site; a page on another site ends with Error: Enter a page on this site. The ranking is the plugin's own table, with no network call. For private nothing is ranked: the command prints the urgent steps instead (purge every layer, then the kill switch), because private content shown to visitors is never a walk-back.
• check <url> runs the page check for one page of this site (a full address or a path): whether the cache may serve it, the rule that decides otherwise and what it means, whether a cached copy exists and how old it is, how many page-audit findings it has and which are new, and the one-line summary the tab shows.

--since takes a span (3d, 12h, 30m) or a date-time in the site timezone (2026-11-01T10:00, 2026-11-01; a trailing Z or an offset is honoured). --format takes table (default, plain ASCII) or json. A bad --since, an unknown --symptom or another --format ends with an Error: line (exit code 1) and prints nothing else. On a site where the Troubleshooting tab is not loaded the commands end with Error: Troubleshooting is not available.

The page option is --page, not --url, for the same reason as assets above: --url is WP-CLI's own.

cdn

wp cachingout cdn status
wp cachingout cdn enable
wp cachingout cdn disable

status (also the default when you give no subcommand) prints whether CDN rewriting is on, the CDN addresses (CNAMEs), HTTPS, the content types it rewrites and the exclusions. enable and disable switch rewriting on or off and print Success: CDN enabled. / Success: CDN disabled.; nothing else changes. Set the CDN address on the CDN tab before you enable it.

version

wp cachingout version

Prints the free plugin's version on the first line and Pro <version> on the second.

On a multisite network

WP-CLI's global --url option chooses the site a command runs on. Every wp cachingout command then acts on that site only: purge clears that site's cached pages and no other (see Multisite), settings reads that site's settings, audit that site's Activity.

wp cachingout purge --url=https://example.com/shop/
wp cachingout settings export --url=https://example.com/shop/ > shop.json

• The command exists on every site where Caching Out Pro is active (network activation covers them all), and runs where a licence has switched Pro on. A site the Network Admin Sites tab shows as "Locked" answers Error: Caching Out Pro is not switched on on this site for everything but version and settings export, until a licence validates on that site.
• Without --url, WP-CLI runs on the network's main site.
• To run a command on every site, loop over WP-CLI's own site list, for example in a Linux shell: wp site list --field=url | xargs -I {} wp cachingout purge --url={}. A site where Pro is not active prints 'cachingout' is not a registered wp command and the loop goes on. To purge the whole network from the browser, use Purge every site in Network Admin.

Troubleshooting

Related

• Activity (change record)
• Import / Export
• Multisite
• Licensing