One-Command Site Optimization
xSpeed Cache can tune your site in a single step. wp xspeed optimize on the command line — or the optimize_site tool from a connected AI assistant — measures your site, turns on the settings that help, checks the page still renders after each one, and undoes anything that breaks it.
What this does
Tuning a caching plugin by hand is a loop: change a setting, load the site, look at it, keep or revert, repeat. This runs that loop for you, in five phases:
- Diagnose. Read the current settings and build an ordered plan of what is still off and worth turning on. A setting already enabled is not a step — it is reported as skipped, not as work done.
- Measure. Take a cached-vs-uncached benchmark, and capture a baseline sample of your home page: HTTP status, page size, how many stylesheets and scripts it links, its title, and whether the document is complete.
- Apply. Write one setting, purge the cache, and move on. Never two at once.
- Verify. Re-fetch the page after each change and compare it to the baseline. If it looks broken, that one setting is reverted immediately and the reason is recorded.
- Re-measure and report. Benchmark again, then report what was applied, what was undone and why, what could still be tried, and what no caching plugin can fix.
Because the changes are applied one at a time and each is verified before the next, a failure is always attributable to the change that just happened — and reverting one setting is enough to recover.
Why use it
- It is the whole tuning loop in one command, including the part people skip: checking the site afterwards.
- It cannot leave you with a broken page from a setting it chose, because anything that fails verification is put back.
- It tells you the truth when there is nothing left to do. A site already fully tuned gets “everything that can be turned on safely is already on”, plus the list of problems that are outside a caching plugin’s reach — not a green tick.
Requirements
- xSpeed Cache (free) — this is not a Pro feature.
- WP-CLI for the command line, or a connected MCP client for
optimize_site. See Connecting AI Agents with the MCP Server. - The site must be reachable over HTTP from itself. If the baseline page cannot be loaded, the run refuses to change anything rather than working blind.
How to run it
From the command line:
wp xspeed optimize
wp xspeed optimize --dry-run
wp xspeed optimize --aggressiveness=safe
wp xspeed optimize --budget=240| Option | What it does | Default |
|---|---|---|
--aggressiveness | safe, standard, or aggressive — how far the run may go | standard |
--dry-run | Print the plan and stop. Changes nothing. | Off |
--budget | Seconds to spend before stopping between steps | 120 |
From an AI assistant, ask for it in plain language (“make this site faster”) and the agent calls optimize_site. It takes the same two main arguments: aggressiveness and dry_run. It is a write tool, so a read-only MCP connection cannot run it.
Tip: Start with
--dry-run. It returns the ordered plan, the steps it would skip and why, and the same diagnosis a real run ends with — without touching a single setting.
What it is allowed to change
Every setting an automated run may touch is classified by risk, and the run applies only the tiers its aggressiveness allows.
| Tier | Applied at | What is in it |
|---|---|---|
| Safe | Every run | Page caching, GZIP, browser-cache headers, minify HTML, minify CSS, stop loading admin icons for visitors, disable XML-RPC |
| Standard | standard and aggressive | Minify JavaScript, defer JavaScript, lazy-load images, add missing image dimensions, combine CSS, combine JavaScript |
| Aggressive | aggressive only | Delay JavaScript until interaction, load CSS asynchronously, remove jQuery Migrate |
Two details in that table are decisions rather than taste:
- Combining runs last. It is the change most likely to alter how a page renders, so it is attempted only after every other step has been applied and verified.
- Aggressive is opt-in because its failures are invisible to the check. Verification reads HTML; it does not run JavaScript. Removing jQuery Migrate once broke a live page whose HTML arrived complete and the right size — only the browser console showed it. Anything that can fail that way stays behind an explicit yes.
Settings that edit your content, switch off another plugin, or restrict endpoints your theme may depend on are never applied by an automated run, at any aggressiveness.
How a change is verified
After each setting, the page is fetched anonymously and uncached — a logged-in request never sees the cached path, and a cached response would show the page as it was before the change. The fresh sample is compared against the baseline, and the change is reverted if any of these is true:
- The page no longer returns HTTP 200.
- The document stops part-way through (no closing
</body>), which usually means a PHP fatal. - The page size moved more than 50% in either direction — far past what optimization does.
- Every stylesheet disappeared, or every script did.
- The page title changed, which suggests an error page rather than your site.
The tolerances are deliberately wide. Minification legitimately removes a chunk of a page and combining rewrites a head full of tags; neither is damage. What this catches is the catastrophic case.
What the report tells you
| Field | What it means |
|---|---|
| Applied | Settings that were written and passed verification |
| Reverted | Settings that were put back, each with the reason the page failed |
| Skipped | Already enabled, or needs a higher aggressiveness than this run |
| Score | Your last recorded performance audit — the run does not spend your PageSpeed quota |
| Next steps | Riskier settings that could still help, each with its real failure mode in plain words. Not applied automatically. |
| Unfixable | Problems outside what caching can reach — an old PHP version, a server snippet only your host can paste, a poor LCP/CLS/TBT caused by the page’s own content |
That last row is the point of the feature as much as the first. A site can be fully cached, with every optimization on, and still score badly because of a heavy hero video, hotlinked images, or a page builder emitting thousands of DOM elements. Those are named, with who can act on them, instead of being left out of a success message.
Note: An AI assistant is instructed to relay all three of the score, the next steps (with their risks) and the unfixable list, and to ask before running again in
aggressivemode. If your assistant offers a riskier setting, that offer is coming from this report.
Best practices
- Run
--dry-runfirst on a site you have not tuned before. - Let the standard run finish before considering
aggressive, and read the stated risk for each remaining setting rather than enabling them all. - Aggressive settings deserve a human look at the rendered page in a browser, since the automatic check cannot execute JavaScript.
- After a run, warm the cache (
wp xspeed preloader start) so the pages your visitors hit are already built.
Troubleshooting
The run refused to start and said it could not take a baseline. The site could not be loaded over HTTP from itself. That is deliberate: with no baseline there is no way to tell a broken page from a working one. Check that the site answers a plain request (a firewall, basic auth, or a challenge page will block it) and try again.
It reported no changes. Everything in the allowed tiers was already on. Read the score, next steps, and unfixable sections of the same report — that is where the remaining answer is.
A setting was applied and then undone. The page failed verification with that setting on, and the report names the check that failed. That setting is not suitable for this site as it stands; the cause is usually a theme or plugin conflict rather than the setting itself.
The score did not change after the run.
The score comes from your last stored audit, not a fresh one. Run a new audit — from the dashboard, or wp xspeed psi --url=... --force with Pro — to see the effect.
FAQ
Does it need an AI provider or a Pro licence? No. The command and the MCP tool are both in the free plugin, and neither calls out to an AI model. An assistant is one way to drive it, not a requirement.
Can it change a setting I deliberately turned off?
Yes, if that setting is in an allowed tier — it plans from what is currently off. Use --aggressiveness=safe to keep it to removals and server-side wins, or --dry-run to see the plan first.
Does it run a PageSpeed test? No. It runs xSpeed Cache’s own cached-vs-uncached benchmark and reads your most recent stored audit for the score, so a run never quietly spends your PageSpeed allowance.
Is the whole thing reversible? Everything it applied is an ordinary xSpeed Cache setting you can switch off again in the dashboard. The report lists exactly what changed.