Playground CLI
@wp-playground/cli is a command-line tool that simplifies the WordPress development and testing flow. Playground CLI supports auto-mounting a directory with a plugin, theme, or WordPress installation. But if you need flexibility, the CLI supports mounting commands to personalize your local environment.
Key features:
- Quick Setup: Set up a local WordPress environment in seconds.
- Flexibility: Allows for configuration to adapt to different scenarios.
- Simple Environment: No extra configuration, just a compatible Node version, and you are ready to use it.
The Playground CLI includes two main commands for running WordPress locally:
start(Simplified): Auto-detects your project type, persists sites between sessions, and opens a browser automatically.server(Advanced): Provides full manual control over configuration. Best for custom setups, CI/CD pipelines, or when you need fine-grained control.
Requirements
The Playground CLI requires Node.js 20.18 or higher, which is the recommended Long-Term Support (LTS) version. You can download it from the Node.js website.
Quickstart
To run the Playground CLI, open a command line and use one of the following commands:
Using start (Simplified)
The start command is the easiest way to get started. It automatically detects your project type, persists your site, and opens the browser:
npx @wp-playground/cli@latest start
When run inside a plugin or theme directory, start automatically mounts your project:
cd my-plugin
npx @wp-playground/cli@latest start
Key differences from server:
- Auto-login is enabled by default
- Opens browser automatically
- Auto-mounts the project by default
Migrating from wp-now
The deprecated @wp-now/wp-now package maps most directly to the start
command:
| wp-now | Playground CLI |
|---|---|
npx @wp-now/wp-now start | npx @wp-playground/cli@latest start |
npx @wp-now/wp-now start --path=./plugin | cd ./plugin && npx @wp-playground/cli@latest start |
npx @wp-now/wp-now start --wp=6.8 --php=8.3 | npx @wp-playground/cli@latest start --wp=6.8 --php=8.3 |
npx @wp-now/wp-now start --blueprint=./blueprint.json | npx @wp-playground/cli@latest start --blueprint=./blueprint.json |
npx @wp-now/wp-now start --skip-browser | npx @wp-playground/cli@latest start --skip-browser |
npx @wp-now/wp-now start --reset | npx @wp-playground/cli@latest start --reset |
The main workflow change is where the saved site lives:
- With
wp-now,--path=./pluginpicked the project and the saved site. - With Playground CLI,
startsaves the site for the current directory. For the closest match,cdinto the project first, then runstart. - When Playground CLI creates WordPress for you, it keeps the WordPress files
in
~/.wordpress-playground/sites/<path-hash>/. - If you run it on a full WordPress directory, or mount a directory at
/wordpress, that directory is the WordPress site. Changes are written there. start --path=./pluginstill mounts that folder, but it does not make./pluginthe saved site. The saved site still belongs to the directory where you ran the command.
Use start for the familiar wp-now-style flow. Use server only when you want
to spell out mounts, storage, or automation yourself.
Using server (Advanced)
The server command provides full control over configuration:
npx @wp-playground/cli@latest server

Automatic site persistence: When the start command manages the WordPress
root directory, it keeps your WordPress site persistent across sessions. Your
files and database are stored in ~/.wordpress-playground/sites/<path-hash>/,
where <path-hash> is derived from the command's current working directory. If
you start from a full WordPress installation, or explicitly mount /wordpress,
that mounted directory becomes the persistent store instead.
This is useful when:
- You want a clean WordPress installation
- Testing fresh installation scenarios
- Your site data became corrupted or inconsistent
The --reset flag works only with start. For server, manually delete the persisted site directory at ~/.wordpress-playground/sites/<path-hash>/.
Choosing a WordPress and PHP Version
By default, the CLI loads the latest stable version of WordPress and PHP 8.3 due to its improved performance. To specify your preferred versions, you can use the flag --wp=<version> and --php=<version>:
npx @wp-playground/cli@latest server --wp=6.8 --php=8.4
Loading Blueprints
One way to take your Playground CLI development experience to the next level is to integrate with Blueprints. For those unfamiliar with this technology, it allows developers to configure the initial state for their WordPress Playground instances.
Using the --blueprint=<blueprint-address> flag, developers can run a Playground with a custom initial state. We’ll use the example below to do this.
(my-blueprint.json)
{
"landingPage": "/wp-admin/options-general.php?page=akismet-key-config",
"login": true,
"plugins": [
"hello-dolly",
"https://raw.githubusercontent.com/adamziel/blueprints/trunk/docs/assets/hello-from-the-dashboard.zip"
]
}
CLI command loading a blueprint:
npx @wp-playground/cli@latest server --blueprint=my-blueprint.json
Missing constants after a login step in CLI 3.1.64
In CLI 3.1.64, running login followed by defineWpConfigConsts with multiple workers can lose constants, including SQLITE_JOURNAL_MODE. If you encounter this, start the server with --workers=1. If you need multiple workers, set "method": "rewrite-wp-config" on the defineWpConfigConsts step to write those constants to wp-config.php. The SQLite corruption report tracks the underlying issue.
Mounting folders manually
Some projects have a specific structure that requires a custom configuration; for example, your repository contains all the files in the /wp-content/ folder. So in this scenario, you can specify to the Playground CLI that it will mount your project from that folder using the --mount flag.
npx @wp-playground/cli@latest server --mount=.:/wordpress/wp-content/plugins/MY-PLUGIN-DIRECTORY
Mounting before WordPress installation
Consider mounting your WordPress project files before the WordPress installation begins. This approach is beneficial if you want to override the Playground boot process, as it can help connect Playground with WP-CLI. The --mount-before-install flag supports this process.
npx @wp-playground/cli@latest server --mount-before-install=.:/wordpress/
On Windows, the path format /host/path:/vfs/path can cause issues. To resolve this, use the flags --mount-dir and --mount-dir-before-install. These flags let you specify host and virtual file system paths in an alternative format: "/host/path" "/vfs/path".
Understanding Data Persistence and SQLite Location in server mode
By default, Playground CLI stores WordPress files and the SQLite database in temporary directories on your operating system:
<OS-TEMP-DIR>/playground-<random-id>/
├── wordpress/ # WordPress installation
├── internal/ # Playground runtime config
└── tmp/ # Temporary PHP files
Finding Your Temp Directory:
The actual location depends on your OS (these are examples or common possibilities):
- macOS/Linux: May be under
/tmp/or/private/var/folders/(varies by system) - Windows:
C:\Users\<username>\AppData\Local\Temp\
To see the exact temp directory path being used, run the CLI with the --verbosity=debug flag:
npx @wp-playground/cli@latest server --verbosity=debug
This will output something like:
Native temp dir for VFS root:
/private/var/folders/c8/mwz12ycx4s509056kby3hk180000gn/T/node-playground-cli-site-62926--62926-yQNOdvJVIgYC
Mount before WP install: /home ->
/private/var/folders/c8/mwz12ycx4s509056kby3hk180000gn/T/node-playground-cli-site-62926--62926-yQNOdvJVIgYC/home
Mount before WP install: /tmp ->
/private/var/folders/c8/mwz12ycx4s509056kby3hk180000gn/T/node-playground-cli-site-62926--62926-yQNOdvJVIgYC/tmp
Mount before WP install: /wordpress ->
/private/var/folders/c8/mwz12ycx4s509056kby3hk180000gn/T/node-playground-cli-site-62926--62926-yQNOdvJVIgYC/wordpress
Where is the SQLite Database Stored?
The database location depends on what you mount:
-
Auto-mounting wp-content or full WordPress:
- Database directory:
<your-local-project>/wp-content/database/ - ✅ Persisted locally in your project folder
- Database directory:
-
Auto-mounting plugin/theme only:
- Database directory:
<OS-TEMP-DIR>/playground-<id>/wordpress/wp-content/database/ - ⚠️ Lost when server stops (temp directories are cleaned up)
- Database directory:
-
Custom mounts: Database location follows your mount configuration
Automatic Cleanup: Playground CLI automatically removes temp directories that are:
- Older than 2 days
- No longer associated with a running process
Recommendation: To persist both your code and database when developing plugins or themes, mount the entire wp-content directory instead of just the plugin/theme folder.
Example: Mounting wp-content for persistence
# Mount your entire wp-content directory
cd my-wordpress-project
npx @wp-playground/cli@latest server --mount=./wp-content:/wordpress/wp-content
Data Persistence in start mode
When start manages the WordPress root directory, Playground CLI
automatically persists your WordPress site in a dedicated directory:
~/.wordpress-playground/sites/<path-hash>/
├── wordpress/ # WordPress installation
├── internal/ # Playground runtime config
└── tmp/ # Temporary PHP files
The <path-hash> is derived from the command's current working directory.
This ensures isolation between different projects when you run start from each
project directory.
Persistence behavior
- Default (no WordPress root mount): WordPress files and database persist in
~/.wordpress-playground/sites/<path-hash>/. Changes survive between CLI restarts. - Full WordPress directory or explicit
/wordpressmount: Automatic persistence in~/.wordpress-playground/sites/<path-hash>/is skipped. The mounted WordPress directory is the persistent store.
The database location depends on your configuration:
- Default (automatic persistence):
- Database directory:
~/.wordpress-playground/sites/<path-hash>/wordpress/wp-content/database/ - Persisted automatically between sessions
- Database directory:
- Full WordPress directory or explicit
/wordpressmount:- Database: Follows the mounted WordPress directory
- Persisted in that mounted directory