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
wp bs blocks list
+----------------------------+---------------------+-----------+------------------------+
| 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
wp bs blocks list --components
Mostrar como JSON
wp bs blocks list --format=json
Validar los campos almacenados
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
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.
+---------------------+----------+------------+-------------------------------------------------------------------------------+------------------------------------------------------------------------------+------+
| 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ó:
[
{
"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.
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:
wp bs pages sync --authoritative --full
Para los scripts de implementación que necesiten el informe completo:
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
wp bs db schemas
+-------------------+-------------+---------+---------------------+
| 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
# 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:
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:
wp bs db migrate my-theme/app subscribers --to=storh
Para bloques con un solo esquema:
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:
wp bs db list my-theme/app subscribers --format=json
RPC
Listar todas las funciones
wp bs rpc list
+-------------------+-------------+--------+----------------+---------+
| 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
wp bs rpc call my-theme/app subscribe --email=user@example.com
La salida es JSON:
{
"success": true
}
Los parámetros se pasan como indicadores --key=value:
wp bs rpc call my-theme/app load_more --offset=10 --limit=5
Cron
Listar todas las tareas
wp bs cron list
+-------------------+----------+----------+---------------------+
| 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
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
wp bs settings list
Obtener un ajuste específico
wp bs settings get tailwind/enabled
wp bs settings get assets/enqueue
Tailwind
Compilar HTML a CSS
wp bs tailwind compile '<div class="flex items-center p-4">'
Compilar desde un archivo
wp bs tailwind compile --file=template.html
Administración de caché
wp bs tailwind cache path # show cache directory
wp bs tailwind cache clear # clear compiled cache
SCSS
Compilar SCSS a CSS
wp bs scss compile '$color: red; .test { color: $color; }'
Compilar desde un archivo
wp bs scss compile --file=styles.scss
Campos personalizados
Listar todos los campos personalizados registrados
wp bs fields list
+-------+----------------+---------------------------+
| name | title | fields |
+-------+----------------+---------------------------+
| hero | Hero Section | heading, description, cta |
| card | Card | title, image, link |
+-------+----------------+---------------------------+
Recursos
Listar todos los recursos
wp bs assets list
Filtrar por tipo
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:
# 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
wp bs content pull
Limite la descarga a un tipo de contenido o una taxonomía configurados:
wp bs content pull --post-type=team_member
wp bs content pull --taxonomy=category
Vista previa sin escribir UID ni archivos:
wp bs content pull --dry-run
Aplicar archivos a la base de datos
wp bs content push
Vista previa del plan de aplicación sin escribir:
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:
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
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
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é
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é
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
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
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:
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
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.