CLI
Blockstudio registra i comandi WP-CLI per gestire blocchi, pagine basate su file, record del database, funzioni RPC, processi cron, impostazioni e la configurazione linguistica WPML dal terminale.
Blocchi
Elencare tutti i blocchi
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 |
+----------------------------+---------------------+-----------+------------------------+
Filtrare solo i componenti
wp bs blocks list --components
Esportare come JSON
wp bs blocks list --format=json
Convalidare i campi memorizzati
wp bs blocks validate 42
wp bs blocks validate 42 57 --format=json
Controlla il contenuto memorizzato dei post specificati tramite ID, inclusi i blocchi
annidati innerBlocks, usando bs_validate_block().
Non esegue il rendering dei blocchi, non espande i riferimenti ai pattern sincronizzati e non modifica i post.
I blocchi sconosciuti senza estensioni Blockstudio vengono ignorati.
La tabella predefinita elenca l’ID del post, il percorso del blocco con indici a partire da zero, il nome del blocco,
il codice del problema, il percorso del campo, la sorgente e il messaggio. JSON include anche i valori originali
value e expected. Un blocco annidato può avere il percorso del blocco 0/1
e il percorso del campo cards/2/style: si tratta di percorsi distinti.
Il comando termina con 0 se non rileva problemi e con 1 se ne rileva. L’output JSON è un semplice elenco, che include [] anche in caso di esito positivo, così l’automazione può leggerlo anche quando il comando termina con 1. I post o gli ID mancanti e i formati diversi da table o json generano errori. Tutti gli ID vengono controllati prima di iniziare la convalida.
Eseguire il rendering dei blocchi
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
Esegue il rendering dei blocchi registrati come farebbe una pagina e segnala ogni avviso PHP, warning, deprecazione ed errore generato dai relativi template. Un tema può eseguire il comando in CI per verificare rapidamente i propri blocchi rispetto a Blockstudio installato. Se non si specificano nomi, viene eseguito il rendering di tutti i blocchi registrati, inclusi i componenti.
Ogni blocco viene sottoposto a rendering tramite do_blocks() a partire da un commento del blocco
con blockstudio.attributes, la struttura memorizzata dall’editor, nel contesto frontend di WP-CLI
e non nell’anteprima dell’inseritore. Non viene impostato alcun post da interrogare
per il rendering. Le isole dinamiche eseguono il rendering del corpo reale del template, invece del solo segnaposto, e l’output incidentale del template non viene incluso nel rapporto.
Il comando non salva direttamente post o valori dei campi, ma esegue i template e gli hook di rendering come normali PHP. Questi possono scrivere dati, chiamare servizi esterni o causare altri effetti collaterali. Eseguitelo su codice attendibile in un sito di test dedicato; non è un ambiente isolato di sola lettura.
Gli attributi del rendering vengono scelti per ciascun blocco:
| Caso | Attributi |
|---|---|
example |
example.attributes del block.json del blocco: i valori usati dall’anteprima dell’inseritore. |
defaults |
default di ciascun campo. Usati per i blocchi senza example.attributes; il comando stampa una riga per ciascuno. |
attributes |
I valori di --attributes, che sostituiscono l’esempio. |
--attributes accetta un oggetto JSON con i valori dei campi indicizzati per chiave di archiviazione, oppure @ e il percorso di un file che lo contiene; è richiesto esattamente un nome di blocco.
Usatelo per raggiungere rami del template non coperti dall’esempio, come una variante. I valori di esempio che generano solo immagini segnaposto nell’anteprima dell’inseritore vengono ignorati e innerBlocks dell’esempio non vengono sottoposti a rendering.
+---------------------+----------+------------+-------------------------------------------------------------------------------+------------------------------------------------------------------------------+------+
| 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 tabella elenca una riga per ogni problema. L’output JSON è un elenco con una voce per ogni blocco sottoposto a rendering, anche quelli senza problemi, così l’automazione può leggere il caso utilizzato:
[
{
"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 o Error. Un problema che si ripete nello stesso file e alla stessa riga, ad esempio in un ciclo, viene segnalato una volta per blocco. I problemi silenziati con @ non vengono segnalati. WordPress genera i propri avvisi di deprecazione, come quelli di _deprecated_function(), solo quando WP_DEBUG è abilitato.
Il comando termina con 0 se non vengono rilevati problemi e con 1 altrimenti. Nomi di blocco sconosciuti, --attributes non leggibili o non validi e formati diversi da table o json generano errori; tutti i nomi vengono controllati prima del rendering del primo blocco.
Pagine
La sincronizzazione delle pagine basate su file è esplicita. Le normali richieste WordPress non effettuano mai la ricerca completa delle pagine né scrivono i relativi post. Un runtime a freddo può leggere una volta i manifest delle raccolte per ripristinare le route, senza sincronizzare i contenuti.
wp bs pages sync
Il comando riconcilia l’intero inventario desiderato e segnala le pagine rilevate, create, aggiornate, invariate, bloccate, mantenute, rimosse e non riuscite. Se le impronte digitali corrispondono, non vengono scritti post o metadati dei post.
L’output tabellare indica le pagine modificate, bloccate, mantenute nel contenuto e rimosse, con i relativi ID dei post. JSON include le voci pages.<name>.preserved,
pages.<name>.overwritten e removedPages con il nome della pagina, la chiave,
l’ID del post e l’azione di pulizia. Un post identico dopo l’unione basata sulle chiavi viene segnalato come invariato, senza creare una revisione né aggiornare la data di modifica.
Gli stati di pubblicazione esistenti vengono mantenuti; le sostituzioni di titolo e slug gestite dai file vengono segnalate con avvisi. Consultate Proprietà dei campi dei post.
Usa --authoritative per sostituire i contenuti gestiti invece di conservare i contenuti dell’editor
associati alle chiavi, e --full per segnalare l’esecuzione come una riconciliazione completa
indipendentemente dall’identità della sorgente salvata. In entrambi i casi, ogni esecuzione confronta
l’intero inventario:
wp bs pages sync --authoritative --full
Per gli script di distribuzione che necessitano del report completo:
wp bs pages sync --format=json
Ogni pagina analizzata dal comando viene controllata per individuare gli attributi salvati dai blocchi
ma mai renderizzati: attributi che un blocco Blockstudio non dichiara come campo
né inoltra al proprio elemento radice, come un class non dichiarato. L’output tabellare
mostra un avviso per ogni pagina e blocco, la colonna dropped ne indica il numero
e il report JSON li elenca sotto pages.<name>.droppedAttributes. Le pagine
la cui sorgente non è cambiata non vengono analizzate di nuovo; vengono quindi segnalate
quando cambiano oppure alla prima sincronizzazione dopo un aggiornamento che modifica
il parser.
Il comando termina con un errore se la ricerca o la riconciliazione segnala un problema. Consulta Pagine per il contratto di identità di PHP API e della distribuzione.
Database
Elencare gli schemi
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 |
+-------------------+-------------+---------+---------------------+
Operazioni 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
Per i blocchi con un solo schema, il nome predefinito dello schema è default:
wp bs db list my-theme/leads
Migrare i record da JSONC a Storh
Usa migrate quando uno schema dispone già di un file db/{schema}.jsonc e vuoi
spostare quei record nel backend su file Storh:
wp bs db migrate my-theme/app subscribers --to=storh
Per i blocchi con schema singolo:
wp bs db migrate my-theme/app --to=storh
Il comando mantiene gli ID interi dei record, scrive in
uploads/blockstudio/db/{block-scope}/{schema}/, ricostruisce gli indici di Storh,
verifica l’archivio di destinazione e lascia intatto il file sorgente .jsonc.
Formati di output
Tutti i comandi di elenco supportano --format=table (predefinito), --format=json e
--format=csv:
wp bs db list my-theme/app subscribers --format=json
RPC
Elencare tutte le funzioni
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|
+-------------------+-------------+--------+----------------+---------+
Chiamare una funzione
wp bs rpc call my-theme/app subscribe --email=user@example.com
L’output è JSON:
{
"success": true
}
I parametri vengono passati come flag --key=value:
wp bs rpc call my-theme/app load_more --offset=10 --limit=5
Cron
Elencare tutti i processi
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 |
+-------------------+----------+----------+---------------------+
Eseguire un processo manualmente
wp bs cron run my-theme/app cleanup
Esegue immediatamente la callback, indipendentemente dalla pianificazione. Utile per il testing e il debug.
Impostazioni
Mostrare tutte le impostazioni
wp bs settings list
Recuperare un’impostazione specifica
wp bs settings get tailwind/enabled
wp bs settings get assets/enqueue
Tailwind
Compilare HTML in CSS
wp bs tailwind compile '<div class="flex items-center p-4">'
Compilare da un file
wp bs tailwind compile --file=template.html
Gestione della cache
wp bs tailwind cache path # show cache directory
wp bs tailwind cache clear # clear compiled cache
SCSS
Compilare SCSS in CSS
wp bs scss compile '$color: red; .test { color: $color; }'
Compilare da un file
wp bs scss compile --file=styles.scss
Campi personalizzati
Elencare tutti i campi personalizzati registrati
wp bs fields list
+-------+----------------+---------------------------+
| name | title | fields |
+-------+----------------+---------------------------+
| hero | Hero Section | heading, description, cta |
| card | Card | title, image, link |
+-------+----------------+---------------------------+
Asset
Elencare tutte le risorse
wp bs assets list
Filtrare per 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
Scripting
Tutti i comandi supportano --format=json per semplificare il piping:
# 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
Content Sync esporta i contenuti WordPress consentiti dai progetti in file e applica questi file nuovamente al database. È un’operazione esplicita e guidata da CLI; non sincronizza al caricamento della pagina né durante l’inizializzazione dell’amministrazione.
Consulta Sincronizzazione dei contenuti per la configurazione, il formato dei file e indicazioni su quando è opportuno gestire i contenuti del database tramite file.
Esportare i contenuti del database nei file
wp bs content pull
Limita l’esportazione a un tipo di post o a una tassonomia configurati:
wp bs content pull --post-type=team_member
wp bs content pull --taxonomy=category
Visualizzare un’anteprima senza scrivere UID o file:
wp bs content pull --dry-run
Applicare i file al database
wp bs content push
Visualizzare un’anteprima del piano di applicazione senza scrivere:
wp bs content push --dry-run
Elimina i post e i termini del database gestiti dal set di contenuti che non esistono più nei file:
wp bs content push --prune --yes
Con --prune, Blockstudio applica prima tutte le modifiche ai file, poi rimuove le entità del database gestite dal set di contenuti che non esistono più nei file. Per eseguire l’eliminazione, è necessario specificare --yes.
Controllare lo stato
wp bs content status
La tabella indica lo stato di ogni entità basata su file: unchanged, would-update, missing-db, conflict, locked oppure orphaned.
Prerendering statico
Consulta Prerendering statico per informazioni sulla cache; questi comandi la gestiscono.
Riscaldare le voci obsolete
wp bs prerender warm
Accoda gli URL pubblici obsoleti, poi esegue di nuovo il rendering di un massimo di warm.concurrency processi
dalla coda persistente di riscaldamento e stampa un riepilogo JSON con i conteggi di queued, processed,
warmed, skipped e failed. Le modifiche ai contenuti e al sito accodano
automaticamente processi sostitutivi. Esegui di nuovo il comando o lascia che il processo di
riscaldamento pianificato smaltisca una coda più ampia; un URL il cui rendering non riesce rimane
obsoleto e viene accodato di nuovo all’esecuzione successiva. In modalità graph, il processo di
riscaldamento per URL è disattivato e il comando non accoda nulla.
Generare un report sullo stato della cache
wp bs prerender status
Riporta l’identità attiva, i file, i byte, i record del grafo, lo stato della coda, il report sulla mappa di pubblicazione anticipata e i contatori di hit, miss, build e errori per ambito.
Svuotare la cache
wp bs prerender purge
Rimuove i documenti prerenderizzati del sito corrente. La successiva richiesta anonima o il successivo passaggio di riscaldamento li ricrea.
Controllare e ripulire la mappa di pubblicazione anticipata
wp bs prerender map status
wp bs prerender map prune --dry-run
wp bs prerender map prune
map status genera un report della mappa di pubblicazione anticipata a livello di installazione: le voci
e le route, i documenti delle route mancanti, le voci orphaned il cui sito
non esiste più e le voci dead la cui directory è scomparsa. map prune rimuove
le voci orfane o non più valide e stampa ciascuna voce rimossa con la relativa motivazione;
--dry-run genera lo stesso report senza scrivere. Non viene mai modificata una mappa
proprietà di un altro strumento.
WPML
Generare la configurazione linguistica
wp bs wpml config
wp bs wpml config --file=wp-content/themes/my-theme/wpml-config.xml
Stampa una configurazione wpml-config.xml che dichiara per la traduzione i campi di testo di ogni blocco registrato e i relativi campi file come ID degli allegati, oppure la scrive usando --file. In un file esistente viene sostituita solo la sezione compresa tra i marcatori Blockstudio. Consultate WPML per sapere quali elementi vengono dichiarati e come mantenere aggiornato il file.
Migrazione dei tag dei blocchi
Uno script autonomo riscrive le forme abbreviate di prefissi e alias usando la forma
canonica <bs:namespace-slug>. Non carica WordPress e non scrive nulla
se non viene specificato esplicitamente --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
Il file dei prefissi associa i prefissi gestiti dai chiamanti a namespace ordinati. Il file dei
blocchi noti è un elenco JSON di nomi di blocchi registrati. Gli alias esatti
sono facoltativi. Il report include associazioni deterministiche, hash prima/dopo,
tag sconosciuti, alias ambigui, tag dinamici ed esempi trovati nei commenti,
nei blocchi di codice, negli intervalli <pre> o <code>.
Lo scanner gestisce markup accoppiato, annidato e autochiudente, inclusi i tag letterali
nelle stringhe PHP. Mantiene gli attributi e modifica solo i nomi dei tag.
Commenti ed esempi di codice vengono riportati senza essere modificati. Gli elementi personalizzati
non correlati vengono ignorati. La migrazione non può essere applicata finché rimangono casi
sconosciuti, ambigui o dinamici, a meno che il chiamante non specifichi deliberatamente --allow-unresolved.
Se eseguito di nuovo sull’output canonico, il comando non apporta modifiche.
Consulta Migrazione per sapere perché esiste la forma canonica e quali problemi risolve.
Rimozione
wp bs teardown
Rimuove gli eventi cron e lo stato del prerendering statico di proprietà dell’installazione: la voce della mappa di pubblicazione anticipata del sito corrente e la dichiarazione WP_CACHE e il drop-in advanced-cache.php condivisi, quando non rimangono più voci di proprietà.
Le installazioni senza un hook di disattivazione del plugin, come le configurazioni incluse in Composer, possono usare questo comando per una rimozione completa. I file di configurazione non vengono modificati.