Wp Wpcli And Ops

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