WP-CLI Commands

All commands live under wp gt-performance. They are registered from src/CLI/Command.php.

wp gt-performance <command> [<action>] [--flags]

Command	Actions	Purpose
doctor	none	Environment and integration checks
health	none	Queue, cron, storage, drop-in, configuration, purge, CSS and warming health
cache	status (default), purge, warm, warm-status, preview, install-dropin, explain, verify	Page cache operations and diagnostics
queue	run (default), status, list, pause, resume, retry, cancel	Background job control
config	export, history, diff, import, restore	Settings history, export and import
cloudflare	status (default), plan, sync, purge, disconnect	Managed cache rule and edge purges
xcloud	status (default), refresh, purge	xCloud host cache integration
database	preview (default), run	Database cleanup
operations	list (default), proposals, apply, reject	Assistant operations and settings proposals
abilities	status (default)	Whether external assistants can reach the plugin’s abilities

An unknown action is an error. Nothing falls through to a default operation, so a typo never runs sync or purge.

Pass target URLs with --page-url. WP-CLI reserves --url for choosing which site to load, so it never reaches the command. A --page-url must be a complete http or https URL on one of the site’s canonical hosts: the hosts of home_url() and site_url(), plus any added with the gt_performance_canonical_hosts filter. Any other host is refused with an error that lists the accepted ones.

doctor and health exit with status 1 when any check fails, and 0 otherwise, including when some checks are only warnings. Every other command exits 1 on an error.

After an update, the first command that touches the queue can report that the schema upgrade is incomplete. The upgrade runs in small batches; repeat the command until it goes through.

doctor

wp gt-performance doctor

Prints a check, value, status table:

Check	Pass when
PHP	8.1 or newer
WordPress	6.6 or newer
Cache directory	wp-content/cache/gt-performance is writable
Page drop-in	advanced-cache.php is owned by GT Performance (missing or conflict is a warning)
WP_CACHE	The constant is true
Redis drop-in	object-cache.php is owned by GT Performance (anything else is a warning)
Cloudflare	The integration is enabled (disabled is a warning)
xCloud	No conflict between xCloud Cloudflare Enterprise and direct Cloudflare
WP-Cron	Request spawning is on, or DISABLE_WP_CRON is set and no event is more than 15 minutes overdue

When cron events are overdue, the WP-Cron row prints a five-minute system cron line you can install. Start here when something is wrong.

Exits with status 1 when any row is fail. A warning row, such as a Redis drop-in or Cloudflare integration you do not use, still exits 0.

health

wp gt-performance health
wp gt-performance health --format=json > gt-performance-health.json

Flag	Values
--format	table (default) or json

Reads saved and local evidence only. It requests no pages. The table has label, status, value and source columns. json prints the redacted support report, the same export the Tools tab offers as a download. Labels and messages follow the site’s language when a translation is installed.

Exits with status 1 when any check fails and 0 when the worst is a warning (for example Language and currency plugins, which warns for as long as such a plugin is active).

cache

wp gt-performance cache [<action>] [--page-url=<url>] [--post=<id>] [--membership]

--page-url is accepted only by purge, explain and verify, and must be on one of the site’s canonical hosts (see above). explain and verify also require the home host. --post and --membership belong to preview.

Action	Effect
status	Prints enabled=yes\|no (the origin cache setting), mode=store\|optimize-only and dropin=owned\|missing\|conflict
purge	Without --page-url, deletes every stored page. With it, deletes that URL’s entry, its mobile variant when a separate mobile cache is on, and every query variant recorded for it. Then finishes the Cloudflare purge before reporting
warm	Queues a warm run and prints its job ID. Discovery and preloads run through the queue. Refused in optimize-only mode, where nothing is queued
warm-status	State, sitemap sources, warnings and per-status target counts of the latest warm run
preview	Lists the URLs an update to --post would purge under the current policy, with the reason for each
install-dropin	Writes the runtime configuration, installs or refreshes advanced-cache.php, and adds WP_CACHE to wp-config.php. Refuses when another plugin owns the drop-in
explain	JSON cache decision for a URL (home page by default). Read-only: no request is made
verify	Purges the URL (home page by default) at the origin and edge, fetches it twice, and records a purge receipt. This is not read-only

wp gt-performance cache explain --page-url=https://example.com/pricing/
wp gt-performance cache purge --page-url=https://example.com/pricing/
wp gt-performance cache preview --post=42
wp gt-performance cache preview --post=42 --membership
wp gt-performance cache warm && wp gt-performance queue run

explain returns cacheable, the reason, the cache key and hash, the origin entry state (fresh, stale, expired or missing) with its timestamps, and what the managed Cloudflare rule would do with the same request, including whether it disagrees with the origin. It is the most useful command when a page will not cache. See Diagnostics.

A full purge also fires the plugin’s full-purge event, so Cloudflare (this site’s hostnames) and xCloud are purged when connected, and a warm run is queued when warming is on and the site is in store mode. If the local purge succeeds and Cloudflare fails, the command exits with an error that says so.

preview without --membership previews a content edit. --membership previews a publication, withdrawal or term change instead. The output ends with how many cached pages have recorded dependencies. See Purging.

warm only queues work. Run wp gt-performance queue run, or let cron do it. With warming turned off, or URLs per warming batch at 0, a run discovers URLs but skips every preload. In optimize-only mode warm exits with an error and queues nothing, because the host’s cache stores pages. See Cache Warming.

queue

wp gt-performance queue [<action>] [--limit=<number>] [--status=<status>] [--id=<id>]

Action	Effect
run	Processes due jobs. --limit defaults to 20
status	Counts of pending, running, failed, complete and cancelled jobs, plus paused and ready
list	Recent jobs with id, type, status, attempts, available_at and last_error. --limit defaults to 20; --status filters by pending, running, failed, complete or cancelled
pause	Pauses optional work. Purge jobs keep running
resume	Resumes the queue
retry	Requeues a failed job. Requires --id
cancel	Cancels a pending job, or requests cancellation of a running one. Requires --id

wp gt-performance queue run --limit=50
wp gt-performance queue list --status=failed
wp gt-performance queue retry --id=1234

The queue normally runs from cron every minute. Run it by hand after cache warm if cron is unreliable, or from a real system cron. Only one runner works at a time, so a second queue run while another is active processes nothing. A run processes up to --limit jobs (100 at most) and stops early after 20 seconds of work. A failed job is retried automatically, up to three attempts in total. See Tools for the same controls in the admin.

config

wp gt-performance config <action> [<target>] [--file=<path>] [--expected-hash=<hash>] [--dry-run]

Action	Target	Effect
export	none	Prints the portable settings as JSON, or writes them to --file
history	none	Lists saved revisions: id, saved, source, user, and how many settings differ from the current ones. Also prints the current settings hash
diff	Revision ID (or a unique prefix) or an export file	Shows what applying it would change. Changes nothing
import	Export file	Applies the file’s settings
restore	Revision ID or unique prefix	Applies that revision’s settings

Flag	Applies to	Effect
--file	export	Output path
--dry-run	import, restore	Show the changes without applying them
--expected-hash	import, restore	Refuse unless the current settings still have this hash, so two people cannot overwrite each other

wp gt-performance config export --file=gt-performance.json
wp gt-performance config import gt-performance.json --dry-run
wp gt-performance config history
wp gt-performance config restore 3f2a --expected-hash=<hash from history>

Credentials, the cache generation, agent and adviser access, Redis, xCloud, and Cloudflare identity (enabled, auth mode, domain, zone) are never exported, imported or restored. Only local settings change. When Cloudflare is enabled and a cache or cloudflare value changes, the command warns you to run wp gt-performance cloudflare sync. See Tools and Settings Reference.

cloudflare

wp gt-performance cloudflare [<action>] [--page-url=<url>] [--forget]

Action	Effect
status	Prints enabled, auth mode, domain and whether a zone ID is configured
plan	Prints, as JSON, what sync would change in this site’s managed Cache Rule. Changes nothing
sync	Creates or updates this site’s managed Cache Rule, purges this site’s hostnames at Cloudflare, then saves the zone ID and turns the integration on. Other rules in the zone are preserved. A failed purge is a warning, not an error
purge	Purges this site’s hostnames, or only --page-url
disconnect	Deletes this site’s managed Cache Rule (no other rule), purges this site’s hostnames, and turns the integration off. The credentials and zone ID stay. With --forget, also deletes the saved token, Global API Key, account email and zone ID. A failed purge is a warning

wp gt-performance cloudflare disconnect
wp gt-performance cloudflare disconnect --forget

When no zone ID is saved, plan, sync and purge look the zone up from the configured domain first. sync refuses to run while xCloud’s Cloudflare Enterprise add-on owns the edge. --page-url is accepted only by purge, and --forget only by disconnect. See Cloudflare.

Connection diagnostics (the stage-by-stage check) run from the Cloudflare tab, not from WP-CLI. See Cloudflare.

xcloud

wp gt-performance xcloud [<action>] [--page-url=<url>]

Action	Effect
status	Prints the saved state: enabled, domain, site, page cache, Cloudflare Enterprise, enterprise_purge (xcloud-plugin, unusable or not-installed), free edge cache, Enterprise edge traffic over 12 hours, last check
refresh	Reads the site’s cache state from the xCloud API, saves it, turns the integration on, and prints the result as JSON
purge	With xCloud’s purge plugin, purges Cloudflare Enterprise first (the whole site, or one page with --page-url), then the narrowest host cache layer when an API token is connected. Without the plugin, Enterprise purge fails closed

wp gt-performance doctor reports Cloudflare: paused (xCloud Enterprise) and xCloud: enterprise purge while xCloud’s purge plugin is installed.

See xCloud.

database

wp gt-performance database          # preview
wp gt-performance database run
wp gt-performance database run --all-revisions

preview prints row counts for every task: revisions, auto_drafts, spam_comments, trashed_posts, trashed_comments, expired_transients, all_transients, and optimize_tables (tables reporting reclaimable space). It deletes nothing.

run executes the tasks saved in the Database tab’s Scheduled tasks list, to completion, in the current process. Like a scheduled run, it keeps the newest Scheduled revisions to retain per post when revisions is selected, so a server cron that calls it matches the built-in schedule. --all-revisions deletes every revision instead, as the Run selected optimization button does; it is accepted only by run. The output lists all tasks, with 0 for those not selected. The admin’s manual cleanup and the schedule run through the background queue instead. See Database Cleanup.

operations

wp gt-performance operations [<action>] [<id>]

Action	Effect
list	The 50 most recent assistant operations with their state, target and user
proposals	Open settings proposals, with each proposed change
apply <id>	Applies an open proposal and prints the changes
reject <id>	Rejects an open proposal

See AI and MCP.

abilities

wp gt-performance abilities status

Reports whether the WordPress Abilities API is available (WordPress 6.9+), the agent access mode (off, read or operate), the MCP Adapter version and endpoint when the adapter is active, and the list of GT Performance abilities. See AI and MCP.

Running WP-CLI where PHP is unusual

Some hosts ship a command-line PHP without mysqli, so a bare wp fails while the site itself is fine. Run WP-CLI on the binary the site uses:

php8.3 $(which wp) gt-performance doctor
# or, on LiteSpeed
/usr/local/lsws/lsphp83/bin/php $(which wp) gt-performance doctor