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:
- Confirm environment (dev/staging/prod).
- Confirm targeting (path/url) so you don’t hit the wrong site.
- Make a backup when performing risky operations.
Read:
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:
wp db export (backup)
wp search-replace --dry-run (review impact)
- Run the real replace with appropriate flags
- 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:
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:
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:
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.
1---
2name: wp-wpcli-and-ops
3description: "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."
4compatibility: "Targets WordPress 7.0+ (PHP 7.4.0+). Requires WP-CLI in the execution environment."
5metadata:
6 source: https://skillmd.com/skills/wordpress/wp-wpcli-and-ops
7---
8
9# WP-CLI and Ops
10
11## When to use
12
13Use this skill when the task involves WordPress operational work via WP-CLI, including:
14
15- `wp search-replace` (URL changes, domain migrations, protocol switch)
16- DB export/import, resets, and inspections (`wp db *`)
17- plugin/theme install/activate/update, language packs
18- cron event listing/running
19- cache/rewrite flushing
20- multisite operations (`wp site *`, `--url`, `--network`)
21- building repeatable scripts (`wp-cli.yml`, shell scripts, CI jobs)
22
23## Inputs required
24
25- Where WP-CLI will run (local dev, staging, production) and whether it’s safe to run.
26- How to target the correct site root:
27 - `--path=<wordpress-root>` and (multisite) `--url=<site-url>`
28- Whether this is multisite and whether commands should run network-wide.
29- Any constraints (no downtime, no DB writes, maintenance window).
30
31## Procedure
32
33### 0) Guardrails: confirm environment and blast radius
34
35WP-CLI commands can be destructive. Before running anything that writes:
36
371. Confirm environment (dev/staging/prod).
382. Confirm targeting (path/url) so you don’t hit the wrong site.
393. Make a backup when performing risky operations.
40
41Read:
42- `references/safety.md`
43
44### 1) Inspect WP-CLI and site targeting (deterministic)
45
46Run the inspector:
47
48- `node skills/wp-wpcli-and-ops/scripts/wpcli_inspect.mjs --path=<path> [--url=<url>]`
49
50If 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.
51
52### 2) Choose the right workflow
53
54#### A) Safe URL/domain migration (`search-replace`)
55
56Follow a safe sequence:
57
581. `wp db export` (backup)
592. `wp search-replace --dry-run` (review impact)
603. Run the real replace with appropriate flags
614. Flush caches/rewrite if needed
62
63Read:
64- `references/search-replace.md`
65
66#### B) Plugin/theme operations
67
68Use `wp plugin *` / `wp theme *` and confirm you’re acting on the intended site (and network) first.
69
70Read:
71- `references/packages-and-updates.md`
72
73#### C) Cron and queues
74
75Inspect cron state and run individual events for debugging rather than “run everything blindly”.
76
77Read:
78- `references/cron-and-cache.md`
79
80#### D) Multisite operations
81
82Multisite changes can affect many sites. Always decide whether you’re operating:
83
84- on a single site (`--url=`), or
85- network-wide (`--network` / iterating sites)
86
87Read:
88- `references/multisite.md`
89
90### 3) Automation patterns (scripts + wp-cli.yml)
91
92For repeatable ops, prefer:
93
94- `wp-cli.yml` for defaults (path/url, PHP memory limits)
95- shell scripts that log commands and stop on error
96- CI jobs that run read-only checks by default
97
98Read:
99- `references/automation.md`
100
101## Verification
102
103- Re-run `wpcli_inspect` after changes that could affect targeting or config.
104- Confirm intended side effects:
105 - correct URLs updated
106 - plugins/themes in expected state
107 - cron/caches flushed where needed
108- If there’s a health check endpoint or smoke test suite, run it after ops changes.
109
110## Failure modes / debugging
111
112- “Error: This does not seem to be a WordPress installation.”
113 - wrong `--path`, wrong container, or missing `wp-config.php`
114- Multisite commands affecting the wrong site
115 - missing `--url` or wrong URL
116- Search-replace causes unexpected serialization issues
117 - wrong flags or changing serialized data unsafely
118
119See:
120- `references/debugging.md`
121
122## Escalation
123
124- If you cannot confirm environment safety, do not run write operations.
125- If the repo uses containerized tooling (Docker/wp-env) but you can’t access it, ask for the intended command runner or CI job.