WordPress Playground CLI for Quick Testing Skill

WordPress Playground CLI for Quick Testing

Use @wp-playground/cli to spin up fast, disposable WordPress instances for testing. No Docker required — uses WebAssembly + SQLite.

When to Use

Worktrees: each worktree gets its own Playground instance on a unique port
Quick feature check: spin up a site to verify a change without touching the Docker dev environment
Parallel branch testing: multiple branches in separate browser tabs
UI review: fast visual check of a feature or fix

For thorough testing that needs MySQL or WP-CLI, use the Docker Compose setup instead.

Quick Start (current directory)

Before starting, ensure build assets exist — Playground mounts the directory as-is:

# Install dependencies if node_modules is missing (common in worktrees).
# npm ci, not npm install — install can rewrite package-lock.json.
[ -d node_modules ] || npm ci

# Build JS/CSS assets (required — Playground has no build step)
npm run build

Then start:

npm run playground:start

This runs npx @wp-playground/cli server with the plugin mounted and the blueprint applied.

With a Blueprint (recommended)

Use the project blueprint for a pre-configured environment:

npx @wp-playground/cli server \
  --mount=.:/wordpress/wp-content/plugins/simple-history \
  --blueprint=.claude/worktree-blueprint.json \
  --port=9400

The blueprint (.claude/worktree-blueprint.json) enables dev mode, activates the plugin, logs in automatically, and enables experimental features.

Multiple Instances (worktrees or branches)

Preferred: use scripts/parallel-dev.sh — it creates the worktree, installs/builds, picks a free port, starts Playground detached, and tracks state per worktree (see the worktree skill for full usage):

scripts/parallel-dev.sh up <slug> [--no-premium] [--premium=<path>]
scripts/parallel-dev.sh status
scripts/parallel-dev.sh down <slug> [--remove]

Manual approach: each instance needs a unique port. Find the next available one:

PORT=9400; while lsof -i :$PORT >/dev/null 2>&1; do PORT=$((PORT+1)); done; echo $PORT

Then start each instance:

# Worktree 1
cd .claude/worktrees/issue-42
npx @wp-playground/cli server --mount=.:/wordpress/wp-content/plugins/simple-history --port=9400

# Worktree 2
cd .claude/worktrees/issue-55
npx @wp-playground/cli server --mount=.:/wordpress/wp-content/plugins/simple-history --port=9401

Each gets its own browser tab: http://localhost:9400, http://localhost:9401, etc.

Useful Flags

| Flag | Purpose | | ------------------ | ------------------------------------- | | --auto-mount | Auto-detect plugin/theme and mount it | | --mount=src:dest | Manually mount a directory | | --port=NNNN | Set the server port | | --wp=6.3 | Use a specific WordPress version | | --php=7.4 | Use a specific PHP version | | --blueprint=path | Apply a blueprint JSON on startup | | --login | Auto-login as admin |

Limitations

SQLite only — not MySQL/MariaDB. Use Docker for database-specific testing.
No WP-CLI — use wp-env or Docker if you need CLI commands.
Ephemeral by default — state may not persist across restarts.

Deprecated: wp-now

@wp-now/wp-now is deprecated. Use @wp-playground/cli with --auto-mount instead — it provides the same auto-detection behavior.

Agent Skills: WordPress Playground CLI for Quick Testing

Install this agent skill to your local

Skill Files