wp-cli
Drive WordPress from the command line via `wp` CLI — site migrations, search-replace, bulk plugin/theme/user/post operations, option and config edits, multisite management, and cron scheduling. Use whenever the user wants to do something to a WordPress site that a terminal can reach faster than wp-admin.
How do I install this agent skill?
npx skills add https://github.com/johnie/skills --skill wp-cliIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides comprehensive tools for managing WordPress installations via WP-CLI. It contains advanced workflows for database migration, content import, and user management. Security risks include a potential surface for indirect prompt injection through external data processing and the use of dynamic PHP execution, though these are mitigated by extensive safety documentation and explicit user confirmation requirements.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- Runlayerfail
3/3 files flagged
What does this agent skill do?
wp-cli
Terminal-first WordPress operations. Safer than wp-admin for bulk work, scriptable, SSH-friendly, and won't time out on 10k-row updates.
Only inspection commands and wp db export (which takes a backup) run without a prompt. Every mutating command — search-replace, db import, db reset, plugin/theme installs, user and post writes — prompts before it runs. That friction is deliberate: this skill routinely points at production.
Reference files live in ${CLAUDE_SKILL_DIR}/references/.
When NOT to use
- One-off edits a content editor would do in 10 seconds in the admin UI. CLI is overkill and error-prone for single-row clicks.
- Data transformations that span millions of rows — WP's ORM will be slow; consider a direct SQL migration with an explicit transaction.
- Anything that needs to run inside a WordPress plugin's hook lifecycle (e.g., REST validation, custom post type registration) — that's PHP code, not CLI.
- Destructive commands without a current backup.
wp db reset,wp db clean, bulk deletes — always snapshot first.
Preflight
Always verify before doing anything:
wp --version # wp-cli is installed
wp core is-installed # WordPress is actually set up at this path
wp core version # which WP version
If not at the WordPress root, pass --path=/path/to/wordpress or cd there first. On remote hosts, use --ssh=user@host/path or a configured alias (see Remote Execution).
Safety patterns
Backup before destructive work
# Database snapshot
wp db export backup-$(date +%Y%m%d-%H%M%S).sql
# Full site snapshot (db + content)
tar -czf site-backup-$(date +%Y%m%d-%H%M%S).tar.gz wp-content/ backup-*.sql
Dry-run when available
wp plugin update --all --dry-run
wp search-replace 'old.com' 'new.com' --dry-run
Dangerous commands — confirm explicitly
These are irreversible without a backup. Confirm with the user before running:
wp db reset— drops every tablewp db clean— drops every table matching the current$table_prefixwp site delete(multisite) — removes a site and its contentwp user deletewithout--reassign— orphans the user's posts (they get deleted too). Always pass--reassign=<new_author_id>to reassign their content first. The flag exists because orphaning content is almost never what you want — the user's posts are the institutional record, not the user row.wp post delete $(wp post list --format=ids)and similar bulk-delete pipes — quietly turn the whole site into a blank page if the filter is wrong.
Performance flags
--format=json # machine-readable
--format=csv # spreadsheet import
--format=ids # space-separated IDs, for piping
--fields=ID,post_title # return only what you need
--skip-plugins # bypass plugin load (fast, may break plugin-dependent commands)
--skip-themes # bypass theme load
--quiet # suppress info output
--skip-plugins is a scalpel: it makes wp db export instant, but breaks commands that rely on a plugin's hooks (e.g., ACF exporters, custom taxonomies registered by a plugin).
Command catalog
Full flag docs and gotchas are in references/commands.md. Categories:
| Category | Prefix | Typical use |
|---|---|---|
| Database | wp db | export, import, query, optimize, search-replace |
| Core | wp core | install, update, verify-checksums, version |
| Plugins | wp plugin | list, install, activate, update, delete |
| Themes | wp theme | list, install, activate, update, delete, theme mod |
| Users | wp user | create, list, delete (--reassign), update, roles, generate |
| Posts / Pages | wp post | list, create, update, delete, generate, post term |
| Comments | wp comment | list, approve, spam, trash, delete |
| Options | wp option | get, update, delete, list, pluck/patch for nested values |
| Cache | wp cache / wp transient | flush, delete, set, list |
| Cron | wp cron | event list/run/schedule/delete, cron test |
| Config | wp config | create, get, set, shuffle-salts |
| Multisite | wp site | list, create, delete, empty, activate/archive |
Workflows
Full step-by-step workflows live in references/, split by task — load only the one the user is doing end-to-end:
| Workflow | File |
|---|---|
| Site migration (local → prod) + search-replace | references/examples-migration.md |
| Plugin updates with rollback, debugging, DB maintenance | references/examples-maintenance.md |
| User audit, cleanup, safe password rotation | references/examples-users.md |
| Bulk content import from CSV | references/examples-content.md |
| Multisite / network operations | references/examples-multisite.md |
Remote execution
Ad-hoc SSH
ssh user@example.com "cd /var/www/html && wp plugin list"
Configured aliases (preferred)
Define aliases once in ~/.wp-cli/config.yml:
@prod:
ssh: user@example.com/var/www/html
@staging:
ssh: user@staging.example.com/var/www/staging
Then:
wp @prod plugin list
wp @staging db export
Aliases beat ad-hoc SSH because they compose with every wp-cli flag (wp @prod --dry-run search-replace ...) and don't invite shell-quoting bugs.
Common errors
| Error | Cause | Fix |
|---|---|---|
The site you have requested is not installed | Not at WordPress root / wp-config.php missing | cd to root or --path=/path/to/wordpress |
MySQL connection failed | Bad credentials or MySQL down | Check wp-config.php, confirm MySQL is running |
Error: Can't select database | DB doesn't exist | wp db create |
PHP Fatal error: Allowed memory size exhausted | Large op or heavy plugins | php -d memory_limit=512M $(which wp) db export |
This does not seem to be a WordPress installation | WP files not found | Check directory; confirm WP is actually installed |
The \guid` column is often used ... but should not be updated` | Expected warning | --skip-columns=guid suppresses it; GUIDs are permanent IDs, not URLs |
Antipatterns — when wp-cli is the wrong tool
- Looping over millions of rows in shell with
xargsorfor. Eachwpinvocation bootstraps WordPress; 1M iterations = days. Prefer a singlewp db querywith a proper SQL statement, or a PHP-side batched job. - Using
wp search-replacewithout--preciseon serialized data larger than a hobby blog.--preciseis slower but handles PHP serialized strings correctly; without it, serialized arrays silently corrupt. - Validation and domain logic. If the logic belongs inside a WP plugin's hook lifecycle, do it there. wp-cli is for operational work, not business rules.
- Credential-bearing commands in your shell history.
wp user createwith--user_pass=...leaks. Pipe the password in or let wp-cli prompt.
Best practices
- Staging first, always. Never run an untested command on production.
- Track
wp-config.phpchanges in version control when feasible (exclude secrets). - Read the output. wp-cli warnings often precede data loss.
- Document non-obvious workflows — migrations, multisite conversions — as they happen; future-you will not remember which flags you used.
--format=jsonwhenever piping tojqor another script. The default human format rots.- Verify after big changes — load the homepage, check admin, exercise critical paths.
- Keep wp-cli current:
wp cli update(Phar installs only — Homebrew and Composer installs update through their package manager).
References
references/commands.md— detailed command + flag reference by category- Workflow guides (load on demand):
references/examples-migration.md— migration + search-replacereferences/examples-maintenance.md— plugin updates, debugging, DB maintenancereferences/examples-users.md— user audit & cleanupreferences/examples-content.md— CSV content importreferences/examples-multisite.md— multisite operations
- Upstream docs: https://developer.wordpress.org/cli/commands/
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/johnie/skills/wp-cli">View wp-cli on skillZs</a>