WP-CLI Create Block Theme

Adds the Create Block Theme plugin's Save Changes to Theme action to WP-CLI. Temporary workaround while WordPress/create-block-theme#830 is in progress. Requires the Create Block Theme plugin and an active block theme.

wp create-block-theme save [flags]

All flags accept true or false.

Without flags, the command uses the same defaults as the Site Editor interface:

wp create-block-theme save

Override any option explicitly:

wp create-block-theme save --save-fonts=false --localize-images=true

--localize-text, --localize-images, and --remove-navigation-refs apply only to saved templates and patterns; with both --save-template-changes=false and --save-patterns=false they have no effect.

See cbt-block-pattern-issue-rca.md for the full root-cause analysis of the block pattern reference problem and design decisions behind these workarounds.

A synced pattern is stored as a wp_block post. Its callers save a core/block reference such as <!-- wp:block {"ref":36949} /-->, where 36949 is that database post ID. Create Block Theme exports each wp_block to patterns/*.php and then deletes the database post so WordPress loads the theme pattern instead. Its built-in reference replacement only handles templates and template parts; ordinary pages and custom post types can retain the old ID. Their reference then points to a deleted post, so the editor and frontend render a missing block.

This wrapper records each ID and exported slug before saving, then changes all current database callers to wp:pattern slug references after export.

To keep synced patterns in the database—and avoid creating pattern-ID references that need migration in the first place—by disabling pattern export which is ran by default:

wp create-block-theme save --save-patterns=false

When synced patterns are saved into patterns/*.php with this plugin, it also changes database references from wp:block IDs to the exported theme pattern slugs. If saving is interrupted after patterns are moved, rerun the retained repair step:

wp create-block-theme fix-pattern-references

Broken Block Pattern references and affected database contents can be diagnosed with wp create-block-theme pattern-refs check:

$ wp create-block-theme pattern-refs check
AFFECTED_REFS
POST_ID  POST_TYPE         POST_STATUS  POST_TITLE        POST_NAME            MISSING_REF
126      wp_template       publish      All archives      archive              405
129      wp_template_part  publish      Header            header               33206
33197    wp_template_part  publish      Studio header     studio-header        33206
34228    page              draft        Template Parts                         34241
34267    wp_template       publish      Archive: demotax  taxonomy-demotax     405

AFFECTED_URLS
MISSING_REF  CALLER_ID  AFFECTED_URL
405          34267      https://example.test/demo-post-type/test-slug-1/
405          34267      https://example.test/demo-post-type/test-slug-2/
405          34267      https://example.test/demo-post-type/test-slug-3/
405          34267      https://example.test/demo-post-type/test-slug-4/
405          34267      https://example.test/demo-post-type/test-slug-5/
405          34267      https://example.test/demo-post-type/test-slug-0/
...
Warning: 5 broken pattern reference(s) found; 17 affected URL(s) found.

For older broken references, provide the verified ID-to-slug map explicitly:

wp create-block-theme fix-pattern-references --map='{"36949":"my-theme/my-pattern"}'

Restore a missing wp_block from a pre-save dump:

wp create-block-theme pattern-refs restore 36949 /backups/260722_pre_save.sql

Back up the production database outside the web root, then audit without changing data:

mkdir -p "$HOME/backups"
backup="$HOME/backups/$(date +%y%m%d-%H%M)_pre-pattern-refs.sql"
wp db export "$backup"
wp create-block-theme pattern-refs check

check exits with status 1 when it finds broken references; save its output. For each missing ID, restore the original synced pattern into DB from a dump taken before it was deleted:

wp create-block-theme pattern-refs restore REF_ID "$backup"

The command reads only that ID's wp_posts row from the dump, inserts it in a transaction only if it is a wp_block, then flushes WordPress caches. It does not restore revisions, metadata, or pattern categories.

Alternatively, only after confirming that the exported theme pattern exists and its content matches the missing pattern, migrate callers to it:

wp create-block-theme fix-pattern-references --map='{"REF_ID":"my-theme/pattern-slug"}'

Do not guess slugs or run save again during recovery. Re-run the audit and purge production page/CDN caches after repairing references.