home / skills / automattic / agent-skills / wp-wpcli-and-ops
This skill helps you manage WordPress operations via WP-CLI safely, including search-replace, backups, updates, and multisite scripting.
npx playbooks add skill automattic/agent-skills --skill wp-wpcli-and-opsReview the files below or copy the command above to add this skill to your agents.
---
name: wp-wpcli-and-ops
description: "Use when working with WP-CLI (wp) for WordPress operations: safe search-replace, db export/import, plugin/theme/user/content management, cron, cache flushing, multisite, and scripting/automation with wp-cli.yml."
compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Requires WP-CLI in the execution environment."
---
# WP-CLI and Ops
## When to use
Use this skill when the task involves WordPress operational work via WP-CLI, including:
- `wp search-replace` (URL changes, domain migrations, protocol switch)
- DB export/import, resets, and inspections (`wp db *`)
- plugin/theme install/activate/update, language packs
- cron event listing/running
- cache/rewrite flushing
- multisite operations (`wp site *`, `--url`, `--network`)
- building repeatable scripts (`wp-cli.yml`, shell scripts, CI jobs)
## Inputs required
- Where WP-CLI will run (local dev, staging, production) and whether it’s safe to run.
- How to target the correct site root:
- `--path=<wordpress-root>` and (multisite) `--url=<site-url>`
- Whether this is multisite and whether commands should run network-wide.
- Any constraints (no downtime, no DB writes, maintenance window).
## Procedure
### 0) Guardrails: confirm environment and blast radius
WP-CLI commands can be destructive. Before running anything that writes:
1. Confirm environment (dev/staging/prod).
2. Confirm targeting (path/url) so you don’t hit the wrong site.
3. Make a backup when performing risky operations.
Read:
- `references/safety.md`
### 1) Inspect WP-CLI and site targeting (deterministic)
Run the inspector:
- `node skills/wp-wpcli-and-ops/scripts/wpcli_inspect.mjs --path=<path> [--url=<url>]`
If WP-CLI isn’t available, fall back to installing it via the project’s documented tooling (Composer, container, or system package), or ask for the expected execution environment.
### 2) Choose the right workflow
#### A) Safe URL/domain migration (`search-replace`)
Follow a safe sequence:
1. `wp db export` (backup)
2. `wp search-replace --dry-run` (review impact)
3. Run the real replace with appropriate flags
4. Flush caches/rewrite if needed
Read:
- `references/search-replace.md`
#### B) Plugin/theme operations
Use `wp plugin *` / `wp theme *` and confirm you’re acting on the intended site (and network) first.
Read:
- `references/packages-and-updates.md`
#### C) Cron and queues
Inspect cron state and run individual events for debugging rather than “run everything blindly”.
Read:
- `references/cron-and-cache.md`
#### D) Multisite operations
Multisite changes can affect many sites. Always decide whether you’re operating:
- on a single site (`--url=`), or
- network-wide (`--network` / iterating sites)
Read:
- `references/multisite.md`
### 3) Automation patterns (scripts + wp-cli.yml)
For repeatable ops, prefer:
- `wp-cli.yml` for defaults (path/url, PHP memory limits)
- shell scripts that log commands and stop on error
- CI jobs that run read-only checks by default
Read:
- `references/automation.md`
## Verification
- Re-run `wpcli_inspect` after changes that could affect targeting or config.
- Confirm intended side effects:
- correct URLs updated
- plugins/themes in expected state
- cron/caches flushed where needed
- If there’s a health check endpoint or smoke test suite, run it after ops changes.
## Failure modes / debugging
- “Error: This does not seem to be a WordPress installation.”
- wrong `--path`, wrong container, or missing `wp-config.php`
- Multisite commands affecting the wrong site
- missing `--url` or wrong URL
- Search-replace causes unexpected serialization issues
- wrong flags or changing serialized data unsafely
See:
- `references/debugging.md`
## Escalation
- If you cannot confirm environment safety, do not run write operations.
- If the repo uses containerized tooling (Docker/wp-env) but you can’t access it, ask for the intended command runner or CI job.
This skill provides operational guidance and scripts for using WP-CLI to manage WordPress sites safely and repeatably. It focuses on search-replace migrations, database export/import, plugin/theme/user management, cron and cache handling, multisite concerns, and automation with wp-cli.yml. Use it to standardize routine ops and reduce blast radius for destructive commands.
The skill inspects the execution environment and WP-CLI availability, then chooses a targeted workflow (safe search-replace, package operations, cron/queue inspection, multisite handling). It includes an inspector script to verify path and URL targeting, recommended sequences for backups and dry-runs, and patterns for scripting and CI-safe jobs. After changes, it verifies side effects and re-runs inspections.
What if WP-CLI isn't available on the host?
Detect with the inspector; if missing, install via the project's documented tooling (Composer, container image, or package) or ask for the intended execution environment before proceeding.
How do I avoid affecting other sites on a multisite network?
Specify --url for a single site or use --network when you explicitly mean network-wide changes; test on a single site first and review scripts carefully.