wp-lemon CLI

A powerful command-line tool designed to streamline the setup and management of WordPress sites built with the wp-lemon WordPress theme by Studio Lemon. This CLI helps you scaffold new sites, create and manage blocks, and simplify your WordPress development workflow.

Developed by Studio Lemon for developers working with the wp-lemon stack.

📋 Table of Contents

• Features
• Requirements
• Commands
  • Site Commands
  • Block Commands
  • Blocks Commands
  • Help & Version
• Contributing
• License
• Support

✨ Features

• 🚀 Quick Site Setup - Scaffold a new wp-lemon WordPress site in minutes
• 🧩 Block Management - Create, reuse, and update WordPress blocks effortlessly
• 🔄 Site Ejection - Convert a wp-lemon site to a standard WordPress installation
• 🎨 Interactive CLI - User-friendly prompts guide you through setup processes

Use with npx:

npx wp-lemon <command>

Install from source:

git clone [email protected]:Studio-Lemon/wp-lemon-create.git
cd wp-lemon-create
npm install
npm link

🔧 Requirements

• Node.js v16.0.0 or higher
• npm (comes with Node.js)
• PHP (8.2 or higher)
• Composer (for PHP dependency management)
• wp CLI (for WordPress command line management)
• wp dotenv package (for managing environment variables)

Check your Node.js version:

node --version

📚 Commands

Site Commands

wp-lemon site create

Creates a new wp-lemon WordPress site with scaffolded theme structure and dependencies.

Usage:

npx wp-lemon site create

What it does:

• Initializes a new WordPress project
• Sets up the wp-lemon theme structure
• Installs required PHP dependencies via Composer
• Configures block directories
• Creates initial configuration files

Interactive prompts:

• Project name
• Project slug (auto-generated from name)
• Theme configuration options

Example:

$ npx wp-lemon site create
# Follow the prompts to configure your new site

wp-lemon site update

Updates an existing wp-lemon site with the latest theme files and dependencies.

Usage:

npx wp-lemon site update

Note: This feature is currently in development. Check back soon for updates!

wp-lemon site eject

Converts a wp-lemon managed site to a standard WordPress installation, removing wp-lemon specific tooling and configurations.

Usage:

npx wp-lemon site eject

What it does:

• Removes wp-lemon CLI dependencies
• Converts wp-lemon specific configurations to standard WordPress configs
• Maintains all your content and customizations
• Generates a backup of your configuration

⚠️ Warning: This action is irreversible. Make sure you have a backup before ejecting!

Block Commands

wp-lemon block create

Scaffolds a new WordPress block in the current site with all necessary files and configuration.

Usage:

npx wp-lemon block create

What it does:

• Creates a new block directory with proper structure
• Generates PHP block files (PHP registration and rendering)
• Creates JavaScript/TypeScript component files
• Sets up block metadata (block.json)
• Configures block styles and editor styles
• Registers the block with WordPress

Interactive prompts:

• Block name (e.g., "Hero Section")
• Block slug (auto-generated, can be customized)
• Block category (common, formatting, layout, widgets, embed)
• Additional block options (supports, alignments, etc.)

Generated files:

blocks/
├── block-slug/
│   ├── block.json
│   ├── block-slug.php
│   ├── block-slug.twig
│   ├── acf-block-slug.css
│   └── index.json

Example:

$ npx wp-lemon block create
# Follow the prompts to configure your new block

wp-lemon block reuse

Reuses a block from a different wp-lemon site by copying it into the current site.

Usage:

npx  wp-lemon block reuse

What it does:

• Allows you to copy/paste a path to a block from another wp-lemon site
• Copies block files to your current site
• Registers the block with your site configuration
• Able to rename the block if needed

Interactive prompts:

• Input path to source block
• Confirm block configuration for new site

Example:

$ npx wp-lemon block reuse
# Select a block from another project to copy into this one

Blocks Commands

wp-lemon blocks create-excel

Copies an Excel template file to your current directory to help you get started with bulk block creation.

Usage:

npx wp-lemon blocks create-excel

What it does:

• Copies blocks-example.xlsx template to your current directory
• Provides a pre-formatted Excel file with all required columns
• Displays instructions for next steps

Workflow:

1. Run the command to get the template
2. Edit the Excel file with your block data
3. Export it as CSV (e.g., blocks-example.csv)
4. Run wp-lemon blocks create ./blocks-example.csv

Excel/CSV Columns:

• name - Block title (e.g., "Hero Banner")
• slug - Block slug (e.g., "hero-banner")
• description - Block description
• category - Block category (layout, content, design, etc.)
• icon - Dashicon name without prefix
• keywords - Pipe-separated keywords (e.g., "hero|banner|header")
• posttypes - Comma-separated post types (leave empty for all)
• alignment - Full alignment support (true/false or y/n)

Example:

$ npx wp-lemon blocks create-excel
✔️  Successfully copied blocks-example.xlsx to current directory

You can now:
  1. Edit blocks-example.xlsx with your block data
  2. Export it as CSV (blocks-example.csv)
  3. Run: wp-lemon blocks create ./blocks-example.csv

wp-lemon blocks create <csvFile>

Creates multiple blocks in bulk from a CSV file, dramatically speeding up the process of scaffolding many blocks at once.

Usage:

npx wp-lemon blocks create ./path/to/blocks.csv

What it does:

• Reads block definitions from a CSV file
• Validates all entries before creating any blocks
• Creates all blocks in batch with proper error handling
• Skips blocks that already exist
• Provides a detailed summary of successes and failures

CSV Format:

The CSV file must include these columns (header row required):

• name (required) - Block title
• slug (required) - Block slug (will be sanitized)
• icon (required) - Dashicon name
• description (optional) - Block description
• category (optional) - Block category
• keywords (optional) - Pipe-separated keywords
• posttypes (optional) - Comma-separated post types
• alignment (optional) - Full alignment support (true/false or y/n)

Validation:

• Checks for required fields (name, slug, icon)
• Detects duplicate slugs in CSV
• Verifies blocks don't already exist
• Validates CSV format and structure
• All validation happens before any blocks are created

Error Handling:

• Skips blocks that fail to create
• Continues processing remaining blocks
• Reports all successes and failures at the end
• Exits with error code if any blocks failed

Example CSV:

name,slug,description,category,icon,keywords,posttypes,alignment
Hero Banner,hero-banner,A full-width hero banner,layout,welcome-view-site,hero|banner|header,,true
Testimonial,testimonial,Display customer testimonials,content,format-quote,testimonial|quote|review,post,false
Call to Action,cta-button,A prominent CTA button,design,button,cta|button|action,,false

Example Usage:

$ npx wp-lemon blocks create ./my-blocks.csv

Found 3 block(s) to create

✔️  Validation passed

Creating block 1/3: hero-banner...
  ✔️  Successfully created hero-banner
Creating block 2/3: testimonial...
  ✔️  Successfully created testimonial
Creating block 3/3: cta-button...
  ✔️  Successfully created cta-button

==================================================
SUMMARY
==================================================
✔️  Successfully created: 3 block(s)
    - hero-banner
    - testimonial
    - cta-button

Tips:

• Use wp-lemon blocks create-excel to get a template file
• Edit in Excel/Google Sheets, then export as CSV
• Keep the CSV in your project for documentation
• Test with a small CSV first before creating many blocks

wp-lemon blocks update

Updates all blocks in your site to the latest versions and standards.

Usage:

npx wp-lemon blocks update

What it does:

• Scans all blocks in your site
• Updates block metadata and registration
• Migrates blocks to latest WordPress block standards
• Updates block styles and scripts
• Validates block configurations

Note: This feature is currently in development. Check back soon for updates!

Help & Version

wp-lemon help

Displays comprehensive help information about all available commands.

Usage:

npx wp-lemon help

or

npx wp-lemon --help
npx wp-lemon -h

wp-lemon --version

Displays the current version of the wp-lemon CLI tool.

Usage:

npx wp-lemon --version
npx wp-lemon -v

🤝 Contributing

We welcome contributions from the wp-lemon community! Here's how you can help improve wp-lemon-create:

Getting Started

1. Fork the repository on GitHub

   git clone [email protected]:YOUR_USERNAME/wp-lemon-create.git
   cd wp-lemon-create

2. Install dependencies

   npm install

3. Create a feature branch

   git checkout -b feature/your-feature-name

Development Workflow

Running Tests

npm test

This runs the CLI test suite and validates all commands.

Testing Commands Locally

Link the package locally for testing:

npm link

Then test commands as if they were globally installed:

npx wp-lemon site create
npx wp-lemon block create

To unlink:

npm unlink

Code Structure

wp-lemon-create/
├── index.js                    # Main CLI entry point
├── lib/
│   ├── banner.js              # CLI banner display
│   ├── actions/
│   │   ├── help.js            # Help command handler
│   │   ├── site/
│   │   │   ├── site-create.js # Site creation logic
│   │   │   ├── site-eject.js  # Site ejection logic
│   │   │   └── create-vanilla.js # Vanilla site setup
│   │   └── block/
│   │       ├── block-create.js # Block scaffolding
│   │       └── block-reuse.js  # Block reuse logic
│   └── helpers/
│       └── test-block-version.js # Version utilities
├── test/
│   └── cli.test.js            # Test suite
└── package.json               # Dependencies & scripts

Common Tasks

Adding a New Command

1. Create action file in appropriate directory:

   // lib/actions/your-feature/your-command.js
   const yourCommand = () => {
       // Implementation
   };
   
   module.exports = { yourCommand };

2. Import in index.js:

   const { yourCommand } = require('./lib/actions/your-feature/your-command');

3. Register command:

   const yourCommand = program.command('your-feature');
   yourCommand
       .command('your-command')
       .description('Description of your command')
       .action(() => {
           showBanner('Your Command');
           yourCommand();
       });

Adding a Helper Function

1. Create in lib/helpers/:

   // lib/helpers/your-helper.js
   const yourHelper = (param) => {
       // Implementation
   };
   
   module.exports = { yourHelper };

2. Import where needed and add tests

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

Getting Help

• 📖 Read the documentation
• 🐛 Report bugs
• 💡 Suggest features
• 📧 Contact: [email protected]

🔗 Related Resources

• wp-lemon WordPress Theme
• WordPress Block Development
• npm Documentation
• Studio Lemon

Made with ❤️ by Studio Lemon