ima-claude 2.16.0 → 2.20.0

package/plugins/ima-claude/skills/wp-ddev/references/wp-cli-reference.md

@@ -0,0 +1,406 @@
+# WP-CLI Command Reference
+
+Comprehensive reference for WP-CLI commands in local development. Organized for lookup — use the TOC to jump to what you need. All examples use the `ddev wp` command.
+
+For inline essentials (database, plugin, user, theme, cache, options, post, taxonomy, menu, rewrite, scaffold, eval), see [SKILL.md](../SKILL.md).
+
+## Table of Contents
+
+- [Core](#core)
+- [Config](#config)
+- [Cron](#cron)
+- [Media](#media)
+- [Comment](#comment)
+- [Role & Capability](#role--capability)
+- [Widget](#widget)
+- [Sidebar](#sidebar)
+- [Site & Multisite](#site--multisite)
+- [Language & i18n](#language--i18n)
+- [Import & Export](#import--export)
+- [Embed](#embed)
+- [Package](#package)
+- [Maintenance Mode](#maintenance-mode)
+- [Server](#server)
+- [Super Admin](#super-admin)
+- [Network Meta](#network-meta)
+- [Advanced Patterns](#advanced-patterns)
+
+---
+
+## Core
+
+`wp core version` · `wp core check-update` · `wp core update` · `wp core download` · `wp core install`
+
+```bash
+ddev wp core version
+ddev wp core check-update
+ddev wp core update
+ddev wp core update --minor
+ddev wp core verify-checksums
+```
+
+**Gotchas**: `core update` changes the WordPress version inside the container. The change persists in the mounted filesystem. Use `ddev setup` to re-run bootstrap after major updates.
+
+---
+
+## Config
+
+`wp config list` · `wp config get <name>` · `wp config set <name> <value>` · `wp config path`
+
+```bash
+ddev wp config path
+ddev wp config list --format=table
+ddev wp config get DB_NAME
+ddev wp config set WP_DEBUG true --raw
+ddev wp config set WP_DEBUG_LOG true --raw
+ddev wp config set SCRIPT_DEBUG true --raw
+ddev wp config set WP_DEBUG false --raw
+```
+
+**Key flags**:
+- `--raw` — Write value as a PHP constant (no quotes). Required for `true`/`false`/numbers.
+- `--type=constant|variable` — Whether to set as `define()` or `$variable`.
+
+**Gotchas**: `wp-config.php` is generated by `ddev setup`. Manual changes via `wp config set` persist across container restarts.
+
+---
+
+## Cron
+
+`wp cron event list` · `wp cron event run <hook>` · `wp cron event schedule <hook> <next-run>` · `wp cron event delete <hook>`
+
+```bash
+ddev wp cron event list --format=table
+ddev wp cron event run wp_update_plugins
+ddev wp cron event run --all
+ddev wp cron event delete my_custom_hook
+ddev wp cron schedule list
+```
+
+**Key flags**:
+- `--due-now` — List only events ready to run.
+- `--format=json` — Useful for piping to jq.
+
+**Gotchas**: DDEV sites don't run real cron by default. Events only fire on page load unless you configure `DISABLE_WP_CRON` + system cron.
+
+---
+
+## Media
+
+`wp media import <file>` · `wp media regenerate` · `wp media image-size`
+
+```bash
+ddev wp media import ~/images/photo.jpg --title="My Photo"
+ddev wp media import https://example.com/image.jpg
+ddev wp media regenerate --yes
+ddev wp media regenerate 42 43 44
+ddev wp media image-size --format=table
+```
+
+**Key flags**:
+- `--yes` — Skip confirmation on regenerate.
+- `--only-missing` — Only regenerate missing sizes.
+- `--skip-delete` — Don't delete old thumbnails during regenerate.
+
+---
+
+## Comment
+
+`wp comment list` · `wp comment create` · `wp comment update <id>` · `wp comment delete <id>` · `wp comment approve <id>`
+
+```bash
+ddev wp comment list --format=table
+ddev wp comment list --status=hold --fields=comment_ID,comment_author,comment_content
+ddev wp comment create --comment_post_ID=42 --comment_content="Test comment" --comment_author="Test"
+ddev wp comment approve 5
+ddev wp comment spam 5
+ddev wp comment delete 5 --force
+ddev wp comment recount
+```
+
+---
+
+## Role & Capability
+
+`wp role list` · `wp role create <role> <name>` · `wp cap list <role>` · `wp cap add <role> <cap>`
+
+```bash
+ddev wp role list --format=table
+ddev wp role create custom_role "Custom Role" --clone=editor
+ddev wp cap list editor --format=table
+ddev wp cap add editor manage_options
+ddev wp cap remove editor manage_options
+```
+
+**Gotchas**: Role/cap changes persist in the database (`wp_options` → `wp_user_roles`). Removing a role doesn't reassign users — they lose access.
+
+---
+
+## Widget
+
+`wp widget list <sidebar-id>` · `wp widget add <widget> <sidebar-id>` · `wp widget delete <widget-id>` · `wp widget reset <sidebar-id>`
+
+```bash
+ddev wp widget list sidebar-1 --format=table
+ddev wp widget add text sidebar-1 --title="Hello" --text="World"
+ddev wp widget update text-2 --title="Updated"
+ddev wp widget delete text-2
+ddev wp widget deactivate text-2
+ddev wp widget reset sidebar-1
+```
+
+**Gotchas**: Widget IDs are auto-generated (e.g., `text-2`). List first to find IDs.
+
+---
+
+## Sidebar
+
+`wp sidebar list`
+
+```bash
+ddev wp sidebar list --format=table
+ddev wp sidebar list --fields=id,name,description
+```
+
+---
+
+## Site & Multisite
+
+`wp site list` · `wp site create` · `wp site activate <site-id>` · `wp site deactivate <site-id>`
+
+```bash
+ddev wp site list --format=table
+ddev wp site create --slug=newsite --title="New Site" --email=admin@example.com
+ddev wp site activate 2
+ddev wp site deactivate 2
+ddev wp site delete 2 --yes
+```
+
+**Key flags**:
+- `--url=<url>` — Target a specific site in multisite. Use with any command.
+
+**Gotchas**: Only works on multisite installs. Single-site installs will error.
+
+---
+
+## Language & i18n
+
+`wp language core list` · `wp language core install <language>` · `wp language core activate <language>` · `wp i18n make-pot`
+
+```bash
+ddev wp language core list --format=table
+ddev wp language core install es_ES
+ddev wp language core activate es_ES
+ddev wp language plugin install hello-dolly es_ES
+ddev wp language theme install flavor es_ES
+ddev wp i18n make-pot . languages/my-plugin.pot
+ddev wp i18n make-json languages/
+```
+
+---
+
+## Import & Export
+
+`wp export` · `wp import <file>`
+
+```bash
+ddev wp export --dir=. --post_type=post
+ddev wp export --dir=. --post_type=page --start_date=2024-01-01
+ddev wp import export.xml --authors=mapping.csv
+ddev wp import export.xml --authors=create
+```
+
+**Key flags**:
+- `--dir` — Export directory (defaults to current dir).
+- `--post_type` — Limit export to specific post type.
+- `--authors=create|mapping.csv|skip` — How to handle author mapping on import.
+
+**Gotchas**: Import requires the WordPress Importer plugin. Install with `ddev wp plugin install wordpress-importer --activate`.
+
+---
+
+## Embed
+
+`wp embed fetch <url>` · `wp embed provider list`
+
+```bash
+ddev wp embed fetch "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
+ddev wp embed provider list --format=table
+ddev wp embed cache clear
+```
+
+---
+
+## Package
+
+`wp package list` · `wp package install <package>` · `wp package uninstall <package>`
+
+```bash
+ddev wp package list
+ddev wp package install wp-cli/doctor-command
+ddev wp package install wp-cli/profile-command
+ddev wp package uninstall wp-cli/doctor-command
+```
+
+**Useful packages**:
+- `wp-cli/doctor-command` — Diagnose WordPress issues
+- `wp-cli/profile-command` — Profile command performance
+- `wp-cli/dist-archive-command` — Create plugin/theme zip archives
+
+---
+
+## Maintenance Mode
+
+`wp maintenance-mode activate` · `wp maintenance-mode deactivate` · `wp maintenance-mode status`
+
+```bash
+ddev wp maintenance-mode activate
+ddev wp maintenance-mode deactivate
+ddev wp maintenance-mode status
+```
+
+---
+
+## Server
+
+`wp server`
+
+```bash
+ddev wp server --host=0.0.0.0 --port=8080
+```
+
+**Gotchas**: Not useful with DDEV — DDEV manages its own nginx/Apache server. Included for completeness.
+
+---
+
+## Super Admin
+
+`wp super-admin list` · `wp super-admin add <user>` · `wp super-admin remove <user>`
+
+```bash
+ddev wp super-admin list
+ddev wp super-admin add admin
+ddev wp super-admin remove admin
+```
+
+**Gotchas**: Multisite only.
+
+---
+
+## Network Meta
+
+`wp network meta get <id> <key>` · `wp network meta update <id> <key> <value>`
+
+```bash
+ddev wp network meta list 1 --format=table
+ddev wp network meta get 1 site_name
+ddev wp network meta update 1 site_name "My Network"
+```
+
+**Gotchas**: Multisite only. Network ID is usually `1`.
+
+---
+
+## Advanced Patterns
+
+### JSON output + jq
+
+Pipe `--format=json` through jq for powerful filtering:
+
+```bash
+# Get IDs of all active plugins
+ddev wp plugin list --status=active --format=json | jq -r '.[].name'
+
+# Get post titles containing "hello"
+ddev wp post list --format=json | jq -r '.[] | select(.post_title | test("hello";"i")) | .post_title'
+
+# Count posts by status
+ddev wp post list --format=json | jq 'group_by(.post_status) | map({status: .[0].post_status, count: length})'
+
+# Get all option names matching a pattern
+ddev wp option list --search="woo*" --format=json | jq -r '.[].option_name'
+```
+
+### Bulk operations
+
+```bash
+# Deactivate all plugins
+ddev wp plugin deactivate --all
+
+# Delete all transients
+ddev wp transient delete --all
+
+# Regenerate all thumbnails
+ddev wp media regenerate --yes
+
+# Delete all spam comments
+ddev wp comment delete $(ddev wp comment list --status=spam --format=ids) --force
+
+# Reset all user passwords
+ddev wp user list --format=ids | xargs -I{} ddev wp user update {} --user_pass="changeme"
+```
+
+### Common eval snippets
+
+```bash
+# Check current theme
+ddev wp eval "echo get_template();"
+
+# Get site health info
+ddev wp eval "echo home_url(); echo ' | '; echo wp_get_theme()->get('Name');"
+
+# Check if a function exists
+ddev wp eval "echo function_exists('wc_get_products') ? 'yes' : 'no';"
+
+# Get active plugin count
+ddev wp eval "echo count(get_option('active_plugins'));"
+
+# List registered post types
+ddev wp eval "print_r(array_keys(get_post_types(['public' => true])));"
+
+# List registered taxonomies
+ddev wp eval "print_r(array_keys(get_taxonomies(['public' => true])));"
+
+# Check PHP version and memory
+ddev wp eval "echo 'PHP: ' . PHP_VERSION . ' | Memory: ' . WP_MEMORY_LIMIT;"
+
+# Test a shortcode
+ddev wp eval "echo do_shortcode('[my_shortcode]');"
+```
+
+### Chaining commands
+
+```bash
+# Install, activate, and verify
+ddev wp plugin install woocommerce --activate && ddev wp plugin list --status=active
+
+# Export before destructive operation
+ddev wp db export before-change.sql && ddev wp search-replace 'old.com' 'new.com'
+
+# Create user and assign role
+ddev wp user create testuser test@test.com --role=subscriber && ddev wp user add-role $(ddev wp user get testuser --field=ID) editor
+```
+
+### Debugging plugin conflicts
+
+```bash
+# Run with all plugins disabled
+ddev wp eval "echo home_url();" --skip-plugins
+
+# Run with specific plugin disabled
+ddev wp eval "echo home_url();" --skip-plugins=problematic-plugin
+
+# Run with themes disabled
+ddev wp eval "echo 'loaded';" --skip-themes
+```
+
+### Format reference
+
+| Format | Use case |
+|---|---|
+| `table` | Human-readable terminal output (default) |
+| `json` | Pipe to jq, programmatic processing |
+| `csv` | Spreadsheet import, simple parsing |
+| `yaml` | Config files, readable structured data |
+| `ids` | Pipe to other commands (`xargs`) |
+| `count` | Quick counts |