Aller au contenu

CLI

Blockstudio enregistre les commandes WP-CLI pour gérer les blocs, les pages stockées dans des fichiers, les enregistrements de la base de données, les fonctions RPC, les tâches cron, les réglages et la configuration linguistique WPML depuis le terminal.

Blocs

Lister tous les blocs

Shell
wp bs blocks list
Code
+----------------------------+---------------------+-----------+------------------------+
| name                       | title               | component | category               |
+----------------------------+---------------------+-----------+------------------------+
| my-theme/hero              | Hero                |           | my-theme               |
| my-theme/card              | Card                | yes       | my-theme               |
| my-theme/newsletter        | Newsletter          |           | my-theme               |
+----------------------------+---------------------+-----------+------------------------+

Filtrer les composants uniquement

Shell
wp bs blocks list --components

Sortie au format JSON

Shell
wp bs blocks list --format=json

Valider les champs enregistrés

Shell
wp bs blocks validate 42
wp bs blocks validate 42 57 --format=json

Vérifie le contenu enregistré des identifiants d’articles indiqués, y compris les éléments innerBlocks imbriqués, à l’aide de bs_validate_block(). La commande ne génère pas les blocs, ne développe pas les références aux compositions synchronisées et ne modifie pas les articles. Les blocs inconnus sans extensions Blockstudio sont ignorés.

Le tableau par défaut indique l’identifiant de l’article, le chemin du bloc (indexé à partir de zéro), le nom du bloc, le code du résultat, le chemin du champ, la source et le message. JSON inclut aussi les valeurs value et expected d’origine. Le chemin d’un bloc imbriqué peut être 0/1 et celui du champ cards/2/style ; il s’agit de chemins distincts.

La commande se termine avec 0 si aucun résultat n’est trouvé et 1 si des résultats sont présents. La sortie JSON est une liste simple, qui inclut [] en cas de réussite, afin que les outils d’automatisation puissent la lire même si la commande se termine avec 1. L’absence d’articles ou d’identifiants, ainsi que les formats autres que table ou json, génèrent des erreurs. Tous les identifiants sont vérifiés avant le début de la validation.

Générer les blocs

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

Génère les blocs enregistrés comme le ferait une page et signale chaque avis PHP, avertissement, avis de dépréciation et erreur levée par leurs modèles. Un thème peut exécuter la commande en CI pour effectuer un test rapide de ses blocs avec l’Blockstudio installé. Sans noms indiqués, tous les blocs enregistrés sont générés, y compris les composants.

Chaque bloc est généré avec do_blocks() à partir d’un commentaire de bloc contenant blockstudio.attributes, la structure enregistrée par l’éditeur, dans le contexte frontal de WP-CLI plutôt que dans l’aperçu de l’outil d’insertion. Aucun article n’est défini pour la requête. Les îlots dynamiques génèrent le contenu réel de leur modèle au lieu de leur seul espace réservé, et les sorties accessoires des modèles sont exclues du rapport.

La commande n’enregistre pas elle-même les articles ni les valeurs de champ, mais elle exécute vos modèles et vos hooks de rendu comme du code PHP ordinaire. Ceux-ci peuvent écrire des données, appeler des services externes ou avoir d’autres effets de bord. Exécutez-la sur un site de test dédié avec du code de confiance ; ce n’est pas un environnement isolé en lecture seule.

Les attributs utilisés pour le rendu sont déterminés pour chaque bloc :

Cas Attributs
example example.attributes du block.json du bloc, c’est-à-dire les valeurs utilisées par l’aperçu de l’outil d’insertion.
defaults default de chaque champ. Utilisées pour les blocs sans example.attributes ; la commande affiche une ligne pour chacun.
attributes Les valeurs de --attributes, qui remplacent l’exemple.

--attributes accepte un objet JSON contenant des valeurs de champ indexées par clé de stockage, ou @ et le chemin d’un fichier qui en contient un. Il faut indiquer exactement un nom de bloc. Utilisez cette option pour atteindre des variantes de modèle absentes de l’exemple. Les valeurs d’exemple qui ne servent qu’à générer des images d’espace réservé dans l’aperçu de l’outil d’insertion sont ignorées, et les innerBlocks de l’exemple ne sont pas générés.

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

Le tableau contient une ligne par problème. La sortie JSON est une liste comportant une entrée pour chaque bloc généré, y compris ceux sans problème, afin que les outils d’automatisation puissent lire le cas utilisé :

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 peut être Notice, Warning, Deprecated ou Error. Un problème qui se répète au même fichier et à la même ligne, par exemple dans une boucle, n’est signalé qu’une fois par bloc. Les problèmes désactivés avec @ ne sont pas signalés. WordPress génère ses propres avis de dépréciation, notamment ceux de _deprecated_function(), uniquement lorsque WP_DEBUG est activé.

La commande se termine avec 0 si aucun problème n’est trouvé et avec 1 dans le cas contraire. Les noms de blocs inconnus, les fichiers --attributes illisibles ou invalides et les formats autres que table ou json génèrent des erreurs. Tous les noms sont vérifiés avant le rendu du premier bloc.

Pages

La synchronisation des pages gérées par fichiers est explicite. Les requêtes WordPress ordinaires ne découvrent jamais toutes les pages et n’écrivent pas d’articles de page. Un environnement d’exécution à froid peut lire une fois les manifestes de collection pour restaurer les routes, sans synchroniser le contenu.

Shell
wp bs pages sync

La commande réconcilie l’inventaire complet souhaité et indique le nombre de pages détectées, créées, mises à jour, inchangées, verrouillées, conservées, supprimées et en échec. Lorsque les empreintes sont identiques, aucune écriture n’est effectuée dans les articles ni dans leurs métadonnées.

La sortie sous forme de tableau indique les pages modifiées, verrouillées, conservées avec leur contenu ou supprimées, avec leurs identifiants d’article. JSON inclut des entrées pages.<name>.preserved, pages.<name>.overwritten et removedPages avec le nom de la page, la clé, l’identifiant d’article et l’action de nettoyage. Un article identique après fusion par clé est signalé comme inchangé, sans créer de révision ni modifier son horodatage de modification.

Les statuts de publication existants sont conservés ; les remplacements de titre et de slug gérés par fichier sont signalés par des avertissements. Voir Propriété des champs d’article.

Utilisez --authoritative pour remplacer le contenu géré au lieu de préserver le contenu de l’éditeur indexé, et --full pour signaler l’exécution comme un rapprochement complet, quelle que soit l’identité de source enregistrée. Dans les deux cas, chaque exécution compare l’inventaire complet :

Shell
wp bs pages sync --authoritative --full

Pour les scripts de déploiement qui ont besoin du rapport complet :

Shell
wp bs pages sync --format=json

Chaque page analysée par la commande est vérifiée pour repérer les attributs stockés par ses blocs mais jamais affichés : les attributs qu’un bloc Blockstudio ne déclare ni comme champ ni ne transmet à son élément racine, comme un class non déclaré. La sortie en tableau affiche un avertissement par page et bloc, la colonne dropped les dénombre, et le rapport JSON les répertorie sous pages.<name>.droppedAttributes. Les pages dont la source n’a pas changé ne sont pas analysées de nouveau : elles sont donc signalées lors de leur prochaine modification, ou à la première synchronisation après une mise à niveau qui modifie l’analyseur.

La commande se termine en échec si la découverte ou le rapprochement signale une erreur. Consultez Pages pour le contrat PHP API et l’identité de déploiement.

Base de données

Lister les schémas

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

Opérations 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

Pour les blocs à schéma unique, le nom du schéma est default par défaut :

Shell
wp bs db list my-theme/leads

Migrer les enregistrements JSONC vers Storh

Utilisez migrate lorsqu’un schéma possède déjà un fichier db/{schema}.jsonc et que vous souhaitez transférer ces enregistrements vers le backend de fichiers Storh :

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

Pour les blocs à schéma unique :

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

La commande préserve les identifiants d’enregistrement entiers, écrit dans uploads/blockstudio/db/{block-scope}/{schema}/, reconstruit les index Storh, vérifie le stockage cible et conserve le fichier source .jsonc.

Formats de sortie

Toutes les commandes de liste prennent en charge --format=table (par défaut), --format=json et --format=csv :

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

RPC

Lister toutes les fonctions

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

Appeler une fonction

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

La sortie est au format JSON :

JSON
{
  "success": true
}

Les paramètres sont transmis sous forme d’options --key=value :

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

Cron

Lister toutes les tâches

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

Exécuter une tâche manuellement

Shell
wp bs cron run my-theme/app cleanup

Le rappel est exécuté immédiatement, quel que soit le calendrier. Utile pour les tests et le débogage.

Paramètres

Afficher tous les réglages

Shell
wp bs settings list

Récupérer un réglage précis

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

Tailwind

Compiler HTML vers CSS

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

Compiler à partir d’un fichier

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

Gestion du cache

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

SCSS

Compiler SCSS vers CSS

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

Compiler à partir d’un fichier

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

Champs personnalisés

Lister tous les champs personnalisés enregistrés

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

Ressources

Lister tous les fichiers statiques

Shell
wp bs assets list

Filtrer par type

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

Toutes les commandes prennent en charge --format=json pour faciliter les redirections :

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 exporte le contenu WordPress autorisé des projets vers des fichiers et applique ces fichiers à la base de données. Le processus est explicite et piloté par CLI ; il ne synchronise pas le contenu au chargement d’une page ou à l’initialisation de l’administration.

Consultez Content Sync pour la configuration, le format des fichiers et les conseils sur les cas où le contenu de base de données basé sur des fichiers est adapté.

Extraire le contenu de la base de données vers des fichiers

Shell
wp bs content pull

Limitez l’extraction à un type d’article ou une taxonomie configurés :

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

Prévisualiser sans écrire d’UID ni de fichiers :

Shell
wp bs content pull --dry-run

Envoyer les fichiers vers la base de données

Shell
wp bs content push

Prévisualiser le plan d’application sans écrire :

Shell
wp bs content push --dry-run

Élaguer les articles et termes de la base de données appartenant à l’ensemble de contenu et qui n’existent plus dans les fichiers :

Shell
wp bs content push --prune --yes

Avec --prune, Blockstudio applique d’abord toutes les modifications des fichiers, puis supprime les entités appartenant à l’ensemble de contenu qui n’existent plus dans les fichiers. L’élagage destructif est refusé si --yes est absent.

Vérifier l’état

Shell
wp bs content status

Le tableau indique chaque entité gérée par fichier comme unchanged, would-update, missing-db, conflict, locked ou orphaned.

Pré-rendu statique

Consultez Pré-rendu statique pour le cache lui-même ; ces commandes le pilotent.

Réchauffer les entrées obsolètes

Shell
wp bs prerender warm

Met en file d’attente les URL publiques obsolètes, puis effectue un nouveau rendu pour jusqu’à warm.concurrency tâches de la file durable de réchauffement et affiche un récapitulatif JSON avec les nombres de queued, processed, warmed, skipped et failed. Les modifications du contenu et du site mettent automatiquement en file d’attente les tâches de remplacement. Relancez la commande ou laissez le réchauffeur planifié traiter la file ; un URL dont le rendu échoue reste obsolète et est remis en file d’attente à la prochaine exécution. En mode graph, le réchauffeur par URL est désactivé et la commande ne met rien en file d’attente.

Signaler l’état du cache

Shell
wp bs prerender status

Signale l’identité active, les fichiers, les octets, les enregistrements du graphe, l’état de la file, le rapport de la carte de pré-diffusion et les compteurs d’accès, d’absence, de génération et d’échec par portée.

Vider le cache

Shell
wp bs prerender purge

Supprime les documents pré-rendus du site actuel. La prochaine requête anonyme ou opération de réchauffement les régénère.

Vérifier et élaguer la carte de pré-diffusion

Shell
wp bs prerender map status
wp bs prerender map prune --dry-run
wp bs prerender map prune

map status signale la carte de pré-diffusion à l’échelle de l’installation : ses entrées et routes, les documents de route manquants, les entrées orphaned dont le site n’existe plus et les entrées dead dont le répertoire a disparu. map prune supprime les entrées orphelines et obsolètes et indique le motif de suppression de chacune ; --dry-run affiche le même rapport sans écrire. Une carte appartenant à un autre outil n’est jamais modifiée.

WPML

Générer la configuration linguistique

Shell
wp bs wpml config
wp bs wpml config --file=wp-content/themes/my-theme/wpml-config.xml

Affiche un wpml-config.xml qui déclare les champs texte de chaque bloc enregistré pour la traduction et ses champs de fichiers sous forme d’identifiants de pièces jointes, ou l’écrit avec --file. Dans un fichier existant, seule la section comprise entre les marqueurs Blockstudio est remplacée. Voir WPML pour connaître les déclarations et maintenir le fichier à jour.

Migration des balises de bloc

Un script autonome réécrit les formes abrégées de préfixe et d’alias selon l’écriture canonique <bs:namespace-slug>. Il ne charge pas WordPress et n’écrit rien sauf si --apply est fourni explicitement :

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

Le fichier de préfixes associe les préfixes gérés par l’appelant à des espaces de noms ordonnés. Le fichier des blocs connus est une liste JSON des noms de blocs enregistrés. Les alias exacts sont facultatifs. Le rapport inclut les correspondances déterministes, les empreintes avant et après, les balises inconnues, les alias ambigus, les balises dynamiques et les exemples trouvés dans les commentaires, les blocs de code, les plages <pre> ou <code>.

L’analyseur gère les balises jumelées, imbriquées et auto-fermantes, y compris les balises littérales dans les chaînes PHP. Il préserve les attributs et ne modifie que les noms de balises. Les commentaires et les exemples de code sont uniquement signalés dans le rapport. Les éléments personnalisés sans rapport sont ignorés. L’application de la migration est bloquée tant que des cas inconnus, ambigus ou dynamiques subsistent, sauf si l’appelant transmet délibérément --allow-unresolved. Relancer la commande sur une sortie canonique n’apporte aucune modification.

Consultez Migration pour comprendre l’origine de l’écriture canonique et les problèmes qu’elle résout.

Désinstallation

Shell
wp bs teardown

Supprime les événements cron et l’état de pré-rendu statique appartenant à une installation : l’entrée de la carte de pré-diffusion du site actuel, ainsi que le fichier drop-in partagé advanced-cache.php et la déclaration WP_CACHE une fois la dernière entrée appartenant à une installation supprimée. Les installations sans hook de désactivation de plugin, comme les configurations intégrées à Composer, utilisent cette commande pour une suppression propre. Les fichiers de configuration sont conservés.