Merge branch 'trunk' into add/file-mounting-to-nodefs

bgrgicak · web-flow · commit 84e2e0737751 · 2025-07-15T13:28:13.000+02:00
diff --git a/README.md b/README.md
@@ -76,7 +76,7 @@ These tools include:
 
 -   [Interactive Code Block for Gutenberg](https://github.com/WordPress/playground-tools/tree/trunk/packages/interactive-code-block/#readme)
 -   [WordPress Playground for Visual Studio Code](https://github.com/WordPress/playground-tools/tree/trunk/packages/vscode-extension/#readme)
--   [wp-now](https://github.com/WordPress/playground-tools/tree/trunk/packages/wp-now/#readme) CLI local development environment.
+-   [@wp-playground/cli](https://github.com/WordPress/wordpress-playground/tree/trunk/packages/playground/cli#readme) CLI local development environment.
 
 ## Cloning WordPress Playground repo
 
diff --git a/packages/docs/site/docs/developers/05-local-development/01-wp-now.md b/packages/docs/site/docs/developers/05-local-development/01-wp-now.md
@@ -3,6 +3,10 @@ title: wp-now
 slug: /developers/local-development/wp-now
 ---
 
+:::caution Package deprecated
+The NPM package @wp-now/wp-now is deprecated, won't receive updates in the future. To use a command-line tool on your developer flow, use the NPM package `@wp-playground/cli`.  
+:::
+
 # wp-now NPM package
 
 [wp-now](https://www.npmjs.com/package/@wp-now/wp-now) is a command-line tool designed to simplify the process of running WordPress locally. It provides a quick and easy way to set up a local WordPress environment with minimal configuration.
diff --git a/packages/docs/site/docs/developers/05-local-development/04-wp-playground-cli.md b/packages/docs/site/docs/developers/05-local-development/04-wp-playground-cli.md
@@ -0,0 +1,124 @@
+---
+title: Playground CLI
+slug: /developers/local-development/wp-playground-cli
+---
+
+# Playground CLI
+
+[@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.
+
+## 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
+
+Running the Playground CLI is as simple as go to a command-line and run:
+
+```bash
+npx @wp-playground/cli@latest server
+```
+
+![Playground CLI in Action](@site/static/img/developers/npx-wp-playground-server.gif)
+
+With the previous command, you only get a fresh WordPress instance to test. Most of the developers want to see their work running. If this is your case, test a plugin or a theme. You can run the CLI on your project folder and run the Playground CLI with the `--auto-mount` flag:
+
+```bash
+cd my-plugin-or-theme-directory
+npx @wp-playground/cli@latest server --auto-mount
+```
+
+### Choosing a WordPress and PHP Version
+
+By default, the CLI loads the latest stable version of WordPress and PHP 8.0 due to its improved performance. To specify your preferred versions, you can use the flag `--wp=<version>` and `--php=<version>`:
+
+```bash
+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](/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=<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)**
+
+```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
+
+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
+
+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/
+```
+
+:::info
+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"`.
+:::
+
+## 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:
+
+-   **`server`**: (Default) Starts a local WordPress server.
+-   **`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 `server` command supports the following optional arguments:
+
+-   `--port=<port>`: The port number for the server to listen on. Defaults to 9400.
+-   `--outfile`: When building, write to this output file.
+-   `--wp=<version>`: The version of WordPress to use. Defaults to the latest.
+-   `--auto-mount`: Automatically mount the current directory (plugin, theme, wp-content, etc.).
+-   `--mount=<mapping>`: 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=<path>`: 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.
+-   `--skip-wordpress-setup`: Do not download or install WordPress. Useful if you are mounting a full WordPress directory.
+-   `--skip-sqlite-setup`: Do not set up the SQLite database integration.
+-   `--quiet`: Do not output logs and progress messages.
+-   `--debug`: Print the PHP error log if an error occurs during boot.
+
+## Need some help with the CLI?
+
+With the Playground CLI, you can use the `--help` to get some support about the available commands.
+
+```bash
+npx @wp-playground/cli@latest --help
+```
diff --git a/packages/docs/site/docs/developers/05-local-development/intro.md b/packages/docs/site/docs/developers/05-local-development/intro.md
@@ -3,18 +3,17 @@ title: Local Development
 slug: /developers/local-development
 ---
 
-## Local Development with WordPress Playground
+## Local WordPress Development with Playground
 
-Playground powers offers several development environments designed to streamline the process of setting up and managing WordPress sites.
+Playground offers various development environments to streamline setting up and managing WordPress sites.
 
-The easiest way to get WordPress site up and running is to open a [public Playground web instance](/web-instance) from https://playground.wordpress.net/ (you could also [host your own WordPress Playground](/developers/architecture/host-your-own-playground)).
+For a quick start, use a [public Playground web instance](/web-instance) at https://playground.wordpress.net/. Alternatively, you can [host your own WordPress Playground](/developers/architecture/host-your-own-playground).
 
-Playground provides additional tools to check your code on a local WordPress environment. These tools are designed to enhance the development experience by prioritizing ease of installation and usability:
+Playground also provides tools for local WordPress development, prioritizing easy installation and usability:
 
--   [`wp-now`](/developers/local-development/wp-now) - CLI tool to spin up a WordPress site with a single command
+-   **[@wp-playground/cli](/developers/local-development/wp-playground-cli):** A command-line tool to quickly launch a WordPress site from your terminal.
+-   **[Visual Studio Code Extension](/developers/local-development/vscode-extension):** Integrates WordPress development directly into VS Code for a seamless experience within the popular editor.
 
--   [Visual Studio Code Extension](/developers/local-development/vscode-extension) - Integrates WordPress development directly into Visual Studio Code to get a seamless development experience within the popular code editor.
+For those needing more control, Playground offers tools for Node.js:
 
-But Playground also provides tools to use WordPress Playground in Node.js:
-
--   [WordPress Playground in Node.js](/developers/local-development/php-wasm-node) - If you need low-level control over the underlying WebAssembly PHP build, take a look at the [`@php-wasm/node` package](https://npmjs.org/@php-wasm/node) which ships the PHP WebAssembly runtime.
+-   **[WordPress Playground in Node.js](/developers/local-development/php-wasm-node):** For low-level control over the WebAssembly PHP build, explore the [`@php-wasm/node` package](https://npmjs.org/@php-wasm/node), which includes the PHP WebAssembly runtime.
diff --git a/packages/docs/site/docs/main/about/build.md b/packages/docs/site/docs/main/about/build.md
@@ -11,7 +11,7 @@ WordPress Playground can help you to create and learn WordPress quickly, even on
 
 ## Setting quickly a local WordPress environment
 
-You can seamlessly integrate Playground into your development workflow to launch a local WordPress environment quickly for testing your code. You can do this directly [from the terminal](/developers/local-development/wp-now) or [your preferred IDE.](/developers/local-development/vscode-extension)
+You can seamlessly integrate Playground into your development workflow to launch a local WordPress environment quickly for testing your code. You can do this directly [from the terminal](/developers/local-development/wp-playground-cli) or [your preferred IDE.](/developers/local-development/vscode-extension)
 
 ## Save changes done on a Block Theme and create Github Pull Requests
 
diff --git a/packages/docs/site/docs/main/contributing/contributor-day.md b/packages/docs/site/docs/main/contributing/contributor-day.md
@@ -4,16 +4,12 @@ slug: /contributing/contributor-day
 
 # WordCamp Contributor Day
 
-The [WordPress Playground VS Code extension](https://marketplace.visualstudio.com/items?itemName=WordPressPlayground.wordpress-playground) and [wp-now](https://www.npmjs.com/package/@wp-now/wp-now) streamline the process of setting up a local WordPress environment. WordPress Playground powers both—no Docker, MySQL, or Apache required.
+The [WordPress Playground VS Code extension](https://marketplace.visualstudio.com/items?itemName=WordPressPlayground.wordpress-playground) and [@wp-playground/cli](https://www.npmjs.com/package/@wp-playground/cli) streamline the process of setting up a local WordPress environment. WordPress Playground powers both—no Docker, MySQL, or Apache required.
 
-Keep reading to learn how to use these tools for [local development](/developers/local-development/wp-now) when contributing to WordPress. Please note that the extension and the NPM package are under development, and not all [Make WordPress teams](https://make.wordpress.org/) are fully supported.
+Keep reading to learn how to use these tools for [local development](/developers/local-development/wp-playground-cli) when contributing to WordPress. Please note that the extension and the NPM package are under development, and not all [Make WordPress teams](https://make.wordpress.org/) are fully supported.
 
 ## Getting Started
 
-If you’re a visual learner, here’s a step-by-step video tutorial. If you prefer reading at your own pace, skip to the written instructions below.
-
-<iframe title="Getting Started with wp-now for WordPress development at Contributor Day" width="752" height="423" src="https://video.wordpress.com/embed/Gn7XOCAM?cover=1&amp;preloadContent=metadata&amp;useAverageColor=1&amp;hd=1&amp;metadata_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJ3b3JkcHJlc3MuY29tIiwiaWF0IjoxNjg2MTQ4ODQ5LCJleHAiOjE2ODYzMjE2NDksImJsb2dfaWQiOiIyMDMxMjIxMTIiLCJndWlkIjoiR243WE9DQU0iLCJhdXRoIjoidmlkZW9wcmVzc19wbGF5YmFja190b2tlbiIsImFjY2VzcyI6InZpZGVvIiwiZXhwaXJlcyI6MTY4NjMyMTY0OX0.DJWVfePHl2nUKo8ziG81CK2VlG5Ui8vNg-dZJ7dOSq8" allow="fullscreen" loading="eager"></iframe>
-
 ### VS Code Playground extension
 
 The [Visual Studio Code Playground extension](https://marketplace.visualstudio.com/items?itemName=WordPressPlayground.wordpress-playground) is a friendly zero-setup development environment.
@@ -23,23 +19,23 @@ The [Visual Studio Code Playground extension](https://marketplace.visualstudio.c
 3. To interact with Playground, click the new icon in the **Activity Bar** and hit the **Start WordPress Server** button.
 4. A new tab will open in your browser within seconds.
 
-### wp-now NPM package
+### @wp-playground/cli NPM package
 
-`@wp-now/wp-now` is a CLI tool that allows you to spin up a WordPress site with a single command. No Docker, MySQL, or Apache are required.
+`@wp-playground/cli` is a CLI tool that allows you to spin up a WordPress site with a single command. No Docker, MySQL, or Apache are required.
 
 #### Prerequisites
 
-`wp-now` requires Node.js and NPM. If you haven’t yet, [download and install](https://nodejs.org/en/download) both before you begin.
+`@wp-playground/cli` requires Node.js 20.18 or newer and NPM. If you haven’t yet, [download and install](https://nodejs.org/en/download) both before you begin.
 
 Depending on the Make WordPress team you contribute to, you may need a different Node.js version than the one you have installed. You can use Node Version Manager (NVM) to switch between versions. [Find the installation guide here](https://github.com/nvm-sh/nvm#installing-and-updating).
 
-#### Run wp-now
+#### Running `@wp-playground/cli`
 
-You don’t have to install `wp-now` on your device to use it. Navigate to your plugin or theme directory and start `wp-now` with the following commands:
+You don’t have to install `@wp-playground/cli` on your device to use it. Navigate to your plugin or theme directory and start `@wp-playground/cli` with the following commands:
 
 ```bash
 cd my-plugin-or-theme-directory
-npx @wp-now/wp-now start
+npx @wp-playground/cli@latest server --auto-mount
 ```
 
 ## Ideas for contributors
@@ -59,15 +55,15 @@ npm run dev
 
 :::info
 
-If you’re unsure about the steps listed above, visit the official [Gutenberg Project Contributor Guide](https://developer.wordpress.org/block-editor/contributors/). Note that in this case, `wp-now` replaces `wp-env`.
+If you’re unsure about the steps listed above, visit the official [Gutenberg Project Contributor Guide](https://developer.wordpress.org/block-editor/contributors/). Note that in this case, `@wp-playground/cli` replaces `wp-env`.
 
 :::
 
-Open a new terminal terminal tab, navigate to the Gutenberg directory, and start WordPress using `wp-now`:
+Open a new terminal terminal tab, navigate to the Gutenberg directory, and start WordPress using `@wp-playground/cli`:
 
 ```bash
 cd gutenberg
-npx @wp-now/wp-now start
+npx @wp-playground/cli@latest server --auto-mount
 ```
 
 When you’re ready, commit and push your changes to your forked repository on GitHub and open a Pull Request on the Gutenberg repository.
@@ -87,7 +83,7 @@ npm install
 npm run dev
 
 # In a different terminal inside the Gutenberg directory *
-npx @wp-now/wp-now start
+npx @wp-playground/cli@latest server --auto-mount
 ```
 
 #### Test a Gutenberg PR with Playground in the browser
diff --git a/packages/docs/site/docs/main/guides/for-plugin-developers.md b/packages/docs/site/docs/main/guides/for-plugin-developers.md
@@ -193,7 +193,7 @@ Here’s an example of a **[plugin that generates Custom Post Types](https://raw
 
 From a plugins' folder in your local development environment, you can quickly load locally a Playground instance with that plugin loaded and activated.
 
-Use the [`wp-now` command](/developers/local-development/wp-now) from your plugin's root directory using your preferred command line program.
+Use the [`@wp-playground/cli` command](/developers/local-development/wp-playground-cli) from your plugin's root directory using your preferred command line program.
 
 With [Visual Studio Code](https://code.visualstudio.com/) IDE, you can also use the [Visual Studio Code extension](/developers/local-development/vscode-extension) while working in the root directory of your plugin.
 
@@ -202,7 +202,7 @@ For example:
 ```bash
 git clone git@github.com:wptrainingteam/devblog-dataviews-plugin.git
 cd devblog-dataviews-plugin
-npx @wp-now/wp-now start
+npx @wp-playground/cli server --auto-mount
 ```
 
 ### See your local changes in a Playground instance and directly create PRs in a GitHub repo with your changes
diff --git a/packages/docs/site/docs/main/guides/for-theme-developers.md b/packages/docs/site/docs/main/guides/for-theme-developers.md
@@ -214,14 +214,14 @@ The ["Stylish Press"](https://github.com/WordPress/blueprints/tree/trunk/bluepri
 
 ### Local theme development and testing with Playground
 
-From the root folder of a block theme's code, you can quickly load locally a Playground instance with that theme loaded and activated. You can do that by launching, in a theme directory, the [`wp-now` command](/developers/local-development/wp-now) from your preferred command line program or the [Visual Code Studio extension](/developers/local-development/vscode-extension) from the [Visual Studio Code](https://code.visualstudio.com/) IDE.
+From the root folder of a block theme's code, you can quickly load locally a Playground instance with that theme loaded and activated. You can do that by launching, in a theme directory, the [`@wp-playground/cli` command](/developers/local-development/wp-playground-cli) from your preferred command line program or the [Visual Code Studio extension](/developers/local-development/vscode-extension) from the [Visual Studio Code](https://code.visualstudio.com/) IDE.
 
 For example:
 
 ```
 git clone git@github.com:WordPress/community-themes.git
 cd community-themes/blue-note
-npx @wp-now/wp-now start
+npx @wp-playground/cli server --auto-mount
 ```
 
 ### Design your theme using the WordPress UI and save your changes as Pull Requests
diff --git a/packages/docs/site/sidebars.js b/packages/docs/site/sidebars.js
@@ -134,7 +134,7 @@ const sidebars = {
 						id: 'developers/local-development/intro',
 					},
 					items: [
-						'developers/local-development/wp-now',
+						'developers/local-development/wp-playground-cli',
 						'developers/local-development/vscode-extension',
 						'developers/local-development/php-wasm-node',
 					],
diff --git a/packages/docs/site/static/img/developers/npx-wp-playground-server.gif b/packages/docs/site/static/img/developers/npx-wp-playground-server.gif
