ralfhortt / wp-cli-scaffold

dev-main 2026-10-27 11:56 UTC

Requires

• php: >=8.2
• ralfhortt/wp-cli-shared: dev-main@dev
• wp-cli/wp-cli: ^2.12

Requires (Dev)

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

GPL-2.0-or-later

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

README

WP-CLI scaffold commands for blocks, block patterns, block theme templates, style variations, and theme.json updates.

Installation

Published package:

wp package install ralfhortt/wp-cli-scaffold

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

Local development checkout:

wp package install /absolute/path/to/wp-cli-scaffold

Update after local edits:

wp package remove ralfhortt/wp-cli-scaffold
wp package install /absolute/path/to/wp-cli-scaffold

Commands

Command	Description
wp scaffold create-block [slug]	Scaffold a block via @wordpress/create-block@4 (theme or plugin)
wp scaffold pattern	Create {active-theme}/patterns/{slug}.php
wp scaffold starter-content	Create a starter content pattern
wp scaffold query-loop	Create a query loop pattern
wp scaffold template [slug]	Create {active-theme}/templates/{slug}.html
wp scaffold template-part [slug]	Create {active-theme}/parts/{slug}.html
wp scaffold style-variation [slug]	Create {active-theme}/styles/{slug}.json
wp scaffold theme-json-section	Merge a payload into a theme.json section

All commands require --path=/path/to/wordpress.

wp scaffold create-block requirements

create-block shells out to Node via npx @wordpress/create-block@4. Install Node.js (see the create-block package for the current minimum version) and ensure npx is on your PATH.

Override the command (for example in CI or when using a fixed global install):

export CREATE_BLOCK_COMMAND="npx @wordpress/create-block@4.1.0"

With --force, the package removes the existing scaffold target directory (for example blocks/{slug} in a theme) before running create-block. @wordpress/create-block does not provide its own --force flag.

wp scaffold theme-json-section merge behavior

Merging uses dot notation (for example settings.color.palette):

• Objects — keys are merged recursively; incoming values replace or extend existing keys.
• Lists — items are appended to the end of the existing list.
• Slug lists — when every item is an object with a slug string (palette entries, font sizes, and similar), items with the same slug are merged recursively and new slugs are appended.

Use --dry-run to print the merged JSON without writing theme.json.

Examples

wp scaffold create-block todo-list --destination=theme --title="Todo List" --path=/path/to/wordpress
wp scaffold pattern --title="Hero Banner" --categories=banner --path=/path/to/wordpress
wp scaffold query-loop --title="Latest Posts" --post-type=post --path=/path/to/wordpress
wp scaffold template single --path=/path/to/wordpress
wp scaffold template-part header --area=header --path=/path/to/wordpress
wp scaffold style-variation ocean --title="Ocean" --primary="#0a5cff" --background="#f4f8ff" --text="#0f172a" --path=/path/to/wordpress
wp scaffold theme-json-section --section=settings.color.palette --json='[{"slug":"brand","name":"Brand","color":"#0a5cff"}]' --path=/path/to/wordpress

Flags

• --theme=<slug> — target a specific theme
• --destination=theme|plugin — for create-block
• --plugin=<slug> — add block to existing plugin
• --area=header|footer|sidebar|uncategorized — for template-part
• --dry-run — print theme.json merge result without writing
• --force — overwrite existing files; for create-block, deletes the target scaffold directory first

Development

composer stan
composer lint
composer test