WP-CLI Operations via Lando
When to use
- Performing database operations (export, import, optimize, search-replace)
- Managing plugins, themes, or users from the command line
- Running maintenance tasks (cache flush, rewrite flush, cron)
- Building or executing deployment scripts
- Troubleshooting WordPress configuration issues
Inputs required
- The specific operation to perform
- For search-replace: old and new values, scope (all tables or specific)
- For user management: user details (email, role, username)
- For deploy scripts: target environment and deployment steps
- Confirmation that backups exist before destructive operations
Procedure
All WP-CLI commands must be prefixed with lando wp to execute inside the Lando container.
Database operations
See references/db-operations.md for export, import, and search-replace workflows.
Quick reference:
# Export backup
lando wp db export "backup-$(date +%Y%m%d-%H%M%S).sql"
# Search-replace (always dry-run first)
lando wp search-replace 'https://old.com' 'https://new.com' --dry-run --precise --all-tables
lando wp search-replace 'https://old.com' 'https://new.com' --precise --all-tables
Scripts: scripts/db-backup.sh and scripts/search-replace.sh.
User and content operations
See references/content-ops.md for user management, post operations, and option manipulation.
Quick reference:
lando wp user create <username> <email> --role=<role> --user_pass=<password>
lando wp post list --post_type=<type> --fields=ID,post_title
lando wp option update my_option '{"key":"value"}' --format=json
Maintenance and deploy operations
See references/maintenance-deploy.md for the full deploy sequence.
Quick reference:
lando wp maintenance-mode activate
lando wp cache flush
lando wp transient delete --all
lando wp rewrite flush
lando wp maintenance-mode deactivate
Preflight checks for destructive operations
See references/preflight-checks.md for mandatory checks before any destructive WP-CLI command.
Key rules:
- Always back up first:
lando wp db export
- Always dry-run search-replace before applying
- Use
--format=json when updating serialized options
- Pipe post content via stdin to avoid backslash stripping
Custom Acorn CLI commands
lando wp acorn <command-name>
lando wp acorn list
Cross-reference the acorn-commands skill for creating and running custom Acorn artisan commands within Lando.
Verification
Failure modes
| Symptom |
Likely cause |
Fix |
lando wp command not found |
Lando not running or misconfigured |
Run lando start, check .lando.yml tooling |
| Search-replace corrupts serialized data |
Missing --precise flag |
Restore from backup, re-run with --precise |
| Database import fails |
SQL file too large or charset mismatch |
Split the file, check max_allowed_packet, verify charset |
| Plugin activation fatal error |
PHP compatibility or dependency conflict |
Check PHP version, review error log with lando logs |
| Cron events not firing |
DISABLE_WP_CRON set without system cron |
Add system cron or remove the constant in dev |
| Maintenance mode stuck |
.maintenance file not removed |
lando wp maintenance-mode deactivate or manually remove the file |
wp acorn commands fail |
Acorn not bootstrapped |
Verify Acorn is installed and activated, check app/Providers/ |
Escalation
- If WP-CLI commands consistently fail inside Lando, check Lando service health with
lando info and lando logs
- For database corruption beyond simple import/export, consult a DBA or restore from a known-good backup
- If search-replace produces unexpected results after dry-run looked clean, restore from backup immediately and investigate serialized data structures
- For deploy script failures in staging or production, halt the deployment, restore from backup, and debug in the Lando local environment first
1---2name: superpowers-sage-wp-cli-ops3description: WP-CLI operations via Lando — lando wp db export, lando wp db import, lando wp search-replace, lando wp search-replace --dry-run, lando wp user create, lando wp post list, lando wp plugin install, database management, maintenance mode, lando wp maintenance-mode activate, lando wp cache flush, lando wp cron event run, lando wp option update, lando wp transient delete, deploy checklist, preflight checks, destructive operations safety4---56# WP-CLI Operations via Lando78## When to use910- Performing database operations (export, import, optimize, search-replace)11- Managing plugins, themes, or users from the command line12- Running maintenance tasks (cache flush, rewrite flush, cron)13- Building or executing deployment scripts14- Troubleshooting WordPress configuration issues1516## Inputs required1718- The specific operation to perform19- For search-replace: old and new values, scope (all tables or specific)20- For user management: user details (email, role, username)21- For deploy scripts: target environment and deployment steps22- Confirmation that backups exist before destructive operations2324## Procedure2526**All WP-CLI commands must be prefixed with `lando wp`** to execute inside the Lando container.2728### Database operations2930See [`references/db-operations.md`](references/db-operations.md) for export, import, and search-replace workflows.3132Quick reference:3334```bash35# Export backup36lando wp db export "backup-$(date +%Y%m%d-%H%M%S).sql"3738# Search-replace (always dry-run first)39lando wp search-replace 'https://old.com' 'https://new.com' --dry-run --precise --all-tables40lando wp search-replace 'https://old.com' 'https://new.com' --precise --all-tables41```4243Scripts: [`scripts/db-backup.sh`](scripts/db-backup.sh) and [`scripts/search-replace.sh`](scripts/search-replace.sh).4445### User and content operations4647See [`references/content-ops.md`](references/content-ops.md) for user management, post operations, and option manipulation.4849Quick reference:5051```bash52lando wp user create <username> <email> --role=<role> --user_pass=<password>53lando wp post list --post_type=<type> --fields=ID,post_title54lando wp option update my_option '{"key":"value"}' --format=json55```5657### Maintenance and deploy operations5859See [`references/maintenance-deploy.md`](references/maintenance-deploy.md) for the full deploy sequence.6061Quick reference:6263```bash64lando wp maintenance-mode activate65lando wp cache flush66lando wp transient delete --all67lando wp rewrite flush68lando wp maintenance-mode deactivate69```7071### Preflight checks for destructive operations7273See [`references/preflight-checks.md`](references/preflight-checks.md) for mandatory checks before any destructive WP-CLI command.7475Key rules:761. Always back up first: `lando wp db export`772. Always dry-run search-replace before applying783. Use `--format=json` when updating serialized options794. Pipe post content via stdin to avoid backslash stripping8081### Custom Acorn CLI commands8283```bash84lando wp acorn <command-name>85lando wp acorn list86```8788Cross-reference the **acorn-commands** skill for creating and running custom Acorn artisan commands within Lando.8990## Verification9192- [ ] Dry-run output reviewed before executing any search-replace93- [ ] Database backup exists before any destructive operation94- [ ] Plugin/theme activation confirmed with `lando wp plugin list` or `lando wp theme list`95- [ ] Cron events listed and verified after scheduling changes96- [ ] Rewrite rules flushed after permalink or route changes97- [ ] Cache cleared after configuration or content changes98- [ ] Deploy script steps completed without errors99100## Failure modes101102| Symptom | Likely cause | Fix |103|---|---|---|104| `lando wp` command not found | Lando not running or misconfigured | Run `lando start`, check `.lando.yml` tooling |105| Search-replace corrupts serialized data | Missing `--precise` flag | Restore from backup, re-run with `--precise` |106| Database import fails | SQL file too large or charset mismatch | Split the file, check `max_allowed_packet`, verify charset |107| Plugin activation fatal error | PHP compatibility or dependency conflict | Check PHP version, review error log with `lando logs` |108| Cron events not firing | `DISABLE_WP_CRON` set without system cron | Add system cron or remove the constant in dev |109| Maintenance mode stuck | `.maintenance` file not removed | `lando wp maintenance-mode deactivate` or manually remove the file |110| `wp acorn` commands fail | Acorn not bootstrapped | Verify Acorn is installed and activated, check `app/Providers/` |111112## Escalation113114- If WP-CLI commands consistently fail inside Lando, check Lando service health with `lando info` and `lando logs`115- For database corruption beyond simple import/export, consult a DBA or restore from a known-good backup116- If search-replace produces unexpected results after dry-run looked clean, restore from backup immediately and investigate serialized data structures117- For deploy script failures in staging or production, halt the deployment, restore from backup, and debug in the Lando local environment first
hekivo