[CLI] Add high-level start command for easy local WordPress development

[adamziel]

Summary

This PR introduces a new start command to Playground CLI that provides a simple, wp-now-style experience for running WordPress locally. It's designed to make the CLI accessible to developers who just want to run a command and get going, without needing to understand low-level options.

The existing server command remains available for advanced users who need fine-grained control over mounts, WordPress installation modes, and other low-level options.

Migrating from wp-now

This change unlocks officially deprecating @wp-now/wp-now and recommending everyone switch to @wp-playground/cli. Here's how wp-now commands map to the new start command:

wp-now	Playground CLI
npx @wp-now/wp-now start	npx @wp-playground/cli start
wp-now start --php=8.3	playground start --php=8.3
wp-now start --wp=6.7	playground start --wp=6.7
wp-now start --port=8000	playground start --port=8000
wp-now start --blueprint=bp.json	playground start --blueprint=bp.json
wp-now start --path=./my-plugin	playground start --path=./my-plugin
wp-now start --skip-browser	playground start --skip-browser
wp-now start --reset	(Not implemented. Playground CLI does not persist sites in the same way as wp-now does.)

The API is intentionally similar. Both tools automatically detect plugin, theme, wp-content, or WordPress directories. Both work with no additional flags.

Improvements over wp-now:

• Auto-login by default: No need to manually log in after starting
• Browser opens automatically: Site launches in your default browser (use --skip-browser to disable)
• Manual mounts available: Use --mount /host/path:/vfs/path for additional mounts beyond auto-detection
• Escape hatch: Use --no-auto-mount to disable auto-detection and manually control mounts
• Site URL override: Use --site-url when you need a specific URL

Differences with wp-now:

• Playground CLI does not persist sites in the same way as wp-now does. In wp-now, you can run wp-now start in a directory, get a site, make some changes to that site, then close the server, come back the next day, start the server again, and continue working on that same site. Playground CLI doesn't do it. Every server is ephemeral. You can store your changes by explicitly mounting wp-content to a local directory, but there's no automation in place to do it for you. If the users will request this feature, we can consider adding it, but I'm skipping it in the initial rollout as it would add a lot of complexity that the Playground CLI tool was intentionally designed not to handle implicitly.

Usage

# Start in current directory (auto-detects project type)
playground start

# Start with a specific path
playground start --path=./my-plugin

# Use specific PHP and WordPress versions
playground start --wp=6.7 --php=8.3

# Don't open browser automatically
playground start --skip-browser

# Enable Xdebug for debugging
playground start --xdebug

# Disable auto-detection and use manual mounts
playground start --no-auto-mount --mount ./my-plugin:/wordpress/wp-content/plugins/my-plugin

# Override the site URL
playground start --site-url=https://my-local-site.test

CLI Flags Reference

Flag	Type	Default	Description
--path	string	current directory	Path to the project directory. Playground auto-detects if this is a plugin, theme, wp-content, or WordPress directory.
--php	string	8.3	PHP version to use. Choices: 7.2, 7.3, 7.4, 8.0, 8.1, 8.2, 8.3, 8.4, 8.5
--wp	string	latest	WordPress version to use.
--port	number	9400	Port to listen on.
--blueprint	string	—	Path to a Blueprint JSON file to execute on startup.
--login	boolean	true	Auto-login as the admin user.
--xdebug	boolean	false	Enable Xdebug for debugging.
--skip-browser	boolean	false	Do not open the site in your default browser on startup.
--quiet	boolean	false	Suppress non-essential output.
--site-url	string	—	Override the site URL. By default, derived from the port (http://127.0.0.1:<port>).
--mount	array	—	Mount a directory to the PHP runtime (can be used multiple times). Format: /host/path:/vfs/path. Use this for additional mounts beyond auto-detection.
--no-auto-mount	boolean	false	Disable automatic project type detection. Use --mount to manually specify mounts instead.

Test plan

• Run playground start --help and verify options are displayed correctly
• Run playground start in a plugin directory and verify auto-detection works
• Verify browser opens automatically on startup
• Verify --skip-browser suppresses browser opening
• Run existing CLI tests to ensure no regressions

[Samiullahstanikzai]

i have this same issue Runtime error
Playground crashed

[adamziel]

@Samiullahstanikzai would you open a new issue with more details and reproduction instructions?

[adamziel]

@JanJakes @fellyph @zaerl Would you mind taking a look at this one? I'd love to learn how intuitive this seems for you? how smooth of a migration path would that be from WP now? And if anything obviously is missing or could be adjusted to make this even more useful?

[akirk]

Could we make the command even shorter? Just: npx @wp-playground/cli

[adamziel]

@akirk I think so! Or maybe even just npx wp-playground – I've secured that name.

[adamziel]

this function accepts a directory path, let's call it accordingly