wp-cli-patterns

WP-CLI Patterns — Best Practices for All Agents

This skill teaches the WP-CLI-first principle: use WP-CLI commands instead of generating PHP code whenever possible. WP-CLI saves tokens, reduces errors, and executes faster than writing throwaway PHP files.

---

Core Rule: WP-CLI Over PHP Generation

Always prefer a single WP-CLI command over generating PHP code.

# BAD (costs tokens): Generate PHP file with update_option()
# GOOD (1 line):      $WP option update my_option 'value'

# BAD:  Generate PHP with wp_insert_post()
# GOOD: $WP post create --post_type=page --post_title='About' --post_status=publish

# BAD:  Generate PHP with wp_create_nav_menu()
# GOOD: $WP menu create "Primary EN" && $WP menu item add-post primary-en 5

# BAD:  Generate PHP to activate a plugin
# GOOD: $WP plugin activate secure-custom-fields

# BAD:  Generate PHP to set permalink structure
# GOOD: $WP rewrite structure '/%postname%/'

Use wp eval only when no dedicated WP-CLI subcommand exists for the operation (e.g., calling ACF's update_field() API).

---

The $WP Convention

Throughout all commands, agents, and skills, $WP is shorthand for the value of wp_cli.wrapper from .wp-create.json. Agents read this value and substitute it into all WP-CLI commands.

For example, if the environment is Docker:

# $WP expands to:
docker exec my-project-wp wp --allow-root

# So this command:
$WP option update blogname "My Site"

# Becomes:
docker exec my-project-wp wp --allow-root option update blogname "My Site"

How to read $WP: Parse .wp-create.json at the project root and extract the wp_cli.wrapper value. Every WP-CLI command in this skill assumes $WP is set to that value.

---

Environment-Aware Execution

Agents read wp_cli.wrapper from .wp-create.json and prepend it to all WP-CLI commands. The wrapper value depends on the environment type:

Environment	wp_cli.wrapper value	Notes
Native	wp --path=/var/www/html/my-project	Direct CLI, requires WP-CLI installed on host
Docker	docker exec my-project-wp wp --allow-root	Executes inside WordPress container
DDEV	ddev wp	DDEV proxies to the web container
Lando	lando wp	Lando proxies to the appserver container
wp-env	npx wp-env run cli wp	wp-env proxies to its CLI container