wp-theme-control

wp-theme-control bakes Site Editor changes from the WordPress database into the active block theme without requiring the Create Block Theme plugin. The implementation is Bash-first and assumes WP-CLI 3.0 or newer. It uses short wp eval expressions where WordPress core APIs are needed, but none of the project scripts are PHP.

Warning

This project is experimental. Use it on local or development sites, start with plan or --dry-run, and inspect the generated files, manifests, and backups before cleaning database records. It is not yet recommended for unattended production workflows.

The initial skill covers the high-value local-development workflow:

• activated Font Library fonts → assets/fonts/* and theme.json
• custom templates and template parts → templates/*.html and parts/*.html, plus hidden runtime patterns when needed
• user Global Styles → a merged theme.json
• unsynced user-created patterns → patterns/*.php
• verified cleanup of only the database records successfully written to files

Synced patterns, distributable-theme packaging, and localization are deliberately out of scope.

Requirements

• Bash 3.2+
• WP-CLI 3.0+
• jq
• a writable active block theme
• the WP-CLI block command group, including wp block template export

Quick start

Run the repository wrapper from any directory:

/path/to/wp-theme-control/bin/wp-theme-control plan --path=/path/to/wordpress
/path/to/wp-theme-control/bin/wp-theme-control all --path=/path/to/wordpress

Each write command prints the location of a TSV manifest and keeps backups in the same run directory. By default, runs are stored under .wp-theme-control/runs in the current directory. Choose another persistent location with --state-dir=/path.

To export and then immediately remove the corresponding database customizations:

bin/wp-theme-control all --clean --path=/path/to/wordpress

For a review-first workflow, omit --clean, inspect the theme diff, then clean the applicable manifests:

bin/wp-theme-control clean /path/to/manifest.tsv --path=/path/to/wordpress

When reviewing an all run, cleaning the styles manifest also clears the Global Styles font bookkeeping. The fonts manifest remains the audit and backup record; clean it directly only when fonts was run by itself.

Cleanup is intentionally strict. It refuses to delete a record when the exported file no longer matches the manifest hash, the database post type is unexpected, or an exported pattern is no longer marked unsynced. --force bypasses the file-hash check, not the record-type checks.

Runtime URLs

Local absolute URLs in exported templates, template parts, and patterns are made portable automatically. The Bash workflow passes staged block markup to one wp eval transformer, which replaces:

• any absolute URL whose path points inside the active theme with get_stylesheet_directory_uri() at runtime, regardless of its saved host
• the current uploads base with wp_get_upload_dir()["baseurl"] at runtime
• the current site base with home_url() at runtime

Theme assets are matched first, then uploads, then the general site URL. Path-based theme matching covers local tools such as Studio when the database home_url() still contains an imported staging domain but editor content contains a localhost theme URL. Rewrites include URLs in src, srcset, block attributes, and background data. The Media Library remains the source of uploaded files: no attachments are copied, moved, or deleted, and numeric attachment IDs are left unchanged. External and already-relative URLs are left alone.

Because WordPress does not execute PHP in template .html files, a template or part that needs runtime URLs is reduced to a wp:pattern reference. Its transformed block content is stored in a generated patterns/wp-theme-control-*.php file with Inserter: no, following the same patternization mechanism used by Create Block Theme. User-created patterns are exported directly as PHP pattern files, so they receive the runtime expressions without another wrapper.

After writing pattern files, the workflow clears WordPress's theme pattern file cache so generated and exported patterns are discoverable on the next request.

theme.json cannot execute PHP. plan warns about local absolute URLs there, and write commands stop before installing a theme.json that would retain one. Move that environment-specific media or link into block markup before baking it.

Commands

wp-theme-control plan       Read-only inventory and collision report
wp-theme-control fonts      Persist activated Font Library fonts
wp-theme-control templates  Export custom templates and template parts
wp-theme-control styles     Merge user Global Styles into theme.json
wp-theme-control patterns   Export unsynced user-created patterns
wp-theme-control clean      Clean records listed in one manifest
wp-theme-control all        Run fonts, templates, styles, and patterns

The fonts command follows Create Block Theme's ordering and data model. Database fontFamilies.theme values are treated as an activation list, so empty fontFace arrays never overwrite full theme definitions. Activated fontFamilies.custom files are copied into assets/fonts/<slug>/, their sources are rewritten to file:./assets/fonts/..., and same-slug custom definitions replace theme definitions. Deactivated definitions are removed from theme.json, but their now-unused asset files are retained for recoverability.

The styles command invokes font persistence first when run directly and excludes font-origin bookkeeping from its Global Styles merge. all runs fonts → templates → styles → patterns. Runtime URL expressions are injected only after database block content has been checked for PHP syntax.

Supported common options are --path=, --url=, --user=, --state-dir=, --dry-run, --clean, and --force where applicable. Remote --ssh targets are intentionally unsupported because theme files are written directly to the local filesystem.

Agent skill

The Codex-compatible skill lives at skills/wp-theme-control. Its bundled scripts are the source of truth; bin/wp-theme-control is a convenience wrapper.