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.

See Also

• Worktree skill — full worktree workflow including Playground setup
• npm scripts: playground:start, playground:server