PHPackages imagewize/pt-cli - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [CLI & Console](/categories/cli) 4. / 5. imagewize/pt-cli ActiveProject[CLI & Console](/categories/cli) imagewize/pt-cli ================ Pattern scaffolding and compliance checker for WordPress FSE block themes v2.4.2(2w ago)050↓50%MITPHPPHP >=8.1 Since May 8Pushed 2w agoCompare [ Source](https://github.com/imagewize/pt-cli)[ Packagist](https://packagist.org/packages/imagewize/pt-cli)[ RSS](/packages/imagewize-pt-cli/feed)WikiDiscussions main Synced 1w ago READMEChangelog (10)Dependencies (2)Versions (16)Used By (0) WordPress Pattern Toolkit ========================= [](#wordpress-pattern-toolkit) Scaffolding, compliance checking, and HTML template validation for WordPress FSE block themes. Generates block pattern PHP files, layout patterns, and style variations. Checks pattern `.php` files for structural and naming rule violations, and checks HTML template/part files for client-side block validation drift — no WordPress context required. Runs on the host machine as a standalone PHP CLI tool. Installation ------------ [](#installation) As a global tool: ``` composer global require imagewize/pt-cli ``` Or as a project dev dependency (recommended for theme development): ``` composer require --dev imagewize/pt-cli ``` Then use `./vendor/bin/pt-cli` or add a Composer script. Requires PHP 8.1+. Usage ----- [](#usage) ### Scaffolding Commands [](#scaffolding-commands) ``` # List available templates, snippets, categories, and style variations pt-cli list # Scaffold a new pattern from a template pt-cli pattern:create --title="My Hero" --slug=my-hero --template=hero-cover --category=elayne/hero # Scaffold a layout pattern pt-cli layout:create --title="Landing Page" --slug=landing --layout=landing-page --category=elayne/pages # Scaffold a theme style variation pt-cli style:create --name="Ocean Legal" --vertical=legal # Full interactive mode (no options = prompts) pt-cli pattern:create ``` ### Compliance Checking [](#compliance-checking) ``` # Check all patterns in a directory pt-cli check /path/to/patterns # Check with a specific theme config pt-cli check /path/to/patterns --theme=elayne # Check a single file pt-cli check /path/to/patterns/header-default.php --theme=elayne # Apply mechanical autofixes pt-cli check /path/to/patterns --theme=elayne --autofix ``` ### HTML Template Compliance [](#html-template-compliance) ``` # Check all .html files in a templates or parts directory pt-cli check:templates /path/to/templates/ --theme=elayne pt-cli check:templates /path/to/parts/ --theme=elayne # Check a single template file pt-cli check:templates /path/to/templates/archive-product.html --theme=elayne # Apply mechanical autofixes (taxQuery:{} → [] and template-part theme attribute) pt-cli check:templates /path/to/templates/ --theme=elayne --autofix ``` ### Pattern Diff & Sync [](#pattern-diff--sync) Compare a Gutenberg clipboard paste against an existing PHP pattern file, or apply the changes back while preserving all PHP translation wrappers. ``` # Report differences only (shows missing translations, editor attrs, CSS issues) pbpaste | pt-cli pattern:diff patterns/woo-signature-pieces.php --from-stdin # Include fix suggestions in the diff report pbpaste | pt-cli pattern:diff patterns/woo-signature-pieces.php --from-stdin --show-suggestions # Output diff results as JSON (for tooling integration) pbpaste | pt-cli pattern:diff patterns/woo-signature-pieces.php --from-stdin --json # Preview the merged result without touching the file pbpaste | pt-cli pattern:diff patterns/woo-signature-pieces.php --from-stdin --apply --dry-run # Apply clipboard changes to the PHP file (preserves esc_html_e, esc_attr_e, etc.) pbpaste | pt-cli pattern:diff patterns/woo-signature-pieces.php --from-stdin --apply # Lower the similarity threshold for loosely matched blocks (default: 0.95) pbpaste | pt-cli pattern:diff patterns/woo-signature-pieces.php --from-stdin --similarity-threshold=0.80 ``` **What `--apply` does:** 1. Strips editor-only attributes (`__privatePreviewState`) from block JSON. 2. Fixes bare font-size slug values (`font-size:small`) → CSS variable (`font-size:var(--wp--preset--font-size--small)`). 3. Removes nested `` copy artefacts introduced by the Gutenberg clipboard. 4. Re-maps every text node back to its original PHP wrapper (`esc_html_e`, `esc_attr_e`, `wp_kses_post`) from the existing file. 5. Generates a new `esc_html_e()` wrapper for any text that is new in the clipboard. 6. Preserves the PHP docblock header unchanged. The file is only written when `--apply` is used **without** `--dry-run`. Commands Reference ------------------ [](#commands-reference) CommandDescription`list` (default)List available templates, snippets, categories, and style variations`pattern:create`Scaffold a new Elayne block pattern from a template`layout:create`Scaffold a new Elayne block layout pattern`style:create`Scaffold a WordPress theme style variation JSON`check`Check PHP pattern files for compliance violations`check:templates`Check HTML template/part files for block validation drift`pattern:diff`Diff Gutenberg clipboard against a pattern file, or apply changes preserving PHPWorkflow -------- [](#workflow) `pt-cli` is an all-in-one tool for WordPress FSE block theme development: ### Scaffolding Workflow [](#scaffolding-workflow) StepToolPurposeWhere1`pt-cli pattern:create` or `pt-cli layout:create`Generate pattern/layout scaffoldingHost2Build in WP editorCreate pattern contentVM3Copy blocksCopy all blocks from editorVM4`pt-cli pattern:create --shell-only`Create PHP file with paste markerHost5Replace markerPaste blocks into pattern fileHost### Pattern Sync Workflow (updating existing patterns) [](#pattern-sync-workflow-updating-existing-patterns) When an existing PHP pattern needs updating from the Site Editor, use `pattern:diff --apply`instead of pasting manually — it keeps all `esc_html_e()` and other PHP wrappers intact. StepCommandPurpose1Edit pattern in Site EditorMake structural/layout changes2Copy all blocks (Cmd+A, Cmd+C)Copy updated block HTML to clipboard3`pbpaste | pt-cli pattern:diff --from-stdin --apply --dry-run`Preview merged result4`pbpaste | pt-cli pattern:diff --from-stdin --apply`Write merged result to file5`pt-cli check --theme=elayne`Verify compliance passes### Compliance Workflow (three-pass) [](#compliance-workflow-three-pass) PassToolPurposeWhere1`wp pattern validate --fix`Structural validation (WordPress parser — unbalanced delimiters, malformed JSON, bad nesting)VM2`pt-cli check --theme=elayne`PHP pattern compliance (hardcoded values, naming rules, WooCommerce block structure)Host3`pt-cli check:templates --theme=elayne`HTML template compliance (WooCommerce save() drift, taxQuery, template-part theme attribute)HostPass 1 requires WordPress (database connection) and runs in the Trellis VM. Passes 2 and 3 are standalone and run on the host machine. Templates --------- [](#templates) **23 pre-built pattern templates** covering common use cases: TemplateDescription`blank`Empty pattern with header only`hero-cover`Full-bleed wp:cover with bottom-center content`cta-fullwidth`Full-width call-to-action band`feature-grid-3col`Full-width section with 3 feature cards`stats-bar-fullwidth`Dark full-width stats/numbers bar`two-column-text-image`Text left, image right two-column layout`header-standard`Standard header — logo, navigation, social links`footer-standard`Standard footer — brand blurb, nav columns, subnav`testimonials-grid`Responsive testimonial card grid with reviewer info`pricing-comparison`Three-tier pricing table with elevated recommended card`blog-post-columns`wp:query-driven 3-column post grid (portrait images)`team-grid`Team member profile grid — photo, name, title, bio**WooCommerce templates:** TemplateDescription`woo-hero`Two-column hero: text + CTA left, decorative cover right`woo-ticker`Server-rendered marquee ticker bar (needs render\_block filter)`woo-shop-categories`CSS bento grid: one large featured card + four smaller cards`woo-featured-products`Section header with View All + product-collection 4-col grid`woo-our-story`Two-column brand story: monogram watermark left, text + stats right`woo-testimonials`Three-column testimonial cards with star ratings and avatar circles`woo-newsletter`Full-bleed newsletter signup with decorative eyebrow`woo-shop-landing`Store homepage shell that composes sub-patterns in sequence`woo-cart`Full-width cart page wrapper (Inserter: false)`woo-checkout`Full-width checkout page wrapper (Inserter: false)`woo-filters-sidebar`Sticky sidebar: price slider + colour-chip attribute + two checkbox-list attributes`woo-product-grid`Filter-aware product-collection grid with sort toolbar + paginationLayouts ------- [](#layouts) **8 layout skeletons** for rapid page construction: LayoutDescription`full-width`Single column, constrained — simplest starting point`two-column`50/50 columns block`three-column`Grid with 3 equal groups`sidebar-left`Narrow left sidebar (33%) + wide content area (66%)`sidebar-right`Wide content area (66%) + narrow right sidebar (33%)`hero-image-left`Cover image left + heading, text, CTA right`hero-image-right`Heading, text, CTA left + cover image right`landing-page`Hero + 3-column features + CTA — no header/footer wrapperStyle Variations ---------------- [](#style-variations) **5 preset color palettes** for common business verticals: VerticalColor Scheme`custom`Enter your own hex color values`legal`Navy blue + gold`plumbing`Dark blue + orange`spa`Sage green + sand`food-beverage`Burgundy + goldSnippets -------- [](#snippets) **13 reusable code snippets** for common pattern components: SnippetDescription`eyebrow-heading-body.txt`Eyebrow label + heading + body paragraph`3col-grid-wrapper.txt`Responsive 3-column grid wrapper`stat-item.txt`Number + label stat card (dark background)`testimonial-card.txt`Testimonial with stars, quote, author`two-button-group.txt`Primary + outline button pair`overlay-grid-cover-card.txt`Portrait cover image card + floating badge (use wp:cover, NOT wp:image)`valid-cover.txt`wp:cover with all required attrs: dimRatio, backgroundColor/customGradient, minHeight (root integer) + minHeightUnit`valid-columns-wp66.txt`wp:columns without inline gap/margin; isStackedOnMobile:false → is-not-stacked-on-mobile class`responsive-grid-min-width.txt`wp:group grid layout with minimumColumnWidth — preferred over wp:columns for 3+ columns`valid-button-attr-order.txt`wp:button with className/colors before style; font size via style.typography.fontSize`valid-fullwidth-section.txt`alignfull outer group + margin reset (top/bottom:"0" no units) + constrained inner group`valid-heading-with-preset.txt`wp:heading with fontSize slug in JSON and matching has-{slug}-font-size utility class in HTMLConfiguration ------------- [](#configuration) Built-in configs ship with the tool: - `base` — default rules for any FSE theme - `elayne` — Elayne-specific rules (extends base) ### Project-level override [](#project-level-override) Create `.pt-cli/{theme}.json` in your project root to override or extend the built-in config without needing a `pt-cli` release: ``` my-project/ ├── .pt-cli/ │ └── elayne.json └── web/app/themes/elayne/ └── patterns/ ``` Config lookup order: 1. `.pt-cli/{theme}.json` (project directory) 2. `config/{theme}.json` (tool directory) 3. `config/base.json` (fallback) Rules ----- [](#rules) ### Base rules (all FSE themes) [](#base-rules-all-fse-themes) RuleAutofixableSeverityNo hardcoded font sizes (CSS px/rem/em)NoErrorNo spacer blocksNoErrorMargin reset on alignfull patternsNoErrorBalanced HTML tags (``, ``, ``, ``, ``, etc.)NoErrorResponsive grid for 3+ columns (warn on `wp:columns`)NoWarningNo hardcoded media IDsNoErrorTranslated strings (HTML tags + alt attributes)NoErrorProper `patternName` in outermost block metadataNoErrorNo HTML comments between opening tags and block commentsNoErrorNo custom domain emails (use `example@example.com`)NoErrorNo hardcoded external URLs in `src` attributesNoError`wp:button` root `fontSize` must use `style.typography`NoError`wp:button` `className` must come before `style` in JSONNoErrorCover block `minHeight` must have root-level unitsNoErrorNo empty border side objects `{}` in block JSONNoError`wp:buttons` must have `` wrapperNoErrorNo `overflow:hidden` as inline style on group blocksNoErrorNo `opacity` as inline style on HTML elementsNoErrorFont preset classes match root-level `fontSize`/`fontFamily`NoErrorNo stale inline `blockGap`/`gap`/`margin` on group/column wrappersNoError### Elayne-specific rules (`--theme=elayne`) [](#elayne-specific-rules---themeelayne) RuleAutofixableSeverity`wp:template-part` must have `"theme":"elayne"` attributeNoError`patternName` prefix must start with `elayne/`NoErrorNo emoji iconsNoWarning`woocommerce/product-title` inside `product-template` must use `post-title` + `__woocommerceNamespace`NoErrorWC native blocks must not have `__woocommerceNamespace`NoError`woocommerce/product-collection` must have `query` metadataNoError`woocommerce/product-collection` must have `` wrapperNoError`woocommerce/product-collection` must not have both `layout` and `displayLayout`NoError### Autofixable rules (`--autofix`) [](#autofixable-rules---autofix) RuleStrip inline `gap:` from groups/columnsStrip inline `margin:` from flex groups/columnsReorder button JSON keys (`className` before `style`)Migrate button root `fontSize` to `style.typography`Inject `has-{slug}-font-size` class on heading/paragraph### Exceptions [](#exceptions) - Templates (`template-*`, `header-*`, `footer-*`) allow: `border-radius:5px`, `border-radius:100px`, `blockGap:0.5rem`, `blockGap:10px` - WooCommerce plugin patterns (`wp-content/plugins/woocommerce/patterns/*`) are exempt from all checks ### Template rules (`check:templates`) [](#template-rules-checktemplates) Applied to `.html` files in `templates/` and `parts/` directories. These checks catch client-side JavaScript `save()` mismatches that the PHP compliance checker and WP-CLI structural validator cannot detect. RuleAutofixableSeverity`taxQuery:{}` must be `taxQuery:[]` (object → array)YesErrorWooCommerce filter sub-blocks must have an HTML `` wrapperNoError`woocommerce/product-filters` `` must include WooCommerce CSS custom propertiesNoError`wp:template-part` must declare `"theme":""`YesWarningBalanced HTML tags (``, ``, ``, ``, etc.)NoError**Why separate from `check`?** The `check` command processes PHP pattern files. HTML template files use a different structure — raw block markup without PHP wrappers — and require different checks. In particular, WooCommerce 9.x+ changed the `save()` output for filter blocks to include empty `` wrappers; templates written against older versions lack those wrappers and trigger client-side block validation errors that neither WP-CLI nor the PHP checker can catch. Demo Rebuild Script ------------------- [](#demo-rebuild-script) For rebuilding demo pages from pattern PHP files, see the [Demo Rebuild Script guide](docs/demo-rebuild-script.md). Development ----------- [](#development) ``` git clone https://github.com/imagewize/pt-cli cd pt-cli composer install bin/pt-cli list bin/pt-cli check --help ``` License ------- [](#license) MIT — see [LICENSE](LICENSE). ### Health Score 44 — FairBetter than 90% of packages Maintenance97 Actively maintained with recent releases Popularity12 Limited adoption so far Community6 Small or concentrated contributor base Maturity50 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~1 days Total 12 Last Release 14d ago Major Versions v1.0.0 → v2.0.02026-05-08 ### Community Maintainers ![](https://www.gravatar.com/avatar/01563ca58ee6cd8347183741d139584749756ca5e02cd062915ca0b5edcc8057?d=identicon)[jasperf](/maintainers/jasperf) --- Top Contributors [![jasperf](https://avatars.githubusercontent.com/u/344138?v=4)](https://github.com/jasperf "jasperf (50 commits)") --- Tags cligutenberg-blockswordpress-patterns ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/imagewize-pt-cli/health.svg) ``` [![Health](https://phpackages.com/badges/imagewize-pt-cli/health.svg)](https://phpackages.com/packages/imagewize-pt-cli) ``` ### Alternatives [illuminate/console The Illuminate Console package. 13045.3M6.1k](/packages/illuminate-console) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)