CLI
Blockstudio registra comandos WP-CLI para gerenciar blocos, páginas baseadas em arquivos, registros de banco de dados, funções RPC, tarefas cron, configurações e a configuração de idioma WPML pelo terminal.
Blocos
Listar todos os blocos
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 apenas componentes
wp bs blocks list --components
Gerar saída como JSON
wp bs blocks list --format=json
Validar campos armazenados
wp bs blocks validate 42
wp bs blocks validate 42 57 --format=json
Verifica o conteúdo armazenado dos IDs de publicação especificados, incluindo innerBlocks aninhados, usando bs_validate_block().
Não renderiza blocos, não expande referências a padrões sincronizados nem modifica publicações. Blocos desconhecidos sem extensões Blockstudio são ignorados.
A tabela padrão lista o ID da publicação, o caminho do bloco baseado em zero, o nome do bloco, o código do problema, o caminho do campo, a origem e a mensagem. JSON também inclui os valores originais de value e expected. Um bloco aninhado pode ter o caminho de bloco 0/1 e o caminho de campo cards/2/style; são caminhos separados.
O comando termina com 0 quando não há problemas e com 1 quando há problemas. A saída JSON é uma lista simples, que inclui [] em caso de sucesso, para que a automação possa lê-la mesmo quando o comando termina com 1. Publicações inexistentes, IDs inexistentes e formatos diferentes de table ou json são erros. Todos os IDs são verificados antes do início da validação.
Renderizar blocos
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 os blocos registrados como uma página faria e informa cada aviso PHP, advertência, descontinuação e erro lançado pelos modelos. Um tema pode executar o comando em CI para testar rapidamente seus blocos com o Blockstudio instalado. Sem nomes, todos os blocos registrados são renderizados, incluindo componentes.
Cada bloco é renderizado por do_blocks() a partir de um comentário de bloco com blockstudio.attributes, o formato armazenado pelo editor, no contexto de frontend de WP-CLI, em vez da prévia do inseridor. Nenhuma publicação consultada é configurada para a renderização. Ilhas dinâmicas renderizam o corpo real do modelo, em vez de apenas o marcador, e a saída incidental do modelo não aparece no relatório.
O próprio comando não salva publicações nem valores de campos, mas executa seus modelos e hooks de renderização como PHP comuns. Eles podem gravar dados, chamar serviços externos ou causar outros efeitos colaterais. Execute-o com código confiável em um site de teste dedicado; ele não é um ambiente isolado somente para leitura.
Os atributos de uma renderização são escolhidos por bloco:
| Caso | Atributos |
|---|---|
example |
O example.attributes do block.json do bloco, os valores usados pela prévia do inseridor. |
defaults |
O default de cada campo. Usado para blocos sem example.attributes; o comando imprime uma linha para cada campo. |
attributes |
Os valores de --attributes, substituindo o exemplo. |
--attributes aceita um objeto JSON com valores de campos identificados pela chave de armazenamento ou @ e o caminho de um arquivo que contenha um, e exige exatamente um nome de bloco. Use-o para acessar ramificações do modelo que o exemplo não alcança, como uma variante. Valores de exemplo que só geram imagens de marcador na prévia do inseridor são ignorados, e innerBlocks do exemplo não são renderizados.
+---------------------+----------+------------+-------------------------------------------------------------------------------+------------------------------------------------------------------------------+------+
| 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 |
+---------------------+----------+------------+-------------------------------------------------------------------------------+------------------------------------------------------------------------------+------+
A tabela lista uma linha por problema. A saída JSON é uma lista com uma entrada por bloco renderizado, incluindo blocos sem problemas, para que a automação possa ler qual caso foi usado:
[
{
"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 é Notice, Warning, Deprecated ou Error. Um problema que se repete no mesmo arquivo e linha, por exemplo, em um loop, é informado uma vez por bloco. Problemas silenciados com @ não são informados. WordPress gera seus próprios avisos de descontinuação, como os de _deprecated_function(), somente quando WP_DEBUG está ativado.
O comando termina com 0 quando nenhum problema é encontrado e com 1 caso contrário. Nomes de bloco desconhecidos, arquivos --attributes ilegíveis ou inválidos e formatos diferentes de table ou json são erros, e todos os nomes são verificados antes da renderização do primeiro bloco.
Páginas
A sincronização de páginas baseadas em arquivos é explícita. Solicitações WordPress comuns nunca fazem uma descoberta completa de páginas nem gravam posts de páginas. Um runtime frio pode ler manifestos de coleções uma vez para restaurar rotas, sem sincronizar o conteúdo.
wp bs pages sync
O comando reconcilia todo o inventário desejado e informa as páginas descobertas, criadas, atualizadas, inalteradas, bloqueadas, preservadas, removidas e com falha. Impressões digitais idênticas não geram gravações de publicações nem de metadados de publicação.
A saída em tabela identifica as páginas alteradas, bloqueadas, com conteúdo preservado e removidas, junto com seus IDs de publicação. JSON inclui entradas pages.<name>.preserved, pages.<name>.overwritten e removedPages com o nome da página, a chave, o ID da publicação e a ação de limpeza. Uma publicação idêntica após a mesclagem por chave é informada como inalterada, sem criar uma revisão nem atualizar o registro de data de modificação.
Os status de publicação existentes são preservados; substituições de título e slug controladas por arquivo são exibidas como avisos. Consulte Propriedade dos campos da publicação.
Use --authoritative para substituir o conteúdo gerenciado em vez de preservar o conteúdo do editor
com chaves, e --full para informar a execução como uma reconciliação completa,
independentemente da identidade da origem armazenada. Em ambos os casos, cada execução compara o inventário completo:
wp bs pages sync --authoritative --full
Para scripts de implantação que precisam do relatório completo:
wp bs pages sync --format=json
Cada página analisada pelo comando é verificada quanto a atributos que seus blocos armazenam,
mas nunca renderizam: atributos que um bloco Blockstudio não declara como campo
nem encaminha ao elemento raiz, como um class não declarado. A saída em tabela mostra um aviso por página e bloco; a coluna dropped contabiliza esses casos,
e o relatório JSON os lista em pages.<name>.droppedAttributes. Páginas
cuja origem não mudou não são analisadas novamente, então elas serão informadas
na próxima alteração ou na primeira sincronização após uma atualização que modificar o analisador.
O comando termina com falha quando a descoberta ou reconciliação informa um erro. Consulte Páginas para conhecer o contrato de identidade de PHP API e de implantação.
Banco de dados
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 |
+-------------------+-------------+---------+---------------------+
Operações 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 blocos com um único esquema, o nome do esquema padrão é default:
wp bs db list my-theme/leads
Migrar registros de JSONC para Storh
Use migrate quando um esquema já tiver um arquivo db/{schema}.jsonc e você quiser
mover esses registros para o backend de arquivos Storh:
wp bs db migrate my-theme/app subscribers --to=storh
Para blocos com um único esquema:
wp bs db migrate my-theme/app --to=storh
O comando preserva os IDs inteiros dos registros, grava em
uploads/blockstudio/db/{block-scope}/{schema}/, recria os índices de Storh,
verifica o armazenamento de destino e mantém o arquivo de origem .jsonc no lugar.
Formatos de saída
Todos os comandos de listagem aceitam --format=table (padrão), --format=json e
--format=csv:
wp bs db list my-theme/app subscribers --format=json
RPC
Listar todas as funções
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|
+-------------------+-------------+--------+----------------+---------+
Chamar uma função
wp bs rpc call my-theme/app subscribe --email=user@example.com
A saída é JSON:
{
"success": true
}
Os parâmetros são passados como opções --key=value:
wp bs rpc call my-theme/app load_more --offset=10 --limit=5
Cron
Listar todas as tarefas
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 |
+-------------------+----------+----------+---------------------+
Executar uma tarefa manualmente
wp bs cron run my-theme/app cleanup
Isso executa o callback imediatamente, independentemente da programação. Útil para testes e depuração.
Configurações
Mostrar todas as configurações
wp bs settings list
Obter uma configuração específica
wp bs settings get tailwind/enabled
wp bs settings get assets/enqueue
Tailwind
Compilar HTML para CSS
wp bs tailwind compile '<div class="flex items-center p-4">'
Compilar a partir de um arquivo
wp bs tailwind compile --file=template.html
Gerenciamento de cache
wp bs tailwind cache path # show cache directory
wp bs tailwind cache clear # clear compiled cache
SCSS
Compilar SCSS para CSS
wp bs scss compile '$color: red; .test { color: $color; }'
Compilar a partir de um arquivo
wp bs scss compile --file=styles.scss
Campos personalizados
Listar todos os campos personalizados registrados
wp bs fields list
+-------+----------------+---------------------------+
| name | title | fields |
+-------+----------------+---------------------------+
| hero | Hero Section | heading, description, cta |
| card | Card | title, image, link |
+-------+----------------+---------------------------+
Recursos
Listar todos os 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 os comandos aceitam --format=json para facilitar o uso em pipes:
# 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 {}
Content Sync
O Content Sync exporta para arquivos o conteúdo permitido de WordPress em projetos e aplica esses arquivos de volta ao banco de dados. É explícito e orientado por CLI; não sincroniza ao carregar uma página nem ao inicializar o admin.
Consulte Sincronização de conteúdo para ver a configuração, o formato dos arquivos e orientações sobre quando o conteúdo do banco de dados baseado em arquivos é uma boa opção.
Exportar o conteúdo do banco de dados para arquivos
wp bs content pull
Limite a exportação a um tipo de post ou taxonomia configurado:
wp bs content pull --post-type=team_member
wp bs content pull --taxonomy=category
Pré-visualize sem gravar UIDs ou arquivos:
wp bs content pull --dry-run
Aplicar arquivos ao banco de dados
wp bs content push
Pré-visualize o plano de aplicação sem gravar:
wp bs content push --dry-run
Remova posts e termos do banco de dados pertencentes ao conjunto de conteúdo que já não existem nos arquivos:
wp bs content push --prune --yes
Com --prune, Blockstudio aplica primeiro todas as alterações nos arquivos e, em seguida, remove as entidades pertencentes ao conjunto de conteúdo que já não existem nos arquivos. O comando se recusa a executar uma remoção destrutiva sem --yes.
Verificar o status
wp bs content status
A tabela informa cada entidade baseada em arquivo como unchanged, would-update, missing-db, conflict, locked ou orphaned.
Pré-renderização estática
Consulte Pré-renderização estática para ver o cache em si; estes comandos o controlam.
Aquecer entradas obsoletas
wp bs prerender warm
Enfileira URLs públicas obsoletas, renderiza novamente até warm.concurrency tarefas
da fila persistente de aquecimento e exibe um resumo JSON com as contagens de queued, processed,
warmed, skipped e failed. Alterações no conteúdo e no site enfileiram automaticamente tarefas substitutas. Execute o comando novamente, ou deixe o aquecedor agendado
executar, para processar uma fila maior; uma URL que não renderizar continuará
obsoleta e será enfileirada novamente na próxima execução. No modo graph, o aquecedor por URL fica desativado e o comando não enfileira nada.
Informar o estado do cache
wp bs prerender status
Informa a identidade ativa, arquivos, bytes, registros do grafo, estado da fila, o relatório do mapa de atendimento antecipado e os contadores de acertos/falhas de cache e de construções por escopo.
Limpar o cache
wp bs prerender purge
Remove os documentos pré-renderizados do site atual. A próxima solicitação anônima ou execução de aquecimento os recria.
Verificar e limpar o mapa de atendimento antecipado
wp bs prerender map status
wp bs prerender map prune --dry-run
wp bs prerender map prune
map status informa o mapa de atendimento antecipado de toda a instalação: suas entradas e
rotas, documentos de rota ausentes, entradas orphaned cujo site já não existe
e entradas dead cujo diretório desapareceu. map prune remove
entradas órfãs e inativas e exibe cada entrada removida com o motivo;
--dry-run exibe o mesmo relatório sem gravar. Um mapa pertencente a outra
ferramenta nunca é alterado.
WPML
Gerar a configuração de idioma
wp bs wpml config
wp bs wpml config --file=wp-content/themes/my-theme/wpml-config.xml
Imprime um wpml-config.xml que declara os campos de texto de cada bloco registrado para tradução e seus campos de arquivo como IDs de anexo, ou grava a configuração com --file. Em um arquivo existente, somente a seção entre os marcadores Blockstudio é substituída. Consulte WPML para saber o que é declarado e como manter o arquivo atualizado.
Migração de tags de blocos
Um script independente reescreve as formas abreviadas de prefixos e aliases para a forma
canônica <bs:namespace-slug>. Ele não carrega WordPress e não grava nada
a menos que --apply seja fornecido explicitamente:
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
O arquivo de prefixos associa prefixos controlados pelo chamador a namespaces ordenados. O arquivo de blocos conhecidos é uma lista JSON de nomes de blocos registrados. Aliases exatos são
opcionais. O relatório inclui mapeamentos determinísticos, hashes antes/depois,
tags desconhecidas, aliases ambíguos, tags dinâmicas e exemplos encontrados em comentários,
blocos de código, intervalos <pre> ou <code>.
O scanner processa marcação pareada, aninhada e autocontida, incluindo tags literais
em strings PHP. Ele preserva os atributos e altera apenas os nomes das tags.
Comentários e exemplos de código aparecem apenas no relatório. Elementos personalizados
sem relação são ignorados. A aplicação de uma migração é bloqueada enquanto houver casos desconhecidos, ambíguos ou dinâmicos, a menos que o chamador passe deliberadamente --allow-unresolved.
Executar o comando novamente sobre a saída canônica não produz alterações.
Consulte Migração para saber por que existe a forma canônica e o que ela resolve.
Desinstalação
wp bs teardown
Remove os eventos cron e o estado de pré-renderização estática pertencentes à instalação: a entrada do mapa de atendimento antecipado do site atual e o componente compartilhado advanced-cache.php
e a declaração WP_CACHE, quando não houver mais nenhuma entrada pertencente à instalação.
Instalações sem um gancho de desativação de plugin, como configurações incluídas em Composer, usam este recurso para uma remoção limpa. Os arquivos de configuração permanecem intactos.