Pular para o conteúdo

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

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 apenas componentes

Shell
wp bs blocks list --components

Gerar saída como JSON

Shell
wp bs blocks list --format=json

Validar campos armazenados

Shell
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

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

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    |
+---------------------+----------+------------+-------------------------------------------------------------------------------+------------------------------------------------------------------------------+------+

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:

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

Shell
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:

Shell
wp bs pages sync --authoritative --full

Para scripts de implantação que precisam do relatório completo:

Shell
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

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       |
+-------------------+-------------+---------+---------------------+

Operações 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 blocos com um único esquema, o nome do esquema padrão é default:

Shell
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:

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

Para blocos com um único esquema:

Shell
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:

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

RPC

Listar todas as funções

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|
+-------------------+-------------+--------+----------------+---------+

Chamar uma função

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

A saída é JSON:

JSON
{
  "success": true
}

Os parâmetros são passados como opções --key=value:

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

Cron

Listar todas as tarefas

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 |
+-------------------+----------+----------+---------------------+

Executar uma tarefa manualmente

Shell
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

Shell
wp bs settings list

Obter uma configuração específica

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

Tailwind

Compilar HTML para CSS

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

Compilar a partir de um arquivo

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

Gerenciamento de cache

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

SCSS

Compilar SCSS para CSS

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

Compilar a partir de um arquivo

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

Campos personalizados

Listar todos os 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 os 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 os comandos aceitam --format=json para facilitar o uso em pipes:

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 {}

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

Shell
wp bs content pull

Limite a exportação a um tipo de post ou taxonomia configurado:

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

Pré-visualize sem gravar UIDs ou arquivos:

Shell
wp bs content pull --dry-run

Aplicar arquivos ao banco de dados

Shell
wp bs content push

Pré-visualize o plano de aplicação sem gravar:

Shell
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:

Shell
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

Shell
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

Shell
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

Shell
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

Shell
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

Shell
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

Shell
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:

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

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

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