# 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.

- Skill: `johnie/wp-cli` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add johnie/wp-cli`
- Raw SKILL.md: https://api.skillmd.com/api/skills/johnie/wp-cli/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: johnie (https://skillmd.com/u/johnie)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/johnie/wp-cli

---


# 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:

```bash
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](#remote-execution)).

## Safety patterns

### Backup before destructive work

```bash
# 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

```bash
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 table
- `wp db clean` — drops every table matching the current `$table_prefix`
- `wp site delete` (multisite) — removes a site and its content
- `wp user delete` without `--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

```bash
--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`](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`](references/examples-migration.md) |
| Plugin updates with rollback, debugging, DB maintenance | [`references/examples-maintenance.md`](references/examples-maintenance.md) |
| User audit, cleanup, safe password rotation | [`references/examples-users.md`](references/examples-users.md) |
| Bulk content import from CSV | [`references/examples-content.md`](references/examples-content.md) |
| Multisite / network operations | [`references/examples-multisite.md`](references/examples-multisite.md) |

## Remote execution

### Ad-hoc SSH

```bash
ssh user@example.com "cd /var/www/html && wp plugin list"
```

### Configured aliases (preferred)

Define aliases once in `~/.wp-cli/config.yml`:

```yaml
@prod:
  ssh: user@example.com/var/www/html
@staging:
  ssh: user@staging.example.com/var/www/staging
```

Then:

```bash
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 `xargs` or `for`. Each `wp` invocation bootstraps WordPress; 1M iterations = days. Prefer a single `wp db query` with a proper SQL statement, or a PHP-side batched job.
- **Using `wp search-replace` without `--precise` on serialized data** larger than a hobby blog. `--precise` is 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 create` with `--user_pass=...` leaks. Pipe the password in or let wp-cli prompt.

## Best practices

1. **Staging first, always.** Never run an untested command on production.
2. **Track `wp-config.php` changes in version control** when feasible (exclude secrets).
3. **Read the output.** wp-cli warnings often precede data loss.
4. **Document non-obvious workflows** — migrations, multisite conversions — as they happen; future-you will not remember which flags you used.
5. **`--format=json` whenever piping to `jq` or another script.** The default human format rots.
6. **Verify after big changes** — load the homepage, check admin, exercise critical paths.
7. **Keep wp-cli current**: `wp cli update` (Phar installs only — Homebrew and Composer installs update through their package manager).

## References

- [`references/commands.md`](references/commands.md) — detailed command + flag reference by category
- Workflow guides (load on demand):
  - [`references/examples-migration.md`](references/examples-migration.md) — migration + search-replace
  - [`references/examples-maintenance.md`](references/examples-maintenance.md) — plugin updates, debugging, DB maintenance
  - [`references/examples-users.md`](references/examples-users.md) — user audit & cleanup
  - [`references/examples-content.md`](references/examples-content.md) — CSV content import
  - [`references/examples-multisite.md`](references/examples-multisite.md) — multisite operations
- Upstream docs: <https://developer.wordpress.org/cli/commands/>