Playground CLI

@wp-playground/cli es una herramienta de línea de comandos que simplifica el flujo de desarrollo y pruebas de WordPress. Playground CLI soporta el montaje automático de un directorio con un plugin, tema o instalación de WordPress. Pero si necesitas flexibilidad, el CLI soporta comandos de montaje para personalizar tu entorno local.

Características principales:

• Configuración rápida: Configura un entorno WordPress local en segundos.
• Flexibilidad: Permite la configuración para adaptarse a diferentes escenarios.
• Entorno simple: Sin configuración extra, solo una versión compatible de Node y estás listo para usarlo.

El Playground CLI incluye dos comandos principales para ejecutar WordPress localmente:

• start (Simplificado): Detecta automáticamente el tipo de tu proyecto, persiste los sitios entre sesiones y abre el navegador automáticamente.
• server (Avanzado): Ofrece control manual completo sobre la configuración. Ideal para configuraciones personalizadas, pipelines CI/CD o cuando necesitas control detallado.

Requisitos

El Playground CLI requiere Node.js 20.18 o superior, que es la versión recomendada de Soporte a Largo Plazo (LTS). Puedes descargarlo desde el sitio web de Node.js.

Inicio rápido

Para ejecutar el Playground CLI, abre una línea de comandos y usa uno de los siguientes comandos:

Usar start (Simplificado)

El comando start es la forma más fácil de empezar. Detecta automáticamente el tipo de tu proyecto, persiste tu sitio y abre el navegador:

npx @wp-playground/cli@latest start

Cuando se ejecuta dentro de un directorio de plugin o tema, start monta tu proyecto automáticamente:

cd my-plugin
npx @wp-playground/cli@latest start

Diferencias principales respecto a server:

• El auto-login está habilitado por defecto
• Abre el navegador automáticamente
• Monta el proyecto automáticamente por defecto

Usar server (Avanzado)

El comando server ofrece control total sobre la configuración:

npx @wp-playground/cli@latest server

Persistencia automática del sitio: Por defecto, el comando start mantiene tu sitio WordPress persistente entre sesiones. Tus archivos y base de datos se almacenan en ~/.wordpress-playground/sites/<path-hash>/, donde <path-hash> se deriva del directorio de tu proyecto. Así puedes detener y reiniciar el CLI sin perder tu trabajo.

Es útil cuando:

• Quieres una instalación limpia de WordPress
• Estás probando escenarios de instalación nueva
• Los datos de tu sitio se han corrompido o son inconsistentes

información

La opción --reset solo funciona con start. Para server, elimina manualmente el directorio del sitio persistido en ~/.wordpress-playground/sites/<path-hash>/.

Elegir una versión de WordPress y PHP

Por defecto, el CLI carga la última versión estable de WordPress y PHP 8.3 por su mejor rendimiento. Para especificar tus versiones preferidas, puedes usar las opciones --wp=<version> y --php=<version>:

npx @wp-playground/cli@latest server --wp=6.8 --php=8.3

Cargar Blueprints

Una forma de llevar tu experiencia de desarrollo con Playground CLI al siguiente nivel es integrar con Blueprints. Para quienes no conozcan esta tecnología, permite a los desarrolladores configurar el estado inicial de sus instancias de WordPress Playground.

Con la opción --blueprint=<blueprint-address>, los desarrolladores pueden ejecutar un Playground con un estado inicial personalizado. Usaremos el ejemplo siguiente.

(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"
  ]
}

Comando CLI que carga un blueprint:

npx @wp-playground/cli@latest server --blueprint=my-blueprint.json

Montar carpetas manualmente

Algunos proyectos tienen una estructura específica que requiere configuración personalizada; por ejemplo, tu repositorio contiene todos los archivos en la carpeta /wp-content/. En ese caso, puedes indicar al Playground CLI que montará tu proyecto desde esa carpeta usando la opción --mount.

npx @wp-playground/cli@latest server --mount=.:/wordpress/wp-content/plugins/MY-PLUGIN-DIRECTORY

Montar antes de la instalación de WordPress

Considera montar los archivos de tu proyecto WordPress antes de que comience la instalación. Este enfoque es útil si quieres sobrescribir el proceso de arranque del Playground, ya que puede ayudar a conectar Playground con WP-CLI. La opción --mount-before-install permite este proceso.

npx @wp-playground/cli@latest server --mount-before-install=.:/wordpress/

información

En Windows, el formato de ruta /host/path:/vfs/path puede causar problemas. Para resolverlo, usa las opciones --mount-dir y --mount-dir-before-install. Estas opciones permiten especificar las rutas del host y del sistema de archivos virtual en un formato alternativo: "/host/path" "/vfs/path".

Entender la persistencia de datos y la ubicación de SQLite en modo server

Por defecto, Playground CLI almacena los archivos de WordPress y la base de datos SQLite en directorios temporales de tu sistema operativo:

<OS-TEMP-DIR>/playground-<random-id>/
├── wordpress/          # Instalación de WordPress
├── internal/           # Configuración del runtime de Playground
└── tmp/                # Archivos temporales de PHP

Encontrar tu directorio temporal:

La ubicación real depende de tu SO (estos son ejemplos o posibilidades habituales):

• macOS/Linux: Puede estar en /tmp/ o /private/var/folders/ (varía según el sistema)
• Windows: C:\Users\<username>\AppData\Local\Temp\

Para ver la ruta exacta del directorio temporal en uso, ejecuta el CLI con la opción --verbosity=debug:

npx @wp-playground/cli@latest server --verbosity=debug

Esto mostrará algo como:

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

¿Dónde se almacena la base de datos SQLite?

La ubicación de la base de datos depende de lo que montes:

• Montaje automático de wp-content o WordPress completo:

  • Base de datos: <tu-proyecto-local>/wp-content/database/.ht.sqlite
  • ✅ Persistida localmente en la carpeta de tu proyecto

• Solo montaje automático de plugin/tema:

  • Base de datos: <OS-TEMP-DIR>/playground-<id>/wordpress/wp-content/database/.ht.sqlite
  • ⚠️ Se pierde al detener el servidor (los directorios temporales se eliminan)

• Montajes personalizados: La ubicación de la base de datos sigue tu configuración de montaje

Limpieza automática: Playground CLI elimina automáticamente directorios temporales que:

• Tengan más de 2 días
• No estén asociados a un proceso en ejecución

Recomendación: Para persistir tanto tu código como la base de datos al desarrollar plugins o temas, monta todo el directorio wp-content en lugar de solo la carpeta del plugin/tema.

Ejemplo: Montar wp-content para persistencia

# Mount your entire wp-content directory
cd my-wordpress-project
npx @wp-playground/cli@latest server --mount=./wp-content:/wordpress/wp-content

Persistencia de datos en modo start

En modo start, Playground CLI persiste automáticamente tu sitio WordPress en un directorio dedicado:

~/.wordpress-playground/sites/<path-hash>/
├── wordpress/          # Instalación de WordPress
├── internal/           # Configuración del runtime de Playground
└── tmp/                # Archivos temporales de PHP

El <path-hash> se deriva de la ruta del directorio de tu proyecto. Así se aíslan los proyectos y se persisten los cambios automáticamente.

Comportamiento de la persistencia

• Por defecto (sin montaje explícito): Los archivos y la base de datos de WordPress persisten en ~/.wordpress-playground/sites/<path-hash>/. Los cambios se mantienen entre reinicios del CLI.
• Montaje explícito de /wordpress: Si indicas una ruta de montaje para /wordpress, se omite la persistencia automática. Tu configuración de montaje tiene prioridad.

La ubicación de la base de datos depende de tu configuración:

• Por defecto (persistencia automática):
  • Base de datos: ~/.wordpress-playground/sites/<path-hash>/wordpress/wp-content/database/.ht.sqlite
  • Persistida automáticamente entre sesiones

Restablecer un sitio persistido

Para empezar de cero, usa la opción --reset con el comando start:

npx @wp-playground/cli@latest start --reset

Comando y argumentos

Playground CLI es simple, configurable y sin opiniones fijas. Puedes configurarlo según tu entorno WordPress. Con Playground CLI puedes usar los siguientes comandos de nivel superior:

• start: (Simplificado) Inicia un servidor WordPress local con detección automática del proyecto, persistencia del sitio y apertura del navegador.
• server: (Avanzado) Inicia un servidor WordPress local con control manual completo de la configuración.
• run-blueprint: Ejecuta un archivo Blueprint sin iniciar un servidor web.
• build-snapshot: Genera un snapshot ZIP de un sitio WordPress a partir de un Blueprint.

El comando start tiene un argumento dedicado:

• --reset: Elimina el sitio almacenado y empieza de cero. Por defecto: false.

El comando server admite los siguientes argumentos opcionales:

• --port=<port>: Puerto en el que escucha el servidor. Por defecto: 9400.
• --version: Muestra el número de versión.
• --outfile: Al construir, escribe en este archivo de salida.
• --site-url=<url>: URL del sitio para WordPress. Por defecto: http://127.0.0.1:{port}.
• --wp=<version>: Versión de WordPress a usar. Por defecto: la más reciente.
• --php=<version>: Versión de PHP. Opciones: 8.5, 8.4, 8.3, 8.2, 8.1, 8.0, 7.4. Por defecto: 8.5.
• --auto-mount[=<path>]: Monta automáticamente un directorio. Sin ruta, monta el directorio de trabajo actual. Puedes montar un directorio WordPress, de plugin, de tema, wp-content o cualquier directorio con archivos PHP y HTML.
• --mount=<mapping>: Monta un directorio manualmente (puede usarse varias veces). Formato: "/host/path:/vfs/path".
• --mount-before-install: Monta un directorio en el runtime PHP antes de la instalación de WordPress (puede usarse varias veces). Formato: "/host/path:/vfs/path".
• --mount-dir: Monta un directorio en el runtime PHP (puede usarse varias veces). Formato: "/host/path" "/vfs/path".
• --mount-dir-before-install: Monta un directorio antes de la instalación de WordPress (puede usarse varias veces). Formato: "/host/path" "/vfs/path".
• --blueprint=<path>: Ruta del archivo JSON Blueprint a ejecutar.
• --blueprint-may-read-adjacent-files: Opción de consentimiento: permite que los recursos "empaquetados" en un blueprint local lean archivos del mismo directorio que el blueprint.
• --login: Inicia sesión automáticamente como administrador.
• --wordpress-install-mode <mode>: Controla cómo Playground prepara WordPress antes del arranque. Por defecto: download-and-install. Otras opciones: install-from-existing-files, install-from-existing-files-if-needed, do-not-attempt-installing.
• --skip-sqlite-setup: No configurar la integración de la base de datos SQLite.
• --verbosity=<level>: Nivel de logs y mensajes de progreso. Opciones: quiet, normal, debug. Por defecto: normal.
• --debug: Muestra el log de errores de PHP si ocurre un error durante el arranque.
• --follow-symlinks: Permite que Playground siga enlaces simbólicos montando automáticamente directorios y archivos enlazados encontrados en directorios montados.
• --internal-cookie-store: Habilita el manejo interno de cookies. Cuando está habilitado, Playground gestiona las cookies internamente con un HttpCookieStore que persiste las cookies entre peticiones. Cuando está deshabilitado, las cookies se gestionan externamente (p. ej. por el navegador en entornos Node.js). Por defecto: false.
• --phpmyadmin[=<path>]: Instala phpMyAdmin para gestionar la base de datos. La URL de phpMyAdmin se mostrará tras el arranque. Opcionalmente especifica una ruta de URL personalizada (por defecto: /phpmyadmin).
• --xdebug: Habilita Xdebug. Por defecto: false.
• --experimental-devtools: Habilita herramientas de desarrollo experimentales en el navegador. Por defecto: false.
• --experimental-unsafe-ide-integration=<ide>: Configura la integración de Xdebug en VS Code (vscode) y PhpStorm (phpstorm).
• --experimental-multi-worker=<number>: Habilita soporte experimental multi-worker, que requiere un directorio /wordpress respaldado por un sistema de archivos real. Pasa un número positivo para el número de workers; en caso contrario, por defecto es el número de CPUs menos 1.

precaución

Con la opción --follow-symlinks, los enlaces simbólicos pueden exponer archivos fuera de los directorios montados a Playground y suponer un riesgo de seguridad.

¿Necesitas ayuda con el CLI?

Con Playground CLI puedes usar la opción --help para ver la lista completa de comandos y argumentos disponibles.

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

Uso programático

El Playground CLI también puede controlarse de forma programática desde JavaScript/TypeScript con la función runCLI. Consulta la guía de uso programático para detalles sobre automatización y pruebas.