Vai al contenuto

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

Shell
wp bs blocks list
Codice
+----------------------------+---------------------+-----------+------------------------+
| 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

Shell
wp bs blocks list --components

Esportare come JSON

Shell
wp bs blocks list --format=json

Convalidare i campi memorizzati

Shell
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

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

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.

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

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

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

Shell
wp bs pages sync --authoritative --full

Per gli script di distribuzione che necessitano del report completo:

Shell
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

Shell
wp bs db schemas
Codice
+-------------------+-------------+---------+---------------------+
| 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

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

Per i blocchi con un solo schema, il nome predefinito dello schema è default:

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

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

Per i blocchi con schema singolo:

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

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

RPC

Elencare tutte le funzioni

Shell
wp bs rpc list
Codice
+-------------------+-------------+--------+----------------+---------+
| 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

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

L’output è JSON:

JSON
{
  "success": true
}

I parametri vengono passati come flag --key=value:

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

Cron

Elencare tutti i processi

Shell
wp bs cron list
Codice
+-------------------+----------+----------+---------------------+
| 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

Shell
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

Shell
wp bs settings list

Recuperare un’impostazione specifica

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

Tailwind

Compilare HTML in CSS

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

Compilare da un file

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

Gestione della cache

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

SCSS

Compilare SCSS in CSS

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

Compilare da un file

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

Campi personalizzati

Elencare tutti i campi personalizzati registrati

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

Asset

Elencare tutte le risorse

Shell
wp bs assets list

Filtrare per 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

Scripting

Tutti i comandi supportano --format=json per semplificare il piping:

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

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

Shell
wp bs content pull

Limita l’esportazione a un tipo di post o a una tassonomia configurati:

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

Visualizzare un’anteprima senza scrivere UID o file:

Shell
wp bs content pull --dry-run

Applicare i file al database

Shell
wp bs content push

Visualizzare un’anteprima del piano di applicazione senza scrivere:

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

Shell
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

Shell
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

Shell
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

Shell
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

Shell
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

Shell
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

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

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

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

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