Zum Inhalt springen

CLI

Blockstudio registriert WP-CLI-Befehle zur Verwaltung von Blöcken, dateibasierten Seiten, Datenbankeinträgen, RPC-Funktionen, cron-Jobs, Einstellungen und der WPML-Sprachkonfiguration vom Terminal aus.

Blöcke

Alle Blöcke auflisten

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

Auf Komponenten beschränken

Shell
wp bs blocks list --components

Als JSON ausgeben

Shell
wp bs blocks list --format=json

Gespeicherte Felder prüfen

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

Prüft den gespeicherten Inhalt der angegebenen Beitrags-IDs, einschließlich verschachtelter innerBlocks, mit bs_validate_block(). Blöcke werden nicht gerendert, Verweise auf synchronisierte Muster nicht aufgelöst und Beiträge nicht geändert. Unbekannte Blöcke ohne Blockstudio-Erweiterungen werden übersprungen.

Die Standardtabelle führt die Beitrags-ID, den nullbasierten Blockpfad, den Blocknamen, den Befundcode, den Feldpfad, die Quelle und die Meldung auf. JSON enthält außerdem die ursprünglichen Werte value und expected. Ein verschachtelter Block kann den Blockpfad 0/1 und den Feldpfad cards/2/style haben; dies sind getrennte Pfade.

Der Befehl wird mit 0 beendet, wenn keine Befunde vorliegen, und mit 1, wenn Befunde vorliegen. Die Ausgabe JSON ist eine einfache Liste, die bei Erfolg auch [] enthält, sodass Automatisierungen sie auch dann lesen können, wenn der Befehl mit 1 beendet wird. Fehlende Beiträge, fehlende IDs und andere Formate als table oder json sind Fehler. Alle IDs werden geprüft, bevor die Validierung beginnt.

Blöcke rendern

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

Rendert registrierte Blöcke wie auf einer Seite und meldet jeden PHP-Hinweis, die Warnung, Veraltung und ausgelösten Fehler, die ihre Templates verursachen. Ein Theme kann den Befehl in CI ausführen, um seine Blöcke mit dem installierten Blockstudio zu testen. Ohne Namen werden alle registrierten Blöcke gerendert, einschließlich Komponenten.

Jeder Block wird über do_blocks() aus einem Blockkommentar mit blockstudio.attributes gerendert, der Form, die der Editor speichert, im Frontend-Kontext von WP-CLI statt in der Inserter-Vorschau. Es wird kein abgefragter Beitrag eingerichtet. Dynamische Inseln rendern den tatsächlichen Template-Inhalt statt nur ihren Platzhalter, und nebenbei erzeugte Template-Ausgaben erscheinen nicht im Bericht.

Der Befehl speichert selbst keine Beiträge oder Feldwerte, führt deine Templates und Render-Hooks aber als gewöhnliche PHP aus. Sie können Daten schreiben, externe Dienste aufrufen oder andere Nebenwirkungen haben. Führe ihn auf einer eigens dafür vorgesehenen Testseite mit vertrauenswürdigem Code aus; er ist keine schreibgeschützte Sandbox.

Die Attribute für einen Render-Vorgang werden je Block ausgewählt:

Fall Attribute
example Die example.attributes des block.json des Blocks, die Werte, die Inserter-Vorschau verwendet.
defaults Die default jedes Felds. Für Blöcke ohne example.attributes verwendet; der Befehl gibt für jedes Feld eine Zeile aus.
attributes Die Werte von --attributes, die das Beispiel ersetzen.

--attributes akzeptiert ein JSON-Objekt mit Feldwerten, deren Schlüssel den Speicherschlüsseln entsprechen, oder @ und den Pfad zu einer Datei, die ein solches Objekt enthält. Außerdem ist genau ein Blockname erforderlich. So kannst du Template-Zweige erreichen, die im Beispiel nicht vorkommen, etwa eine Variante. Beispielwerte, die in der Inserter-Vorschau nur Platzhalterbilder erzeugen, werden übersprungen, und innerBlocks des Beispiels werden nicht gerendert.

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

Die Tabelle enthält eine Zeile pro Problem. Die Ausgabe JSON ist eine Liste mit einem Eintrag pro gerendertem Block, auch für Blöcke ohne Probleme. So können Automatisierungen den verwendeten Fall auslesen:

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 ist Notice, Warning, Deprecated oder Error. Ein Problem, das in derselben Datei und Zeile wiederholt auftritt, zum Beispiel in einer Schleife, wird pro Block einmal gemeldet. Mit @ unterdrückte Probleme werden nicht gemeldet. WordPress gibt eigene Veraltungshinweise aus, etwa die von _deprecated_function(), aber nur, wenn WP_DEBUG aktiviert ist.

Der Befehl wird mit 0 beendet, wenn keine Probleme gefunden werden, und andernfalls mit 1. Unbekannte Blocknamen, nicht lesbare oder ungültige --attributes und andere Formate als table oder json sind Fehler. Alle Namen werden geprüft, bevor der erste Block gerendert wird.

Seiten

Die Synchronisierung dateibasierter Seiten erfolgt explizit. Gewöhnliche WordPress-Anfragen führen weder eine vollständige Seitenerkennung durch noch schreiben sie Seitenbeiträge. Eine kalte Laufzeitumgebung kann einmalig Sammlungsmanifeste lesen, um Routen wiederherzustellen, ohne Inhalte zu synchronisieren.

Shell
wp bs pages sync

Der Befehl gleicht das vollständige gewünschte Inventar ab und meldet entdeckte, erstellte, aktualisierte, unveränderte, gesperrte, beibehaltene, entfernte und fehlgeschlagene Seiten. Übereinstimmende Fingerabdrücke führen zu keinen Schreibvorgängen an Beiträgen oder Beitragsmetadaten.

Die Tabellenausgabe führt geänderte, gesperrte, inhaltlich beibehaltene und entfernte Seiten mit ihren Beitrags-IDs auf. JSON enthält Einträge vom Typ pages.<name>.preserved, pages.<name>.overwritten und removedPages mit Seitenname, Schlüssel, Beitrags-ID und Bereinigungsaktion. Ein nach dem Zusammenführen anhand von Schlüsseln identischer Beitrag wird als unverändert gemeldet, ohne eine Revision zu erstellen oder den Änderungszeitpunkt vorzuverlegen.

Vorhandene Veröffentlichungsstatus bleiben erhalten; dateieigene Ersetzungen von Titel und Slug werden als Warnungen ausgegeben. Siehe Zuständigkeit für Beitragsfelder.

Verwende --authoritative, um verwaltete Inhalte zu ersetzen, statt schlüsselbasierte Editor-Inhalte beizubehalten. Mit --full wird der Durchlauf unabhängig von der gespeicherten Quellidentität als vollständiger Abgleich gemeldet. In beiden Fällen wird das vollständige Inventar verglichen:

Shell
wp bs pages sync --authoritative --full

Für Deployment-Skripte, die den vollständigen Bericht benötigen:

Shell
wp bs pages sync --format=json

Jede Seite, die der Befehl einliest, wird auf Attribute geprüft, die ihre Blöcke speichern, aber nie rendern: Attribute, die ein Blockstudio-Block weder als Feld deklariert noch an sein Stammelement weitergibt, etwa ein nicht deklariertes class. Die Tabellenausgabe zeigt für jede Seite und jeden Block eine Warnung an, die Spalte dropped zählt sie und der Bericht JSON führt sie unter pages.<name>.droppedAttributes auf. Seiten, deren Quelle sich nicht geändert hat, werden nicht erneut eingelesen. Sie werden daher beim nächsten Mal gemeldet, wenn sie sich ändern, oder bei der ersten Synchronisierung nach einem Parser-Upgrade.

Der Befehl wird mit einem Fehlerstatus beendet, wenn die Erkennung oder der Abgleich einen Fehler meldet. In Seiten findest du Informationen zum Vertrag für PHP API und Deployment-Identitäten.

Datenbank

Schemas auflisten

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

CRUD-Vorgänge

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

Bei Blöcken mit nur einem Schema wird standardmäßig default als Schemaname verwendet:

Shell
wp bs db list my-theme/leads

JSONC-Einträge nach Storh migrieren

Verwende migrate, wenn ein Schema bereits über eine db/{schema}.jsonc-Datei verfügt und du die Einträge in das dateibasierte Storh-Backend verschieben möchtest:

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

Für Blöcke mit einem Schema:

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

Der Befehl behält ganzzahlige Eintrags-IDs bei, schreibt nach uploads/blockstudio/db/{block-scope}/{schema}/, erstellt die Storh-Indizes neu, überprüft den Zielspeicher und lässt die Quelldatei .jsonc bestehen.

Ausgabeformate

Alle Auflistungsbefehle unterstützen --format=table (Standard), --format=json und --format=csv:

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

RPC

Alle Funktionen auflisten

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

Funktion aufrufen

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

Die Ausgabe ist JSON:

JSON
{
  "success": true
}

Parameter werden als --key=value-Flags übergeben:

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

Cron

Alle Jobs auflisten

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

Job manuell ausführen

Shell
wp bs cron run my-theme/app cleanup

Dadurch wird der Callback sofort und unabhängig vom Zeitplan ausgeführt. Nützlich zum Testen und Debuggen.

Einstellungen

Alle Einstellungen anzeigen

Shell
wp bs settings list

Einzelne Einstellung abrufen

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

Tailwind

HTML nach CSS kompilieren

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

Aus Datei kompilieren

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

Cache-Verwaltung

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

SCSS

SCSS nach CSS kompilieren

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

Aus Datei kompilieren

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

Benutzerdefinierte Felder

Alle registrierten benutzerdefinierten Felder auflisten

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

Assets

Alle Assets auflisten

Shell
wp bs assets list

Nach Typ filtern

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

Skripterstellung

Alle Befehle unterstützen --format=json für einfaches Weiterleiten:

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 exportiert zulässige WordPress-Inhalte in Dateien und übernimmt diese Dateien in die Datenbank. Der Vorgang ist explizit und wird durch CLI gesteuert. Er findet nicht beim Laden einer Seite oder bei der Initialisierung des Admin-Bereichs statt.

In der Content-Sync-Dokumentation findest du Konfigurationsangaben, das Dateiformat und Hinweise dazu, wann dateibasierte Datenbankinhalte sinnvoll sind.

Datenbankinhalte in Dateien ziehen

Shell
wp bs content pull

Den Pull auf einen konfigurierten Beitragstyp oder eine Taxonomie beschränken:

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

Vorschau anzeigen, ohne UIDs oder Dateien zu schreiben:

Shell
wp bs content pull --dry-run

Dateien in die Datenbank übertragen

Shell
wp bs content push

Anwendungsplan in der Vorschau anzeigen, ohne etwas zu schreiben:

Shell
wp bs content push --dry-run

Datenbankbeiträge und -begriffe, die dem Inhaltssatz gehören und in den Dateien nicht mehr vorhanden sind, entfernen:

Shell
wp bs content push --prune --yes

Mit --prune wendet Blockstudio zuerst alle Dateiänderungen an und entfernt anschließend dem Inhaltssatz zugehörige Entitäten, die in den Dateien nicht mehr vorhanden sind. Ein destruktives Bereinigen wird nur ausgeführt, wenn --yes angegeben ist.

Status prüfen

Shell
wp bs content status

Die Tabelle zeigt jede dateibasierte Entität mit dem Status unchanged, would-update, missing-db, conflict, locked oder orphaned.

Statisches Prerendering

Weitere Informationen zum Cache selbst findest du unter Statisches Prerendering; diese Befehle steuern ihn.

Veraltete Einträge aktualisieren

Shell
wp bs prerender warm

Fügt veraltete öffentliche URLs zur Warteschlange hinzu, rendert dann bis zu warm.concurrency Aufträge aus der dauerhaften Aktualisierungswarteschlange neu und gibt eine Zusammenfassung von JSON mit den Zählwerten queued, processed, warmed, skipped und failed aus. Änderungen an Inhalten und der Website fügen automatisch Ersatzaufträge hinzu. Führe den Befehl erneut aus oder lass den geplanten Aktualisierungsprozess eine größere Warteschlange abarbeiten. Ein URL, dessen Rendering fehlschlägt, bleibt veraltet und wird beim nächsten Durchlauf erneut in die Warteschlange aufgenommen. Im Modus graph ist der Aktualisierungsprozess pro URL deaktiviert und der Befehl fügt nichts zur Warteschlange hinzu.

Cache-Status melden

Shell
wp bs prerender status

Meldet die aktive Identität, Dateien, Bytes, Graphdatensätze, den Warteschlangenstatus, den Bericht zur Early-Serve-Zuordnung sowie Zähler für Treffer, Fehlschläge, Builds und Fehler je Bereich.

Cache leeren

Shell
wp bs prerender purge

Entfernt die vorgerenderten Dokumente der aktuellen Website. Die nächste anonyme Anfrage oder ein Aktualisierungslauf erstellt sie neu.

Early-Serve-Zuordnung prüfen und bereinigen

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

map status meldet die installationsweite Early-Serve-Zuordnung: ihre Einträge und Routen, fehlende Routendokumente, orphaned-Einträge, deren Website nicht mehr existiert, sowie dead-Einträge, deren Verzeichnis fehlt. map prune entfernt verwaiste und ungültige Einträge und gibt jeden entfernten Eintrag samt Begründung aus; --dry-run gibt denselben Bericht aus, ohne etwas zu schreiben. Eine Zuordnung, die einem anderen Tool gehört, wird nie verändert.

WPML

Sprachkonfiguration erstellen

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

Gibt eine wpml-config.xml aus, die die Textfelder aller registrierten Blöcke zur Übersetzung und deren Dateifelder als Anhangs-IDs deklariert, oder schreibt sie mit --file. In einer vorhandenen Datei wird nur der Abschnitt zwischen den Blockstudio-Markierungen ersetzt. Unter WPML erfährst du, was deklariert wird und wie du die Datei aktuell hältst.

Migration von Block-Tags

Ein eigenständiges Skript schreibt Präfix- und Alias-Kurzformen in die kanonische Schreibweise <bs:namespace-slug> um. Es lädt WordPress nicht und schreibt nichts, sofern --apply nicht ausdrücklich angegeben wird:

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

Die Präfixdatei ordnet vom Aufrufer verwaltete Präfixe geordneten Namespaces zu. Die Datei mit bekannten Blöcken ist eine JSON-Liste registrierter Blocknamen. Exakte Aliase sind optional. Der Bericht enthält deterministische Zuordnungen, Hashes vor und nach der Änderung, unbekannte Tags, mehrdeutige Aliase, dynamische Tags sowie Beispiele aus Kommentaren, Codeblöcken, <pre>– oder <code>-Bereichen.

Der Scanner verarbeitet gepaarte, verschachtelte und selbstschließende Markups, einschließlich wörtlicher Tags in PHP-Zeichenfolgen. Er erhält Attribute und ändert nur Tagnamen. Kommentare und Codebeispiele erscheinen nur im Bericht. Nicht zugehörige benutzerdefinierte Elemente werden ignoriert. Eine Migration kann nicht angewendet werden, solange unbekannte, mehrdeutige oder dynamische Fälle vorliegen, es sei denn, der Aufrufer gibt ausdrücklich --allow-unresolved an. Bei einer erneuten Ausführung mit kanonischer Ausgabe entstehen keine Änderungen.

Unter Migration erfährst du, warum es die kanonische Schreibweise gibt und welche Probleme sie löst.

Deinstallation

Shell
wp bs teardown

Entfernt die cron-Ereignisse und den statischen Prerendering-Status, die einer Installation gehören: den Early-Serve-Zuordnungseintrag der aktuellen Website sowie den gemeinsam genutzten advanced-cache.php-Drop-in und die WP_CACHE-Deklaration, sobald der letzte zugehörige Eintrag entfernt wurde. Installationen ohne Plugin-Deaktivierungshook, etwa Composer-basierte Setups, können so sauber entfernt werden. Konfigurationsdateien bleiben unverändert.