CLI
Blockstudio registers WP-CLI commands for managing blocks, file-backed pages, database records, RPC functions, cron jobs, settings, and the WPML language configuration from the terminal.
Blocks
List all blocks
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 |
+----------------------------+---------------------+-----------+------------------------+
Filter to components only
wp bs blocks list --components
Output as JSON
wp bs blocks list --format=json
Validate stored fields
wp bs blocks validate 42
wp bs blocks validate 42 57 --format=json
Checks the stored content of the specified post IDs, including nested
innerBlocks, using bs_validate_block().
It does not render blocks, expand synced pattern references, or modify posts.
Unknown blocks without Blockstudio extensions are skipped.
The default table lists the post ID, zero-based block path, block name,
finding code, field path, source, and message. JSON also includes the original
value and expected values. A nested block can have the block path 0/1
and the field path cards/2/style; these are separate paths.
The command exits with 0 for no findings and 1 when findings exist.
JSON output is a plain list, including [] on success, so automation can
read it even when the command exits with 1. Missing posts, missing IDs, and
formats other than table or json are errors. All IDs are checked before
validation begins.
Render blocks
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
Renders registered blocks the way a page does and reports every PHP notice, warning, deprecation, and thrown error their templates raise. A theme can run the command in CI to smoke-test its blocks against the installed Blockstudio. Without names, every registered block is rendered, including components.
Each block is rendered through do_blocks() from a block comment with
blockstudio.attributes, the shape the editor stores, in WP-CLI’s frontend
context rather than the inserter preview. No queried post is set up for the
render. Dynamic islands render their real template body rather than only their
placeholder, and incidental template output is kept out of the report.
The command does not save posts or field values itself, but it executes your templates and render hooks as ordinary PHP. They can write data, call external services, or have other side effects. Run it against trusted code on a dedicated test site; it is not a read-only sandbox.
The attributes of a render are chosen per block:
| Case | Attributes |
|---|---|
example |
The example.attributes of the block’s block.json, the values the inserter preview uses. |
defaults |
The default of each field. Used for blocks without example.attributes; the command prints a line for each. |
attributes |
The values of --attributes, replacing the example. |
--attributes takes a JSON object of field values keyed by storage key, or
@ and the path of a file that contains one, and needs exactly one block name.
Use it to reach template branches that the example does not, such as a
variant. Example values that only generate placeholder images in the inserter
preview are skipped, and innerBlocks of the example are not rendered.
+---------------------+----------+------------+-------------------------------------------------------------------------------+------------------------------------------------------------------------------+------+
| 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 |
+---------------------+----------+------------+-------------------------------------------------------------------------------+------------------------------------------------------------------------------+------+
The table lists one row per problem. JSON output is a list with one entry per rendered block, including blocks without problems, so automation can read the case that was used:
[
{
"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 is Notice, Warning, Deprecated, or Error. A problem that
repeats at the same file and line, for example in a loop, is reported once per
block. Problems silenced with @ are not reported. WordPress raises its own
deprecation notices, such as those of _deprecated_function(), only while
WP_DEBUG is enabled.
The command exits with 0 when no problems are found and 1 otherwise. Unknown
block names, unreadable or invalid --attributes, and formats other than
table or json are errors, and all names are checked before the first block
is rendered.
Pages
File-backed page synchronization is explicit. Ordinary WordPress requests never perform complete page discovery or write page posts. A cold runtime may read collection manifests once to restore routes, without synchronizing content.
wp bs pages sync
The command reconciles the complete desired inventory and reports discovered, created, updated, unchanged, locked, preserved, removed, and failed pages. Equal fingerprints produce no post or post-meta writes.
Table output names changed, locked, content-preserved, and removed pages with
their post IDs. JSON includes pages.<name>.preserved,
pages.<name>.overwritten, and removedPages entries with the page name, key,
post ID, and cleanup action. An identical post after keyed merging is reported
as unchanged without creating a revision or advancing its modified timestamp.
Existing publication statuses are preserved; file-owned title and slug replacements are printed as warnings. See Post Field Ownership.
Use --authoritative to replace managed content instead of preserving keyed
editor content, and --full to report the pass as a full reconciliation
regardless of the stored source identity. Every pass compares the complete
inventory either way:
wp bs pages sync --authoritative --full
For deployment scripts that need the complete report:
wp bs pages sync --format=json
Every page the command parses is checked for attributes that its blocks store
but never render: attributes a Blockstudio block neither declares as a field
nor forwards to its root element, such as an undeclared class. The table
output prints a warning per page and block, the dropped column counts them,
and the JSON report lists them under pages.<name>.droppedAttributes. Pages
whose source did not change are not parsed again, so they are reported the
next time they change, or on the first sync after an upgrade that changes the
parser.
The command exits unsuccessfully when discovery or reconciliation reports an error. See Pages for the PHP API and deployment identity contract.
Database
List schemas
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 |
+-------------------+-------------+---------+---------------------+
CRUD operations
# 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
For single-schema blocks, the schema name defaults to default:
wp bs db list my-theme/leads
Migrate JSONC records to Storh
Use migrate when a schema already has a db/{schema}.jsonc file and you want
to move those records into the Storh file backend:
wp bs db migrate my-theme/app subscribers --to=storh
For single-schema blocks:
wp bs db migrate my-theme/app --to=storh
The command preserves integer record IDs, writes to
uploads/blockstudio/db/{block-scope}/{schema}/, rebuilds Storh indexes,
verifies the target store, and leaves the source .jsonc file in place.
Output formats
All list commands support --format=table (default), --format=json, and
--format=csv:
wp bs db list my-theme/app subscribers --format=json
RPC
List all functions
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|
+-------------------+-------------+--------+----------------+---------+
Call a function
wp bs rpc call my-theme/app subscribe --email=user@example.com
Output is JSON:
{
"success": true
}
Parameters are passed as --key=value flags:
wp bs rpc call my-theme/app load_more --offset=10 --limit=5
Cron
List all jobs
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 |
+-------------------+----------+----------+---------------------+
Run a job manually
wp bs cron run my-theme/app cleanup
This executes the callback immediately, regardless of the schedule. Useful for testing and debugging.
Settings
Show all settings
wp bs settings list
Get a specific setting
wp bs settings get tailwind/enabled
wp bs settings get assets/enqueue
Tailwind
Compile HTML to CSS
wp bs tailwind compile '<div class="flex items-center p-4">'
Compile from file
wp bs tailwind compile --file=template.html
Cache management
wp bs tailwind cache path # show cache directory
wp bs tailwind cache clear # clear compiled cache
SCSS
Compile SCSS to CSS
wp bs scss compile '$color: red; .test { color: $color; }'
Compile from file
wp bs scss compile --file=styles.scss
Custom Fields
List all registered custom fields
wp bs fields list
+-------+----------------+---------------------------+
| name | title | fields |
+-------+----------------+---------------------------+
| hero | Hero Section | heading, description, cta |
| card | Card | title, image, link |
+-------+----------------+---------------------------+
Assets
List all assets
wp bs assets list
Filter by type
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
All commands support --format=json for easy 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 projects allowlisted WordPress content to files and applies those files back to the database. It is explicit and CLI-driven; it does not sync on page load or admin initialization.
See Content Sync for configuration, file format, and guidance on when file-based database content is a good fit.
Pull database content to files
wp bs content pull
Limit the pull to one configured post type or taxonomy:
wp bs content pull --post-type=team_member
wp bs content pull --taxonomy=category
Preview without writing UIDs or files:
wp bs content pull --dry-run
Push files to the database
wp bs content push
Preview the apply plan without writing:
wp bs content push --dry-run
Prune content-set owned database posts and terms that no longer exist in files:
wp bs content push --prune --yes
With --prune, Blockstudio applies all file changes first, then removes content-set owned entities that no longer exist in the files. It refuses to run a destructive prune unless --yes is present.
Check status
wp bs content status
The table reports each file-backed entity as unchanged, would-update, missing-db, conflict, locked, or orphaned.
Static Prerendering
See Static Prerendering for the cache itself; these commands drive it.
Warm stale entries
wp bs prerender warm
Enqueues stale public URLs, then re-renders up to warm.concurrency jobs from
the durable warm queue and prints a JSON summary with queued, processed,
warmed, skipped, and failed counts. Content and site changes enqueue
replacement jobs automatically. Run the command again, or let the scheduled
warmer run, to work a larger queue down; a URL that fails to render stays
stale and is enqueued again on the next run. In graph mode the per-URL
warmer is off and the command enqueues nothing.
Report cache state
wp bs prerender status
Reports the active identity, files, bytes, graph records, queue state, the early-serve map report, and per-scope hit/miss/build/failure counters.
Purge the cache
wp bs prerender purge
Removes the current site’s prerendered documents. The next anonymous request or warm pass rebuilds them.
Check and prune the early-serve map
wp bs prerender map status
wp bs prerender map prune --dry-run
wp bs prerender map prune
map status reports the installation-wide early-serve map: its entries and
routes, route documents that are missing, orphaned entries whose site no
longer exists, and dead entries whose directory is gone. map prune removes
orphaned and dead entries and prints each removed entry with its reason;
--dry-run prints the same report without writing. A map owned by another
tool is never touched.
WPML
Generate the language configuration
wp bs wpml config
wp bs wpml config --file=wp-content/themes/my-theme/wpml-config.xml
Prints a wpml-config.xml that declares the text fields of every registered
block for translation and its files fields as attachment IDs, or writes it with
--file. In an existing file, only the section between the Blockstudio markers
is replaced. See WPML for what is declared and how to keep the file up to date.
Block Tag Migration
A standalone script rewrites prefix and alias shorthands to the canonical
<bs:namespace-slug> spelling. It does not load WordPress and does not write
unless --apply is explicitly supplied:
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
The prefix file maps caller-owned prefixes to ordered namespaces. The known
block file is a JSON list of registered block names. Exact aliases are
optional. The report includes deterministic mappings, before/after hashes,
unknown tags, ambiguous aliases, dynamic tags, and examples found in comments,
code fences, <pre>, or <code> ranges.
The scanner handles paired, nested, and self-closing markup, including literal
tags in PHP strings. It preserves attributes and changes only tag names.
Comments and code samples are report-only. Unrelated custom elements are
ignored. Applying a migration is blocked while unknown, ambiguous, or dynamic
cases remain unless the caller deliberately passes --allow-unresolved.
Running the command again over canonical output produces no changes.
See Migration for why the canonical spelling exists and what it resolves.
Teardown
wp bs teardown
Removes the cron events and static prerender state an installation owns: the
current site’s early-serve map entry, and the shared advanced-cache.php
drop-in and WP_CACHE declaration once the final owned entry is gone.
Installations without a plugin deactivation hook, such as Composer-bundled
setups, use this for a clean removal. Configuration files are left untouched.