Title: Playground CLI Published: July 15, 2026 Last modified: July 16, 2026 --- # Playground CLI ## In this article * [Requirements](https://developer.wordpress.org/playground/developers/local-development/wp-playground-cli/?output_format=md#requirements) * [Quickstart](https://developer.wordpress.org/playground/developers/local-development/wp-playground-cli/?output_format=md#quickstart) - [Using start (Simplified)](https://developer.wordpress.org/playground/developers/local-development/wp-playground-cli/?output_format=md#using-start-simplified) * [Migrating from wp-now](https://developer.wordpress.org/playground/developers/local-development/wp-playground-cli/?output_format=md#migrating-from-wp-now) - [Using server (Advanced)](https://developer.wordpress.org/playground/developers/local-development/wp-playground-cli/?output_format=md#using-server-advanced) - [Choosing a WordPress and PHP Version](https://developer.wordpress.org/playground/developers/local-development/wp-playground-cli/?output_format=md#choosing-a-wordpress-and-php-version) - [Loading Blueprints](https://developer.wordpress.org/playground/developers/local-development/wp-playground-cli/?output_format=md#loading-blueprints) - [Mounting folders manually](https://developer.wordpress.org/playground/developers/local-development/wp-playground-cli/?output_format=md#mounting-folders-manually) - [Mounting before WordPress installation](https://developer.wordpress.org/playground/developers/local-development/wp-playground-cli/?output_format=md#mounting-before-wordpress-installation) - [Understanding Data Persistence and SQLite Location in server mode](https://developer.wordpress.org/playground/developers/local-development/wp-playground-cli/?output_format=md#understanding-data-persistence-and-sqlite-location-in-server-mode) - [Data Persistence in start mode](https://developer.wordpress.org/playground/developers/local-development/wp-playground-cli/?output_format=md#data-persistence-in-start-mode) * [Command and Arguments](https://developer.wordpress.org/playground/developers/local-development/wp-playground-cli/?output_format=md#command-and-arguments) - [Loading PHP.wasm extensions](https://developer.wordpress.org/playground/developers/local-development/wp-playground-cli/?output_format=md#loading-php-wasm-extensions) * [Need some help with the CLI?](https://developer.wordpress.org/playground/developers/local-development/wp-playground-cli/?output_format=md#need-some-help-with-the-cli) * [Programmatic usage](https://developer.wordpress.org/playground/developers/local-development/wp-playground-cli/?output_format=md#programmatic-usage) [ Back to top](https://developer.wordpress.org/playground/developers/local-development/wp-playground-cli/?output_format=md#wp--skip-link--target) [@wp-playground/cli](https://www.npmjs.com/package/@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](https://developer.wordpress.org/playground/developers/local-development/wp-playground-cli/?output_format=md#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](https://nodejs.org/en/download). ## 󠀁[Quickstart](https://developer.wordpress.org/playground/developers/local-development/wp-playground-cli/?output_format=md#quickstart)󠁿 To run the Playground CLI, open a command line and use one of the following commands: ### 󠀁[Using start (Simplified)](https://developer.wordpress.org/playground/developers/local-development/wp-playground-cli/?output_format=md#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: ```bash npx @wp-playground/cli@latest start ``` When run inside a plugin or theme directory, `start` automatically mounts your project: ```bash 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](https://developer.wordpress.org/playground/developers/local-development/wp-playground-cli/?output_format=md#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=./plugin` picked the project and the saved site. * With Playground CLI, `start` saves the site for the current directory. For the closest match, `cd` into the project first, then run `start`. * When Playground CLI creates WordPress for you, it keeps the WordPress files in `~/.wordpress-playground/sites//`. * 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=./plugin` still mounts that folder, but it does not make `./plugin` the 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)](https://developer.wordpress.org/playground/developers/local-development/wp-playground-cli/?output_format=md#using-server-advanced)󠁿 The `server` command provides full control over configuration: ```bash npx @wp-playground/cli@latest server ``` ![Playground CLI in Action](https://i0.wp.com/raw.githubusercontent.com/WordPress/ wordpress-playground/refs/heads/trunk/packages/docs/site/static/img/developers/npx- wp-playground-server.gif?ssl=1) **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//`, where ` ` 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//`. ### 󠀁[Choosing a WordPress and PHP Version](https://developer.wordpress.org/playground/developers/local-development/wp-playground-cli/?output_format=md#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=` and `--php=`: ```bash npx @wp-playground/cli@latest server --wp=6.8 --php=8.4 ``` ### 󠀁[Loading Blueprints](https://developer.wordpress.org/playground/developers/local-development/wp-playground-cli/?output_format=md#loading-blueprints)󠁿 One way to take your Playground CLI development experience to the next level is to integrate with [Blueprints](https://developer.wordpress.org/playground/blueprints/getting-started/). For those unfamiliar with this technology, it allows developers to configure the initial state for their WordPress Playground instances. Using the `--blueprint=` flag, developers can run a Playground with a custom initial state. We’ll use the example below to do this. **(my-blueprint.json)** ```bash { "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: ```bash npx @wp-playground/cli@latest server --blueprint=my-blueprint.json ``` ### 󠀁[Mounting folders manually](https://developer.wordpress.org/playground/developers/local-development/wp-playground-cli/?output_format=md#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. ```bash npx @wp-playground/cli@latest server --mount=.:/wordpress/wp-content/plugins/MY-PLUGIN-DIRECTORY ``` ### 󠀁[Mounting before WordPress installation](https://developer.wordpress.org/playground/developers/local-development/wp-playground-cli/?output_format=md#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. ```bash 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](https://developer.wordpress.org/playground/developers/local-development/wp-playground-cli/?output_format=md#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**: ``` /playground-/ ├── 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\\AppData\Local\Temp\` To see the exact temp directory path being used, run the CLI with the `--verbosity =debug` flag: ```bash 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: `/wp-content/database/.ht.sqlite` - ✅ **Persisted locally** in your project folder * **Auto-mounting plugin/theme only**: - Database: `/playground-/wordpress/wp-content/database/.ht. sqlite` - ⚠️ **Lost when server stops** (temp directories are cleaned up) * **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** ```bash # 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](https://developer.wordpress.org/playground/developers/local-development/wp-playground-cli/?output_format=md#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// ├── wordpress/ # WordPress installation ├── internal/ # Playground runtime config └── tmp/ # Temporary PHP files ``` The `` 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](https://developer.wordpress.org/playground/developers/local-development/wp-playground-cli/?output_format=md#persistence-behavior)󠁿 * **Default (no WordPress root mount)**: WordPress files and database persist in` ~/.wordpress-playground/sites//`. Changes survive between CLI restarts. * **Full WordPress directory or explicit `/wordpress` mount**: Automatic persistence in `~/.wordpress-playground/sites//` is skipped. The mounted WordPress directory is the persistent store. The database location depends on your configuration: * **Default (automatic persistence)**: - Database: `~/.wordpress-playground/sites//wordpress/wp-content/ database/.ht.sqlite` - **Persisted automatically** between sessions * **Full WordPress directory or explicit `/wordpress` mount**: - Database: Follows the mounted WordPress directory - **Persisted in that mounted directory** #### 󠀁[Resetting a persisted site](https://developer.wordpress.org/playground/developers/local-development/wp-playground-cli/?output_format=md#resetting-a-persisted-site)󠁿 To start fresh, use the `--reset` flag with the `start` command: ```bash npx @wp-playground/cli@latest start --reset ``` ## 󠀁[Command and Arguments](https://developer.wordpress.org/playground/developers/local-development/wp-playground-cli/?output_format=md#command-and-arguments)󠁿 Playground CLI is simple, configurable, and unopinionated. You can set it up according to your unique WordPress setup. With the Playground CLI, you can use the following top-level commands: * **`start`**: (Simplified) Starts a local WordPress server with automatic project detection, site persistence, and browser opening. * **`server`**: (Advanced) Starts a local WordPress server with full manual control over configuration. * **`run-blueprint`**: Executes a Blueprint file without starting a web server. * **`build-snapshot`**: Builds a ZIP snapshot of a WordPress site based on a Blueprint. The `start` command supports these common optional arguments. Run `npx @wp-playground/ cli@latest start --help` for the full list: * `--path=`: Path to the project directory. Defaults to the current working directory. * `--wp=`: WordPress version to use. Defaults to the latest. * `--php=`: PHP version to use. Defaults to PHP 8.3. * `--port=`: The port number for the server to listen on. Defaults to 9400 when available. * `--blueprint=`: The path to a JSON Blueprint file to execute. * `--login`: Automatically log the user in as an administrator. Defaults to true. * `--skip-browser`: Do not open the site in your default browser. * `--reset`: Delete the stored site and start fresh. Defaults to false. * `--no-auto-mount`: Disable automatic project detection. The `server` command supports these common optional arguments. Run `npx @wp-playground/ cli@latest server --help` for the full list: * `--port=`: The port number for the server to listen on. Defaults to 9400. * `--version`: Show version number. * `--site-url=`: Site URL to use for WordPress. Defaults to `http://127.0.0.1:{ port}`. * `--wp=`: The version of WordPress to use. Defaults to the latest. * `--php=`: PHP version to use. Choices: `8.5`, `8.4`, `8.3`, `8.2`, ` 8.1`, `8.0`, `7.4`. Defaults to `8.3`. * `--auto-mount[=]`: Automatically mount a directory. If no path is provided, mounts the current working directory. You can mount a WordPress directory, a plugin directory, a theme directory, a wp-content directory, or any directory containing PHP and HTML files. * `--mount=`: Manually mount a directory (can be used multiple times). Format: `"/host/path:/vfs/path"`. * `--mount-before-install`: Mount a directory to the PHP runtime before WordPress installation (can be used multiple times). Format: `"/host/path:/vfs/path"`. * `--mount-dir`: Mount a directory to the PHP runtime (can be used multiple times). Format: `"/host/path"` `"/vfs/path"`. * `--mount-dir-before-install`: Mount a directory before WordPress installation( can be used multiple times). Format: `"/host/path"` `"/vfs/path"` * `--blueprint=`: The path to a JSON Blueprint file to execute. * `--blueprint-may-read-adjacent-files`: Consent flag: Allow “bundled” resources in a local blueprint to read files in the same directory as the blueprint file. * `--login`: Automatically log the user in as an administrator. * `--wordpress-install-mode `: Control how Playground prepares WordPress before booting. Defaults to `download-and-install`. Other options: `install-from- existing-files` (install using files you’ve mounted), `install-from-existing- files-if-needed` (skip setup when an existing site is detected), and `do-not- attempt-installing` (never download or install WordPress). * `--skip-sqlite-setup`: Do not set up the SQLite database integration. * `--verbosity=`: Output logs and progress messages. Choices: `quiet`, ` normal`, `debug`. Defaults to `normal`. * `--debug`: Print the PHP error log if an error occurs during boot. * `--follow-symlinks`: Allow Playground to follow symlinks by automatically mounting symlinked directories and files encountered in mounted directories. * `--internal-cookie-store`: Enable internal cookie handling. When enabled, Playground will manage cookies internally using an HttpCookieStore that persists cookies across requests. When disabled, cookies are handled externally (e.g., by a browser in Node.js environments). Defaults to false. * `--phpmyadmin[=]`: Install phpMyAdmin for database management. The phpMyAdmin URL will be printed after boot. Optionally specify a custom URL path (default:`/ phpmyadmin`). * `--xdebug`: Enable Xdebug. Defaults to false. * `--php-extension=`: Load a PHP.wasm extension manifest before PHP starts. Accepts local paths, `file:` URLs, and HTTP(S) URLs. Can be used multiple times. * `--experimental-devtools`: Enable experimental browser development tools. Defaults to false. * `--experimental-unsafe-ide-integration=`: Set up the Xdebug integration on VS Code (`vscode`) and PhpStorm (`phpstorm`). * `--workers=`: Number of request-handling worker threads. Pass a positive integer, or `auto` to use one worker per CPU core (minus one). Defaults to `min( 6, cpus-1)`. Useful for multi-client workloads (e.g. parallel e2e suites) that need more than 6 in-flight requests. * `--experimental-multi-worker=`: Deprecated. Use `--workers=` instead. The value of this flag is ignored. ### 󠀁[Loading PHP.wasm extensions](https://developer.wordpress.org/playground/developers/local-development/wp-playground-cli/?output_format=md#loading-php-wasm-extensions)󠁿 Playground CLI can load external PHP.wasm extensions before PHP starts. Pass a manifest produced by `@php-wasm/compile-extension`, or a published manifest such as the SQLite Database Integration native parser: ```bash npx @wp-playground/cli@latest server \ --php=8.5 \ --php-extension=https://wordpress.github.io/sqlite-database-integration/wp_mysql_parser-wasm-extension/latest/manifest.json \ --blueprint=https://wordpress.github.io/sqlite-database-integration/blueprint.json ``` For local development, point the flag at a local manifest: ```bash npx @wp-playground/cli@latest server \ --php=8.5 \ --php-extension=./dist/wp_mysql_parser/manifest.json ``` `--php-extension` is repeatable. The manifest selects the `.so` artifact matching the active PHP version and can also stage sidecar files, `.ini` settings, and environment variables before startup. External extensions are JSPI side modules. If your Node.js build does not expose JSPI, the CLI rejects the extension request during startup. Use a Node.js build with JSPI support when testing custom extensions locally. See [Loading PHP extensions](https://developer.wordpress.org/playground/developers/apis/javascript-api/php-extensions) and [Building PHP extensions](https://developer.wordpress.org/playground/developers/apis/javascript-api/build-php-extensions) for manifest format, compiler helpers, and dependency notes. With the flag `--follow-symlinks`, the following symlinks will expose files outside mounted directories to Playground and could be a security risk. ## 󠀁[Need some help with the CLI?](https://developer.wordpress.org/playground/developers/local-development/wp-playground-cli/?output_format=md#need-some-help-with-the-cli)󠁿 With the Playground CLI, you can use the `--help` flag to get the full list of available commands and arguments. ```bash npx @wp-playground/cli@latest --help ``` ## 󠀁[Programmatic usage](https://developer.wordpress.org/playground/developers/local-development/wp-playground-cli/?output_format=md#programmatic-usage)󠁿 The Playground CLI can also be controlled programmatically from JavaScript/TypeScript using the `runCLI` function. See the [Programmatic Usage guide](https://developer.wordpress.org/playground/guides/programmatic-playground-cli) for details on automation and testing. First published July 15, 2026 Last updated July 16, 2026 Edit article [ Improve it on GitHub: Playground CLI ](https://raw.githubusercontent.com/WordPress/wordpress-playground/trunk/packages/docs/site/docs/developers/05-local-development/04-wp-playground-cli.md) Changelog [ See list of changes: Playground CLI ](https://developer.wordpress.org/playground/developers/local-development/wp-playground-cli/?output_format=md#) [ Previous: Local Development](https://developer.wordpress.org/playground/developers/local-development/) [ Next: VS Code extension](https://developer.wordpress.org/playground/developers/local-development/vscode-extension/)