|
| 1 | +--- |
| 2 | +title: Playground CLI |
| 3 | +slug: /developers/local-development/wp-playground-cli |
| 4 | +--- |
| 5 | + |
| 6 | +# Playground CLI |
| 7 | + |
| 8 | +[@wp-playground/cli](https://www.npmjs.com/package/@wp-playground/cli) is a command-line tool that simplifies the WordPress development and testing flow. |
| 9 | +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. |
| 10 | + |
| 11 | +**Key features:** |
| 12 | + |
| 13 | +- **Quick Setup**: Set up a local WordPress environment in seconds. |
| 14 | +- **Flexibility**: Allows for configuration to adapt to different scenarios. |
| 15 | +- **Simple Environment**: No extra configuration, just a compatible Node version, and you are ready to use it. |
| 16 | + |
| 17 | +## Requirements |
| 18 | + |
| 19 | +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). |
| 20 | + |
| 21 | +## Quickstart |
| 22 | + |
| 23 | +Running the Playground CLI is as simple as go to a command-line and run: |
| 24 | + |
| 25 | +```bash |
| 26 | +npx @wp-playground/cli@latest server |
| 27 | +``` |
| 28 | + |
| 29 | + |
| 30 | + |
| 31 | +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: |
| 32 | + |
| 33 | +```bash |
| 34 | +cd my-plugin-or-theme-directory |
| 35 | +npx @wp-playground/cli@latest server --auto-mount |
| 36 | +``` |
| 37 | + |
| 38 | +### Choosing a WordPress and PHP Version |
| 39 | + |
| 40 | +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>`: |
| 41 | + |
| 42 | +```bash |
| 43 | +npx @wp-playground/cli@latest server --wp=6.8 --php=8.4 |
| 44 | +``` |
| 45 | + |
| 46 | +### Loading Blueprints |
| 47 | + |
| 48 | +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. |
| 49 | + |
| 50 | +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. |
| 51 | + |
| 52 | +**(my-blueprint.json)** |
| 53 | + |
| 54 | +```bash |
| 55 | +{ |
| 56 | + "landingPage": "/wp-admin/options-general.php?page=akismet-key-config", |
| 57 | + "login": true, |
| 58 | + "plugins": [ |
| 59 | + "hello-dolly", |
| 60 | + "https://raw.githubusercontent.com/adamziel/blueprints/trunk/docs/assets/hello-from-the-dashboard.zip" |
| 61 | + ] |
| 62 | +} |
| 63 | +``` |
| 64 | + |
| 65 | +CLI command loading a blueprint: |
| 66 | + |
| 67 | +```bash |
| 68 | +npx @wp-playground/cli@latest server --blueprint=my-blueprint.json |
| 69 | +``` |
| 70 | + |
| 71 | +### Mounting folders manually |
| 72 | + |
| 73 | +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. |
| 74 | + |
| 75 | +```bash |
| 76 | +npx @wp-playground/cli@latest server --mount=.:/wordpress/wp-content/plugins/MY-PLUGIN-DIRECTORY |
| 77 | +``` |
| 78 | + |
| 79 | +### Mounting before WordPress installation |
| 80 | + |
| 81 | +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. |
| 82 | + |
| 83 | +```bash |
| 84 | +npx @wp-playground/cli@latest server --mount-before-install=.:/wordpress/ |
| 85 | +``` |
| 86 | + |
| 87 | +:::info |
| 88 | +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"`. |
| 89 | +::: |
| 90 | + |
| 91 | +## Command and Arguments |
| 92 | + |
| 93 | +Playground CLI is simple, configurable, and unopinionated. You can set it up according |
| 94 | +to your unique WordPress setup. With the Playground CLI, you can use the following top-level commands: |
| 95 | + |
| 96 | +- **`server`**: (Default) Starts a local WordPress server. |
| 97 | +- **`run-blueprint`**: Executes a Blueprint file without starting a web server. |
| 98 | +- **`build-snapshot`**: Builds a ZIP snapshot of a WordPress site based on a Blueprint. |
| 99 | + |
| 100 | +The `server` command supports the following optional arguments: |
| 101 | + |
| 102 | +- `--port=<port>`: The port number for the server to listen on. Defaults to 9400. |
| 103 | +- `--outfile`: When building, write to this output file. |
| 104 | +- `--wp=<version>`: The version of WordPress to use. Defaults to the latest. |
| 105 | +- `--auto-mount`: Automatically mount the current directory (plugin, theme, wp-content, etc.). |
| 106 | +- `--mount=<mapping>`: Manually mount a directory (can be used multiple times). Format: `"/host/path:/vfs/path"`. |
| 107 | +- `--mount-before-install`: Mount a directory to the PHP runtime before WordPress installation (can be used multiple times). Format: `"/host/path:/vfs/path"`. |
| 108 | +- `--mount-dir`: Mount a directory to the PHP runtime (can be used multiple times). Format: `"/host/path"` `"/vfs/path"`. |
| 109 | +- `--mount-dir-before-install`: Mount a directory before WordPress installation (can be used multiple times). Format: `"/host/path"` `"/vfs/path"` |
| 110 | +- `--blueprint=<path>`: The path to a JSON Blueprint file to execute. |
| 111 | +- `--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. |
| 112 | +- `--login`: Automatically log the user in as an administrator. |
| 113 | +- `--skip-wordpress-setup`: Do not download or install WordPress. Useful if you are mounting a full WordPress directory. |
| 114 | +- `--skip-sqlite-setup`: Do not set up the SQLite database integration. |
| 115 | +- `--quiet`: Do not output logs and progress messages. |
| 116 | +- `--debug`: Print the PHP error log if an error occurs during boot. |
| 117 | + |
| 118 | +## Need some help with the CLI? |
| 119 | + |
| 120 | +With the Playground CLI, you can use the `--help` to get some support about the available commands. |
| 121 | + |
| 122 | +```bash |
| 123 | +npx @wp-playground/cli@latest --help |
| 124 | +``` |
0 commit comments