Docs › Spark Speed

WP-CLI and MCP: every command and tool

This page describes everything you can do in Spark Speed 0.73.2 without an admin screen: the WP-CLI commands on the server and the MCP tools an AI assistant such as Claude or ChatGPT uses to work with your site. Meant for administrators and agencies who work with the command line or an AI assistant; you do not need it for day-to-day management.

Tested with Spark Speed 0.73.2 on 10 October 2026 · WordPress 7.1, WooCommerce 11.2, Breakdance 3.0 beta, PHP 8.3 on Apache · By Kevin, founder of SparkCore

In short

Every command starts with wp spark-speed and runs on the server
mcp token and ai apply only exist with a valid licence; diagnostics refuses without one
MCP needs a valid licence and an authorized client acting as an administrator
start_optimization needs an open dashboard in the browser for the browser check

Status and cache

Quickly see how the cache is doing, empty it and check what visitors receive.

wp spark-speed status

Basic · Manual, via WP-CLI

What it does: Shows the cache state in five lines: which plugin owns the cache drop-in (the file WordPress loads early for the page cache), whether WP_CACHE is on, how many pages are cached, how many addresses are queued and whether the optional local worker is reachable. Handy for a quick look without opening wp-admin.
When to use it: After an update, a migration or a purge, or in a monitoring script.
How to check the effect: The output is in English: Drop-in owner, WP_CACHE, Cached pages, Queue pending, Worker. Worker : OFFLINE is normal: the worker is optional and not in the zip; Spark then uses the PHP route.
Example: wp spark-speed status
How to undo: Nothing to undo: the command only reads.

wp spark-speed purge

Basic · Manual, via WP-CLI

What it does: Empties the whole page cache. Pages are then rebuilt on the next visit or by the cache warmer.
When to use it: When visitors see an outdated version, or after a large change to the theme or settings.
How to check the effect: You see Page cache purged. With wp spark-speed status you see Cached pages drop.
Example: wp spark-speed purge
Watch out: Until the cache is rebuilt, first visits are slower. This does not empty the object cache; that is flush-object-cache.
How to undo: Cannot be undone. Rebuild the cache with wp spark-speed optimize --all followed by wp spark-speed warm.

wp spark-speed flush-object-cache

Advanced · Manual, via WP-CLI

What it does: Empties the object cache (the temporary store of database results, for example in Redis, Memcached, APCu or SQLite) that runs through Spark's object cache drop-in. This is deliberately separate from the page cache.
When to use it: When you suspect stale data in the object cache. Spark does not empty the object cache automatically.
Requirements: A working Spark object cache. Otherwise you get a warning.
How to check the effect: A success message, or a warning when there was nothing to flush.
Example: wp spark-speed flush-object-cache
Watch out: Right after flushing, WordPress asks more from the database again.
How to undo: Not needed: the object cache refills itself.

wp spark-speed verify-cache

Advanced · Manual, via WP-CLI

What it does: Fetches one page of your own site as a desktop and as a mobile visitor and returns a verdict in JSON: which cache status was served and whether it matches the current code and settings.
When to use it: After a change, to check that visitors get the new cached version.
Requirements: --page with a full address on this site, without a query string. Without --page the command stops with an error.
How to check the effect: The JSON contains ok. The exit code is 0 when everything matches and 2 when it does not, so you can use it in a script.
Example: wp spark-speed verify-cache --page=https://example.com/product/example/
How to undo: Nothing to undo: the command only reads.

Building the cache

Optimize pages, work through the queue and follow or resume the cache build. You see the same build in the admin on the Cache tab.

wp spark-speed optimize

Advanced · Manual, via WP-CLI

What it does: Without extra options this rebuilds the home page, optimized and cached per device. With --page=<address> you do that for one page. With --all you queue every page of the site; the actual work is then done with process or warm.
When to use it: After a purge, or when you want one important page ready right away.
Requirements: Use --page, not --url: WP-CLI already reserves --url.
How to check the effect: One line per device with the result, for example ok or a reason why it did not work. With --all you see how many addresses were queued.
Example: wp spark-speed optimize --page=https://example.com/shop/
Watch out: When the emergency brake (safe mode) is on or optimization is switched off, pages are only cached, not optimized.
How to undo: Purge that page or the whole cache.

wp spark-speed process

Advanced · Manual, via WP-CLI

What it does: Processes part of the queue now, 20 addresses by default. It uses the same lock as the background processing, so they never get in each other's way.
When to use it: To work through a filled queue in steps, for example after optimize --all.
Requirements: A queue with addresses. Change the number with --limit=<number>.
How to check the effect: One line per address with the result per device, and finally Batch done. Remaining: N.
Example: wp spark-speed process --limit=50
Watch out: Loads the server while it runs. If another runner holds the lock, nothing is processed.
How to undo: Not applicable.

wp spark-speed warm

Advanced · Manual, via WP-CLI

What it does: Works through the whole queue until it is empty, in batches of 25 by default. When there is no progress it finds out why. If another runner is busy it says so and stops; with --wait it waits up to 15 minutes for the lock.
When to use it: On low-traffic sites where WP-Cron does not run often enough by itself, or after a full purge.
Requirements: The site must be able to reach itself (loopback), because the warmer fetches your own pages. Change the batch size with --batch=<number>.
How to check the effect: Per round remaining: N (cached M) and a summary. The exit code is 0 when the queue is empty, 1 when work is left over and 2 when the warmer is blocked or stuck.
Example: wp spark-speed warm --wait
Watch out: Can take a long time and loads the server. A site in maintenance mode or behind bot protection that returns 403 makes pages fail.
How to undo: Stop with Ctrl+C. You can empty the built cache with purge.

wp spark-speed warm-status

Basic · Manual, via WP-CLI

What it does: Shows how the cache build is doing: the state and since when, how long nothing happened, the reason, the queue, cached pages against the total, any pause, failed addresses and the last test. With --json you get everything as JSON.
When to use it: When the build is not progressing, or in a monitor that watches the exit code.
How to check the effect: The lines have Dutch labels (stand, sinds, wachtrij, gecached, pauze, fails, laatste toets). Exit code 0 is healthy, 1 is a known cause, 2 is stuck and 3 means the state cannot be determined.
Example: wp spark-speed warm-status --json
How to undo: Nothing to undo: the command only reads.

wp spark-speed warm-hervat

Advanced · Manual, via WP-CLI

What it does: Tests a paused cache build with a real attempt on the first address in the queue and resumes the build when the site answers correctly. This is the command line version of the button that resumes the build on the Cache tab.
When to use it: After you fixed the cause of a pause, for example a loopback error or bot protection.
Requirements: An open pause. Without a pause it reports Er stond geen pauze open..
How to check the effect: When it resumes you see Hervat. with the queue and the number of cached pages (exit code 0). When it does not, a warning Niet hervat: <reason> (exit code 1). Check afterwards with warm-status.
Example: wp spark-speed warm-hervat
Watch out: If the site still returns errors, the pause stays.
How to undo: Not applicable.

Shop, customers and load plan

These commands control features you also find in the admin, with the same test first. The subcommands are Dutch words: aan (on), uit (off), proef (test), legen (empty).

wp spark-speed winkelwagen

Advanced · Manual, via WP-CLI

What it does: Controls the cache for visitors with a filled cart, the same feature as Cached pages with a filled cart on the Cart and logged-in customers card. status (default) shows the state and the last test. proef runs the test. aan switches it on and uit switches it off.
When to use it: On a WooCommerce shop where buyers with something in their cart would otherwise get a fully rendered, slow page every time.
Requirements: WooCommerce. aan only works after a successful test, or with --bevestigd after you reviewed a difference that was found.
How to check the effect: The test reports the outcome, the number of pages, whether the cart script is needed and which differences were found. When switching on you see Winkelwagencache aan; de paginacache is geleegd..
Example: wp spark-speed winkelwagen proef
Watch out: Switching on empties the whole page cache. If you wrongly approve a difference with --bevestigd, personal content can end up in shared pages.
How to undo: wp spark-speed winkelwagen uit
Technical name: woo_cart_cache

wp spark-speed klantcache

Advanced · Manual, via WP-CLI

What it does: Controls the own cache for logged-in customers, the same feature as Own cache for logged-in customers on the Cart and logged-in customers card. status (default) shows the state, the number of sessions with their own copy and whether it can be switched on. aan (on), uit (off and emptied) and legen (empties all customer copies).
When to use it: When logged-in customers get a fully rendered page on every click.
Requirements: If the feature cannot be switched on on this site, aan refuses and gives the reason. Customer roles only, never administrators. A copy is at most 8 hours old.
How to check the effect: Messages such as Klantcache aan. or Klantcache uit en geleegd., and with status a line with stand, sessies met eigen kopieen and kan aan.
Example: wp spark-speed klantcache status
Watch out: Every logged-in session gets its own copies, so disk use grows with the number of customers.
How to undo: wp spark-speed klantcache uit
Technical name: klant_cache

wp spark-speed laadplan

Advanced · Manual, via WP-CLI

What it does: Controls the load plan: plugins that load code on the front end without changing the page are skipped there, after proof. This is the same feature as the Front-end load plan card under Diagnostics. kandidaten lists plugins with their number of files and the last test. proef <plugin> tests whether the page stays the same without that plugin. weglaten <plugin> skips it on the front end. laden <plugin> loads it again. aan and uit switch the plan on or off. status shows the state.
When to use it: When a plugin loads a lot of front-end code that your visitors do not need.
Requirements: weglaten is only allowed after a test with outcome gelijk (equal), or with --bevestigd after you reviewed a difference yourself. Applies to anonymous visitors only. The plan is off by default.
How to check the effect: A line with modus, weggelaten op de voorkant and the owner of the must-use plugin (a plugin WordPress always loads first).
Example: wp spark-speed laadplan proef contact-form-7
Watch out: An identical page does not prove that a plugin does no invisible work, such as security, server-side tracking or logging. Only skip plugins you know.
How to undo: wp spark-speed laadplan laden <plugin> or wp spark-speed laadplan uit.

Importing and analysing measurements

For people who measure themselves: import browser measurements so Spark prioritises exactly the right image and fonts, and look at the critical path.

wp spark-speed image-hint

Advanced · Manual, via WP-CLI

What it does: Imports a measurement from a real browser that records which image on a page is the LCP (the largest visible element during loading). While the measurement is valid, the cached page loads exactly that image with priority.
When to use it: When Spark picks the wrong main image by itself.
Requirements: A JSON file of at most 16 KB from an administrator scan. The collector scripts named on the Measured choices card are not included in the plugin zip.
How to check the effect: On success Observation stored; refresh and verify the affected cache variants.. If the address, age, settings or LCP evidence do not match, the measurement is rejected. Then refresh the affected page and check with verify-cache.
Example: wp spark-speed image-hint --file=lcp.json
Watch out: The command does not purge the cache or change settings. Measurements expire after six hours and on changes to content, media, menus, theme, plugins or settings.
How to undo: There is no separate command to remove a measurement; after it expires the automatic choice applies again.

wp spark-speed font-hint

Advanced · Manual, via WP-CLI

What it does: Imports a measurement of the local fonts that are actually loaded visibly, so only those are preloaded.
When to use it: When too many or the wrong fonts are preloaded.
Requirements: A JSON file of at most 16 KB. The collector scripts named on the Measured choices card are not included in the plugin zip.
How to check the effect: Font observation stored; refresh and verify affected cache variants. or Font observation rejected..
Example: wp spark-speed font-hint --file=fonts.json
Watch out: An outdated measurement can preload the wrong font. Measurements expire after six hours and on changes to the site.
How to undo: No separate command; after it expires the automatic choice applies again.

wp spark-speed font-metrics

Advanced · Manual, via WP-CLI

What it does: Imports measured sizes for the fallback font, so text shifts less while the web font loads.
When to use it: When text visibly shifts as soon as the web font arrives.
Requirements: A JSON file of at most 16 KB. Values out of range are rejected. The collector scripts named on the Measured choices card are not included in the plugin zip.
How to check the effect: Font metrics stored; refresh the affected cache variants and verify the layout. Then look at the page.
Example: wp spark-speed font-metrics --file=metrics.json
Watch out: Wrong sizes can make text shift instead. Check the layout.
How to undo: No separate command found; purge the affected pages.

wp spark-speed kritiek-pad

Advanced · Manual, via WP-CLI

What it does: Shows what has to load before the LCP (the critical path). With --file it analyses a Lighthouse JSON (a DevTools export or a PageSpeed response) and stores the result for the What keeps the score from green card under Diagnostics. With --page it fetches the page as a mobile visitor and estimates from the HTML, without timings.
When to use it: When you want to know what is holding the score back.
Requirements: One of the two options. The Lighthouse file must contain the network requests. --page only works with addresses on this site.
How to check the effect: Compact JSON in the terminal.
Example: wp spark-speed kritiek-pad --file=lighthouse.json
How to undo: Not needed: the command changes nothing else on the site.

Commands that need a valid licence

Spark Speed has one licence level. The commands mcp token and ai apply only exist while the licence is valid (or in the 14-day grace period); diagnostics always exists but refuses without a valid licence.

wp spark-speed diagnostics

Advanced · Manual, via WP-CLI · works only with a valid licence

What it does: Prints the diagnostics report as JSON (server, PHP, cache, plugins), or saves it to a file with --save=<path>. It is the same report as Download diagnostic report in the admin.
When to use it: For support, or to hand to an AI.
Requirements: A valid licence. The command also exists without a licence, but then refuses with an error.
How to check the effect: JSON in the terminal, or Saved to <path>.
Example: wp spark-speed diagnostics --save=spark-report.json
Watch out: The file contains server and settings details. Treat it as confidential.
How to undo: Delete the file.

wp spark-speed mcp token

Advanced · Manual, via WP-CLI · only with a valid licence

What it does: Manages MCP keys from the command line. create makes a new key and shows it once. list shows the keys without the secret. revoke <id> revokes a key. Use --label to name the key (WP-CLI by default). This is the same as Create key on the Connect Claude or ChatGPT (MCP) card.
When to use it: When you want to connect an AI program on your own computer, such as Claude Code, to the site.
Requirements: Only exists while the licence is valid. You must pass --user=<admin> for a user with administrator rights. create refuses to print to a screen: pipe the output straight into your password manager or secret store. At most five keys.
How to check the effect: list shows per key an id, a hint (first and last four characters), name, owner, creation time and last use.
Example: wp spark-speed mcp token list --user=admin
Watch out: A key can do everything the MCP tools can, acting as the administrator who owns it. A lost key cannot be recovered, only revoked. If the owner loses administrator rights, the key stops working.
How to undo: wp spark-speed mcp token revoke <id> --user=admin (the id, not the key itself).

wp spark-speed ai apply

Advanced · Manual, via WP-CLI · only with a valid licence

What it does: Applies a configuration proposal from an AI through the same safety gate as the MCP tool apply_config: forbidden and site-bound settings are rejected, at most one risky switch is turned on at a time and every change gets a change_id. The proposal comes from --file or from standard input.
When to use it: When you made a proposal with an AI and want to apply it in a controlled way without opening the admin.
Requirements: Only exists while the licence is valid. --user=<admin> with administrator rights. The proposal is JSON of at most 64 KB.
How to check the effect: JSON with among others applied, change_id, changed, rejected and next_step. Then check the site on mobile: menu, sliders, forms and cart.
Example: wp spark-speed ai apply --file=proposal.json --json --user=admin
Watch out: A risky setting can break the front end. After every successful change the cache is rebuilt, which loads the server for a while.
How to undo: There is no WP-CLI command to undo. Use the MCP tool revert_change with the change_id, or set the setting back in the admin.

MCP: connecting and requirements

What you need before an AI assistant can use the tools below.

MCP-koppeling

Advanced · No switch: active while the licence is valid

What it does: MCP (Model Context Protocol) is a standard that lets an AI assistant such as Claude or ChatGPT work with your site through fixed tools. Spark Speed has its own MCP address in WordPress. It only gives the AI the tools listed below: measuring, changing settings, undoing and purging the cache, no server access.
Requirements: A valid licence, and an authorized client that acts as an administrator. There are three ways: your own key (via Create key or wp spark-speed mcp token) in the X-Spark-Token header or as a Bearer token; a WordPress application password of an administrator; or the connector from Claude.ai or ChatGPT, where you sign in to WordPress and grant access. Without a valid licence the address refuses every request.
How to check the effect: The address and the lines for Claude Code and Claude Desktop are on the Connect Claude or ChatGPT (MCP) card on the Optimization tab. After the first request your key shows a last-used time there.
Example: claude mcp add --transport http spark-speed https://example.com/wp-json/spark-speed/v1/mcp --header "X-Spark-Token: <key>"
Watch out: Each key or user is allowed at most 120 requests per minute. A request from a browser on another domain is refused. An AI can never change some settings, including the emergency brake, automatic rollback and the settings that belong to this server.
How to undo: Revoke a key or connection on the same card, or with wp spark-speed mcp token revoke.

MCP tools that only read

These tools change nothing on your site. An AI uses them to measure and to back up a proposal.

get_optimization_guide

Basic · Manual, via MCP · read only

What it does: Returns the optimization playbook: the workflow, what every setting does, which settings are risky and how to verify. The same playbook is included in the diagnostics report.
When to use it: First in a conversation, so the AI knows how Spark Speed works.
How to check the effect: Plain text, not JSON.
Example: Ask: "Read the Spark Speed guide first."
How to undo: Nothing to undo: this tool only reads.

get_site_overview

Basic · Manual, via MCP · read only

What it does: Returns an overview: site address, plugin, WordPress and PHP versions, the detected builder, WooCommerce and host, cache coverage, the main switches and the latest changes.
When to use it: At the start of every session.
How to check the effect: JSON with among others the version and the switches.
Example: Ask: "Give me an overview of my site in Spark Speed."
How to undo: Nothing to undo: this tool only reads.