ralfhortt / wp-cli-theme-sync

dev-main 2026-10-27 12:21 UTC

Requires

• php: >=8.2
• ralfhortt/wp-cli-shared: dev-main@dev
• sebastian/diff: ^5.1
• wp-cli/wp-cli: ^2.10

Requires (Dev)

• pestphp/pest: ^2.36
• phpstan/phpstan: ^2.2

GPL-2.0-or-later

Published on Packagist.org on 2026-11-13 07:47 UTC

README

WP-CLI commands to detect drift between block theme data stored in WordPress and local theme files.

Installation

Published package:

wp package install ralfhortt/wp-cli-theme-sync

ralfhortt/wp-cli-shared is installed automatically as a Composer dependency.

Local development checkout:

wp package install /absolute/path/to/wp-cli-theme-sync

Commands

Command	Description
wp theme-sync status	Show out-of-sync templates, template parts, and styles
wp theme-sync diff	Alias of wp theme-sync status (lists drift, not unified diffs)
wp theme-sync show <slug>	Show a unified diff for a single item
wp theme-sync export	Export templates, parts, and styles from DB into theme files
wp theme-sync export-templates	Export customized templates from DB into templates/*.html
wp theme-sync export-parts	Export customized template parts from DB into parts/*.html
wp theme-sync export-styles	Export merged styles into theme.json and existing styles/*.json

Drift states

• missing_local - DB item exists but corresponding local file is missing
• content_differs - normalized DB and file content differ
• unmapped_style_change - DB variation change has no corresponding local file (listed by default; only fails exit code with --strict-styles)

Flags

• --theme=<slug> target a specific theme
• --all include in-sync rows
• --type=<type> filter or target template, template_part, or styles
• --slug=<slug> filter status output by slug
• --state=<state> filter status output by drift state
• --area=<area> disambiguate template parts with the same slug
• --strict-styles treat unmapped style variation changes as drift failures (exit code 1 on status / diff; errors on export-styles)
• --verbose include checksum hints in status details
• --format=table|json|yaml|csv for status/export output
• --format=diff|raw-db|raw-file for show output
• --context=<lines> context lines for unified diff output (default: 3)
• --dry-run preview writes without changing files
• --force overwrite changed existing files during export

Exit codes

• 0 when everything is in sync (or when show reports an in-sync item)
• 1 when drift exists (or when show reports drift). Unmapped style variations alone exit 0 unless --strict-styles is set.

Notes

• Comparison is driven by customized templates/parts in the database (Site Editor), not every file on disk.
• --theme scopes templates, parts, global styles, and export paths to that theme (including wp_global_styles for that stylesheet).
• export / export-styles write merged theme + user global styles into theme.json (what the site shows), not theme-only defaults.

Examples

wp theme-sync status --path=/path/to/wordpress
wp theme-sync status --type=template --state=content_differs --path=/path/to/wordpress
wp theme-sync diff --format=json --strict-styles --path=/path/to/wordpress

wp theme-sync show single --type=template --path=/path/to/wordpress
wp theme-sync show header --type=template_part --area=header --path=/path/to/wordpress
wp theme-sync show theme.json --type=styles --path=/path/to/wordpress
wp theme-sync show ocean --type=styles --format=raw-db --path=/path/to/wordpress

wp theme-sync export --dry-run --path=/path/to/wordpress
wp theme-sync export --force --path=/path/to/wordpress
wp theme-sync export-styles --force --strict-styles --path=/path/to/wordpress

Development

composer stan
composer lint
composer test