Saltar al contenido

CLI

Blockstudio registra comandos WP-CLI para gestionar bloques, páginas respaldadas por archivos, registros de base de datos, funciones RPC, tareas cron, ajustes y la configuración de idioma WPML desde el terminal.

Bloques

Listar todos los bloques

Shell
wp bs blocks list
Código
+----------------------------+---------------------+-----------+------------------------+
| name                       | title               | component | category               |
+----------------------------+---------------------+-----------+------------------------+
| my-theme/hero              | Hero                |           | my-theme               |
| my-theme/card              | Card                | yes       | my-theme               |
| my-theme/newsletter        | Newsletter          |           | my-theme               |
+----------------------------+---------------------+-----------+------------------------+

Filtrar solo componentes

Shell
wp bs blocks list --components

Mostrar como JSON

Shell
wp bs blocks list --format=json

Validar los campos almacenados

Shell
wp bs blocks validate 42
wp bs blocks validate 42 57 --format=json

Comprueba el contenido almacenado de los IDs de entrada especificados, incluidos los bloques anidados innerBlocks, mediante bs_validate_block(). No renderiza bloques, no expande referencias a patrones sincronizados ni modifica entradas. Se omiten los bloques desconocidos que no tienen extensiones Blockstudio.

La tabla predeterminada muestra el ID de la entrada, la ruta del bloque desde cero, el nombre del bloque, el código del hallazgo, la ruta del campo, el origen y el mensaje. JSON también incluye los valores originales de value y expected. Un bloque anidado puede tener la ruta de bloque 0/1 y la ruta de campo cards/2/style; son rutas distintas.

El comando termina con 0 si no hay hallazgos y con 1 si los hay. La salida JSON es una lista simple que incluye [] cuando todo va bien, para que la automatización pueda leerla incluso cuando el comando termina con 1. La ausencia de entradas o IDs, y los formatos distintos de table o json son errores. Se comprueban todos los IDs antes de iniciar la validación.

Renderizar bloques

Shell
wp bs blocks render
wp bs blocks render my-theme/hero my-theme/card
wp bs blocks render my-theme/card --attributes='{"variant":"wide"}'
wp bs blocks render my-theme/card --attributes=@card.json --format=json

Renderiza los bloques registrados como lo haría una página e informa de cada aviso PHP, advertencia, obsolescencia y error lanzado por sus plantillas. Un tema puede ejecutar el comando en CI para probar sus bloques frente a la instalación Blockstudio. Si no se indican nombres, se renderizan todos los bloques registrados, incluidos los componentes.

Cada bloque se renderiza mediante do_blocks() a partir de un comentario de bloque con blockstudio.attributes, la estructura que almacena el editor, en el contexto de frontend de WP-CLI, en lugar de la vista previa del insertador. No se configura ninguna entrada consultada para el renderizado. Las islas dinámicas renderizan el cuerpo real de su plantilla, no solo su marcador de posición, y la salida incidental de las plantillas no aparece en el informe.

El comando no guarda entradas ni valores de campos por sí mismo, pero ejecuta tus plantillas y hooks de renderizado como solicitudes normales de PHP. Pueden escribir datos, llamar a servicios externos o tener otros efectos secundarios. Ejecútalo en un sitio de prueba dedicado y con código de confianza; no es un entorno aislado de solo lectura.

Los atributos del renderizado se eligen para cada bloque:

Caso Atributos
example El example.attributes de block.json del bloque, los valores que utiliza la vista previa del insert.
defaults El default de cada campo. Se usa para bloques sin example.attributes; el comando imprime una línea por cada uno.
attributes Los valores de --attributes, que sustituyen al ejemplo.

--attributes acepta un objeto JSON con valores de campos asociados a la clave de almacenamiento, o @ y la ruta de un archivo que lo contiene, y requiere exactamente un nombre de bloque. Úsalo para llegar a ramas de la plantilla que no cubre el ejemplo, como una variante. Se omiten los valores de ejemplo que solo generan imágenes de marcador de posición en la vista previa del insertador, y no se renderizan innerBlocks del ejemplo.

Código
+---------------------+----------+------------+-------------------------------------------------------------------------------+------------------------------------------------------------------------------+------+
| block               | case     | level      | message                                                                       | file                                                                         | line |
+---------------------+----------+------------+-------------------------------------------------------------------------------+------------------------------------------------------------------------------+------+
| smoke/deprecated    | defaults | Deprecated | strlen(): Passing null to parameter #1 ($string) of type string is deprecated | /wordpress/wp-content/themes/smoke-theme/blockstudio/deprecated/index.php    | 1    |
| smoke/undefined-key | example  | Warning    | Undefined array key "subtitle"                                                | /wordpress/wp-content/themes/smoke-theme/blockstudio/undefined-key/index.php | 2    |
+---------------------+----------+------------+-------------------------------------------------------------------------------+------------------------------------------------------------------------------+------+

La tabla incluye una fila por cada problema. La salida JSON es una lista con una entrada por bloque renderizado, incluidos los que no presentan problemas, para que la automatización pueda leer qué caso se usó:

JSON
[
  {
    "block": "smoke/branch",
    "case": "attributes",
    "problems": [
      {
        "level": "Warning",
        "message": "Undefined array key \"width\"",
        "file": "/wordpress/wp-content/themes/smoke-theme/blockstudio/branch/index.php",
        "line": 2
      }
    ]
  }
]

level es Notice, Warning, Deprecated o Error. Si un problema se repite en el mismo archivo y línea, por ejemplo dentro de un bucle, se informa una vez por bloque. No se informa de los problemas silenciados con @. WordPress genera sus propios avisos de obsolescencia, como los de _deprecated_function(), solo cuando WP_DEBUG está habilitado.

El comando termina con 0 si no se encuentran problemas y con 1 en caso contrario. Los nombres de bloque desconocidos, los archivos --attributes ilegibles o no válidos y los formatos distintos de table o json son errores; se comprueban todos los nombres antes de renderizar el primer bloque.

Páginas

La sincronización de páginas respaldadas por archivos es explícita. Las solicitudes ordinarias de WordPress nunca descubren todas las páginas ni escriben entradas de página. Un entorno de ejecución recién iniciado puede leer una vez los manifiestos de colecciones para restaurar las rutas, sin sincronizar el contenido.

Shell
wp bs pages sync

El comando concilia todo el inventario deseado e informa de las páginas detectadas, creadas, actualizadas, sin cambios, bloqueadas, conservadas, eliminadas y fallidas. Las huellas digitales idénticas no generan escrituras en las entradas ni en sus metadatos.

La salida en tabla muestra las páginas modificadas, bloqueadas, cuyo contenido se ha conservado y eliminadas, junto con sus IDs de entrada. JSON incluye entradas pages.<name>.preserved, pages.<name>.overwritten y removedPages con el nombre de la página, la clave, el ID de entrada y la acción de limpieza. Si una entrada es idéntica después de combinar las claves, se informa como sin cambios, sin crear una revisión ni actualizar su fecha de modificación.

Se conservan los estados de publicación existentes; las sustituciones del título y el slug propiedad del archivo se muestran como advertencias. Consulta Propiedad de los campos de la entrada.

Use --authoritative para reemplazar el contenido administrado en vez de conservar el contenido del editor asociado a claves, y --full para informar del proceso como una reconciliación completa, independientemente de la identidad de origen almacenada. En ambos casos, cada proceso compara el inventario completo:

Shell
wp bs pages sync --authoritative --full

Para los scripts de implementación que necesiten el informe completo:

Shell
wp bs pages sync --format=json

Cada página que analiza el comando se comprueba para detectar atributos que sus bloques almacenan pero nunca muestran: atributos que un bloque Blockstudio no declara como campo ni pasa a su elemento raíz, como un class no declarado. La salida en tabla muestra una advertencia por página y bloque; la columna dropped los cuenta, y el informe JSON los enumera en pages.<name>.droppedAttributes. Las páginas cuyo origen no ha cambiado no se vuelven a analizar, por lo que se informan la próxima vez que cambien o durante la primera sincronización tras una actualización que cambie el analizador.

El comando termina con un error si el descubrimiento o la reconciliación informa de un error. Consulte Páginas para conocer el contrato de PHP API y de identidad de implementación.

Base de datos

Listar esquemas

Shell
wp bs db schemas
Código
+-------------------+-------------+---------+---------------------+
| block             | schema      | storage | fields              |
+-------------------+-------------+---------+---------------------+
| my-theme/app      | subscribers | table   | email, name, plan   |
| my-theme/app      | logs        | jsonc   | action, details     |
| my-theme/app      | events      | storh   | title, status       |
+-------------------+-------------+---------+---------------------+

Operaciones CRUD

Shell
# List records
wp bs db list my-theme/app subscribers

# List with filters
wp bs db list my-theme/app subscribers --plan=pro --limit=10

# Get a single record
wp bs db get my-theme/app subscribers 1

# Create a record
wp bs db create my-theme/app subscribers --email=a@b.com --plan=pro

# Update a record
wp bs db update my-theme/app subscribers 1 --plan=enterprise

# Delete a record
wp bs db delete my-theme/app subscribers 1

Para los bloques de un solo esquema, el nombre del esquema predeterminado es default:

Shell
wp bs db list my-theme/leads

Migrar registros de JSONC a Storh

Use migrate cuando un esquema ya tenga un archivo db/{schema}.jsonc y quiera trasladar esos registros al backend de archivos Storh:

Shell
wp bs db migrate my-theme/app subscribers --to=storh

Para bloques con un solo esquema:

Shell
wp bs db migrate my-theme/app --to=storh

El comando conserva los ID enteros de los registros, escribe en uploads/blockstudio/db/{block-scope}/{schema}/, reconstruye los índices de Storh, verifica el almacén de destino y deja intacto el archivo de origen .jsonc.

Formatos de salida

Todos los comandos de listado admiten --format=table (predeterminado), --format=json y --format=csv:

Shell
wp bs db list my-theme/app subscribers --format=json

RPC

Listar todas las funciones

Shell
wp bs rpc list
Código
+-------------------+-------------+--------+----------------+---------+
| block             | function    | public | capability     | methods |
+-------------------+-------------+--------+----------------+---------+
| my-theme/app      | subscribe   | yes    |                | POST    |
| my-theme/app      | stats       |        | edit_posts     | POST    |
| my-theme/app      | get_status  |        |                | GET,POST|
+-------------------+-------------+--------+----------------+---------+

Llamar a una función

Shell
wp bs rpc call my-theme/app subscribe --email=user@example.com

La salida es JSON:

JSON
{
  "success": true
}

Los parámetros se pasan como indicadores --key=value:

Shell
wp bs rpc call my-theme/app load_more --offset=10 --limit=5

Cron

Listar todas las tareas

Shell
wp bs cron list
Código
+-------------------+----------+----------+---------------------+
| block             | job      | schedule | next_run            |
+-------------------+----------+----------+---------------------+
| my-theme/app      | cleanup  | daily    | 2026-03-17 00:00:00 |
| my-theme/app      | sync     | hourly   | 2026-03-16 15:00:00 |
+-------------------+----------+----------+---------------------+

Ejecutar una tarea manualmente

Shell
wp bs cron run my-theme/app cleanup

Esto ejecuta la función de devolución de llamada de inmediato, sin importar la programación. Es útil para realizar pruebas y depurar.

Ajustes

Mostrar todos los ajustes

Shell
wp bs settings list

Obtener un ajuste específico

Shell
wp bs settings get tailwind/enabled
wp bs settings get assets/enqueue

Tailwind

Compilar HTML a CSS

Shell
wp bs tailwind compile '<div class="flex items-center p-4">'

Compilar desde un archivo

Shell
wp bs tailwind compile --file=template.html

Administración de caché

Shell
wp bs tailwind cache path    # show cache directory
wp bs tailwind cache clear   # clear compiled cache

SCSS

Compilar SCSS a CSS

Shell
wp bs scss compile '$color: red; .test { color: $color; }'

Compilar desde un archivo

Shell
wp bs scss compile --file=styles.scss

Campos personalizados

Listar todos los campos personalizados registrados

Shell
wp bs fields list
Código
+-------+----------------+---------------------------+
| name  | title          | fields                    |
+-------+----------------+---------------------------+
| hero  | Hero Section   | heading, description, cta |
| card  | Card           | title, image, link        |
+-------+----------------+---------------------------+

Recursos

Listar todos los recursos

Shell
wp bs assets list

Filtrar por tipo

Shell
wp bs assets list --type=global
wp bs assets list --type=admin
wp bs assets list --type=editor
wp bs assets list --type=registered

Scripts

Todos los comandos admiten --format=json para facilitar el encadenamiento mediante tuberías:

Shell
# Export all subscribers as JSON
wp bs db list my-theme/app subscribers --format=json > subscribers.json

# Count records
wp bs db list my-theme/app subscribers --format=json | jq length

# Batch delete
wp bs db list my-theme/app logs --format=json | \
  jq -r '.[].id' | \
  xargs -I {} wp bs db delete my-theme/app logs {}

Sincronización de contenido

Los proyectos de sincronización de contenido permiten incluir en una lista de permitidos el contenido WordPress y guardarlo en archivos; después, aplican esos archivos a la base de datos. El proceso es explícito y se controla mediante CLI; no se sincroniza al cargar la página ni al inicializar la administración.

Consulte Sincronización de contenido para ver la configuración, el formato de archivo y las recomendaciones sobre cuándo conviene usar contenido de base de datos basado en archivos.

Descargar contenido de la base de datos a archivos

Shell
wp bs content pull

Limite la descarga a un tipo de contenido o una taxonomía configurados:

Shell
wp bs content pull --post-type=team_member
wp bs content pull --taxonomy=category

Vista previa sin escribir UID ni archivos:

Shell
wp bs content pull --dry-run

Aplicar archivos a la base de datos

Shell
wp bs content push

Vista previa del plan de aplicación sin escribir:

Shell
wp bs content push --dry-run

Eliminar las entradas y los términos de la base de datos que pertenecen al conjunto de contenido y ya no existen en los archivos:

Shell
wp bs content push --prune --yes

Con --prune, Blockstudio aplica primero todos los cambios de archivos y, después, elimina las entidades que pertenecen al conjunto de contenido y ya no existen en los archivos. No ejecuta una depuración destructiva sin --yes.

Comprobar el estado

Shell
wp bs content status

La tabla muestra cada entidad respaldada por archivos con el estado unchanged, would-update, missing-db, conflict, locked o orphaned.

Prerenderizado estático

Consulte Prerenderizado estático para obtener información sobre la caché; estos comandos la controlan.

Actualizar entradas obsoletas

Shell
wp bs prerender warm

Encola las URL públicas obsoletas, luego vuelve a renderizar hasta warm.concurrency tareas de la cola de actualización persistente y muestra un resumen JSON con recuentos de queued, processed, warmed, skipped y failed. Los cambios en el contenido y el sitio encolan automáticamente nuevas tareas. Vuelva a ejecutar el comando, o deje que se ejecute el actualizador programado, para procesar una cola mayor; una URL que no se pueda renderizar seguirá obsoleta y volverá a encolarse la próxima vez que se ejecute el comando. En el modo graph, el actualizador por URL está desactivado y el comando no encola nada.

Informar del estado de la caché

Shell
wp bs prerender status

Informa de la identidad activa, los archivos, los bytes, los registros del grafo, el estado de la cola, el informe del mapa de respuesta temprana y los contadores de aciertos, fallos, compilaciones y errores por ámbito.

Purgar la caché

Shell
wp bs prerender purge

Elimina los documentos prerenderizados del sitio actual. La próxima solicitud anónima o el siguiente proceso de actualización los reconstruirá.

Comprobar y depurar el mapa de respuesta temprana

Shell
wp bs prerender map status
wp bs prerender map prune --dry-run
wp bs prerender map prune

map status informa del mapa de respuesta temprana de toda la instalación: sus entradas y rutas, los documentos de rutas que faltan, las entradas orphaned cuyo sitio ya no existe y las entradas dead cuyo directorio ha desaparecido. map prune elimina las entradas huérfanas y caducadas e imprime cada entrada eliminada con el motivo; --dry-run muestra el mismo informe sin escribir. Nunca modifica un mapa que pertenezca a otra herramienta.

WPML

Generar la configuración de idioma

Shell
wp bs wpml config
wp bs wpml config --file=wp-content/themes/my-theme/wpml-config.xml

Muestra un wpml-config.xml que declara los campos de texto de cada bloque registrado para su traducción y sus campos de archivos como IDs de adjuntos, o lo escribe con --file. En un archivo existente, solo se sustituye la sección entre los marcadores Blockstudio. Consulta WPML para saber qué se declara y cómo mantener el archivo actualizado.

Migración de etiquetas de bloque

Un script independiente cambia las abreviaturas de prefijo y alias por la forma canónica <bs:namespace-slug>. No carga WordPress ni escribe nada a menos que se indique explícitamente --apply:

Shell
php vendor/blockstudio/blockstudio/bin/migrate-block-tags.php \
  --root="$PWD" \
  --prefix-map=/tmp/project-prefixes.json \
  --known-blocks=/tmp/project-blocks.json \
  --aliases=/tmp/project-aliases.json \
  --report=/tmp/blockstudio-tag-migration.json \
  --dry-run

El archivo de prefijos asigna prefijos gestionados por quien realiza la llamada a espacios de nombres ordenados. El archivo de bloques conocidos es una lista JSON de nombres de bloque registrados. Los alias exactos son opcionales. El informe incluye asignaciones deterministas, hashes anteriores y posteriores, elementos desconocidos, alias ambiguos, etiquetas dinámicas y ejemplos encontrados en comentarios, bloques de código, rangos <pre> o <code>.

El analizador procesa etiquetas emparejadas, anidadas y autocerradas, incluidas las etiquetas literales en cadenas PHP. Conserva los atributos y solo cambia los nombres de las etiquetas. Los comentarios y ejemplos de código solo se incluyen en el informe. Se ignoran los elementos personalizados no relacionados. Se bloquea la aplicación de una migración mientras queden casos desconocidos, ambiguos o dinámicos, a menos que quien realiza la llamada indique deliberadamente --allow-unresolved. Si se vuelve a ejecutar el comando sobre la salida canónica, no se producen cambios.

Consulte Migración para saber por qué existe la forma canónica y qué problemas resuelve.

Desinstalación

Shell
wp bs teardown

Elimina los eventos cron y el estado de prerenderizado estático que controla una instalación: la entrada del sitio actual en el mapa de respuesta temprana y las declaraciones compartidas de advanced-cache.php y WP_CACHE una vez eliminada la última entrada gestionada. Las instalaciones sin un gancho de desactivación del plugin, como las configuraciones incluidas en Composer, pueden usar este comando para eliminarlas limpiamente. Los archivos de configuración no se modifican.