Skip to content

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

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

Filter to components only

Shell
wp bs blocks list --components

Output as JSON

Shell
wp bs blocks list --format=json

Validate stored fields

Shell
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

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

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.

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

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:

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

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

Shell
wp bs pages sync --authoritative --full

For deployment scripts that need the complete report:

Shell
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

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 operations

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

For single-schema blocks, the schema name defaults to default:

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

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

For single-schema blocks:

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

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

RPC

List all functions

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

Call a function

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

Output is JSON:

JSON
{
  "success": true
}

Parameters are passed as --key=value flags:

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

Cron

List all jobs

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

Run a job manually

Shell
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

Shell
wp bs settings list

Get a specific setting

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

Tailwind

Compile HTML to CSS

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

Compile from file

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

Cache management

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

SCSS

Compile SCSS to CSS

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

Compile from file

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

Custom Fields

List all registered custom fields

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

Assets

List all assets

Shell
wp bs assets list

Filter by 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

All commands support --format=json for easy 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 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

Shell
wp bs content pull

Limit the pull to one configured post type or taxonomy:

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

Preview without writing UIDs or files:

Shell
wp bs content pull --dry-run

Push files to the database

Shell
wp bs content push

Preview the apply plan without writing:

Shell
wp bs content push --dry-run

Prune content-set owned database posts and terms that no longer exist in files:

Shell
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

Shell
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

Shell
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

Shell
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

Shell
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

Shell
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

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

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

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

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