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.

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 the following command:

npx @wp-playground/cli@latest server

With the previous command, you only get a fresh WordPress instance to test. Most developers will want to test their own work. To test a plugin or a theme, navigate to your project folder and run the CLI with the --auto-mount flag:

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.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.3

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

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/

información

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.
• --verbosity: Output logs and progress messages. Choices are "quiet", "normal" or "debug". Defaults to "normal".
• --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 flag to get the full list of available commands and arguments.

npx @wp-playground/cli@latest --help

Programmatic Usage with JavaScript

The Playground CLI can also be controlled programmatically from your JavaScript/TypeScript code using the runCLI function. This gives you direct access to all CLI functionalities within your code, which is useful for automating end-to-end tests. Let's cover the basics of using runCLI.

Running a WordPress instance with a specific version

Using the runCLI function, you can specify options like the PHP and WordPress versions. In the example below, we request PHP 8.3, the latest version of WordPress, and to be automatically logged in. All supported arguments are defined in the RunCLIArgs type.

import { runCLI, RunCLIArgs, RunCLIServer } from "@wp-playground/cli";

let cliServer: RunCLIServer;

cliServer = await runCLI({
    command: 'server',
    php: '8.3',
    wp: 'latest',
    login: true
} as RunCLIArgs);

To execute the code above, the developer can set their preferred method. A simple way to execute this code is to save it as a .ts file and run it with a tool like tsx. For example: tsx my-script.ts

Setting a Blueprint

You can provide a blueprint in two ways: either as an object literal directly passed to the blueprint property, or as a string containing the path to an external .json file.

import { runCLI, RunCLIServer } from "@wp-playground/cli";

let cliServer: RunCLIServer;

cliServer = await runCLI({
  command: 'server',
  wp: 'latest',
  blueprint: {
    steps: [
        {
          "step": "setSiteOptions",
          "options": {
              "blogname": "Blueprint Title",
              "blogdescription": "A great blog description"
          }
        }
    ],
  },
});

For full type-safety when defining your blueprint object, you can import and use the BlueprintDeclaration type from the @wp-playground/blueprints package:

import type { BlueprintDeclaration } from '@wp-playground/blueprints';

const myBlueprint: BlueprintDeclaration = {
  landingPage: "/wp-admin/",
  steps: [
    {
      "step": "installTheme",
      "themeData": {
        "resource": "wordpress.org/themes",
        "slug": "twentytwentyone"
      },
      "options": {
        "activate": true
      }
    }
  ]
};

Mounting a plugin programmatically

It is possible to mount local directories programmatically using runCLI. The options mount and mount-before-install are available. The hostPath property expects a path to a directory on your local machine. This path should be relative to where your script is being executed.

	cliServer = await runCLI({
      command: 'server',
      login: true,
      'mount-before-install': [
        {
          hostPath: './[my-plugin-local-path]',
          vfsPath: '/wordpress/wp-content/plugins/my-plugin',
        },
      ],
    });

With those options we can combine mounting parts of the project with blueprints, for example:

import { runCLI, RunCLIArgs, RunCLIServer } from "@wp-playground/cli";

let cliServer: RunCLIServer;

cliServer = await runCLI({
    command: 'server',
    php: '8.3',
    wp: 'latest',
    login: true,
    mount: [
        {
            "hostPath": "./plugin/",
            "vfsPath": "/wordpress/wp-content/plugins/playwright-test"
        }
    ],
    blueprint: {
        steps: [
            {
                "step": "activatePlugin",
                "pluginPath": "/wordpress/wp-content/plugins/playwright-test/plugin-playwright.php"
            }
        ]
    }
} as RunCLIArgs);