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
  • Content Commands
  • Help & Version
• Contributing
• License
• Support

✨ Features

• 🚀 Quick Site Setup - Scaffold a new wp-lemon WordPress site in minutes
• 🧩 Block Management - Create, reuse, rename, 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!

wp-lemon site refactor

Refactors an existing wp-lemon site by updating Bedrock, WordPress core, plugins, parent theme, and child theme to the latest versions.

Usage:

npx wp-lemon site refactor

What it does:

• Backs up the current child theme to {theme-name}-old
• Downloads and installs the latest Bedrock WordPress boilerplate
• Updates WordPress core to the latest version
• Updates all plugins (ACF Pro, Fluent Forms, Rank Math, etc.)
• Updates the wp-lemon parent theme
• Downloads and configures the latest wp-lemon child theme
• Installs and builds npm/composer dependencies
• Preserves your .env and configuration files

Interactive prompts:

• Confirmation to proceed (requires clean git branch)
• Project URL (e.g., mysite.local)
• Optional plugins (SearchWP, WPML)
• Hosting environment (SpinupWP or WP Rocket)

Process flow:

1. Renames existing theme to {theme-name}-old as backup
2. Creates temporary directory for fresh installation
3. Installs Bedrock and all dependencies in temp directory
4. Moves all files from temp to root (including dotfiles)
5. Cleans up temporary files

⚠️ Important:

• Make sure you're on a clean git branch before running
• Commit all changes before refactoring
• Review changes after refactoring before committing
• The old theme backup allows you to compare or restore if needed

Example:

$ npx wp-lemon site refactor
# Make sure you are on a clean git branch and have committed all your changes. Press any key to continue
# What is the project URL? (e.g. mysite.local): mysite.local
# Add plugin: SearchWP? yes/no (defaults to no) no
# Add plugin: WPML? yes/no (defaults to no) no
# Does the project run on Spinup-wp? (defaults to no) yes

wp-lemon site pull

Pulls the database from a remote wp-lemon site into your local environment using WP Migrate DB Pro.

Usage:

npx wp-lemon site pull

What it does:

• Installs WordPress core locally (with default test credentials)
• Activates the WP Migrate DB Pro plugin
• Prompts for confirmation before proceeding
• Updates the WP Migrate DB Pro license key
• Pulls the database from the specified remote site

Requirements:

• WP Migrate DB Pro must be installed
• A valid WP Migrate DB Pro license key
• The remote site URL and its push/pull connection key

Interactive prompts:

• Confirmation to proceed (y/n)
• WP Migrate DB Pro license key
• URL of the remote site to pull from

Example:

$ npx wp-lemon site pull
Do you want to pull the database? (y/n) y
Enter your WP Migrate DB Pro key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Enter the URL of the site you want to pull from: https://mysite.com

⚠️ Warning: This will overwrite your local database. Make sure you have a backup before pulling!

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

wp-lemon block rename

Renames an existing block in the current site, updating all file names, file contents, and references.

Usage:

npx wp-lemon block rename

What it does:

• Lists all available blocks in the current directory
• Prompts for the block to rename and the new name
• Validates that the source block exists and the new name is available
• Renames the block directory
• Renames all files containing the old block name
• Updates all references to the old block name inside files
• Updates the SCSS import in the theme's _index.scss file

Interactive prompts:

• Block to rename (select from available blocks)
• New block name

Example:

$ npx wp-lemon block rename

Available blocks:
  - hero-banner
  - testimonial
  - cta-button

Block to rename: hero-banner
New block name: hero-section

Renaming block from hero-banner to hero-section...
  Renamed file: hero-banner.php → hero-section.php
  Renamed file: hero-banner.twig → hero-section.twig
  Renamed file: acf-hero-banner.scss → acf-hero-section.scss
  Updated scss import in _index.scss

✔️  Successfully renamed block from hero-banner to hero-section

⚠️ Important Notes:

• Must be run from the blocks directory
• All file contents are updated automatically
• SCSS imports are automatically updated
• Make sure to rebuild your assets after renaming

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!

Content Commands

wp-lemon content backup

Imports or exports site content by handling database dumps, uploads, or both, based on interactive prompts.

Usage:

npx wp-lemon content backup

Run location:

• Run this command from the root of your wp-lemon project
• The command derives your project name from the current folder
• It expects your local stack path at ~/sites/<project-name>/

What it does:

• Asks if you want to import or export
• Asks if you want to process all, files, or db
• Starts your local server with start-server when available
• Exports/imports the database with wp db export and wp db import
• Exports/imports uploads as uploads.zip in the project root

Generated/expected files in project root:

• <project-name>.sql
• uploads.zip

Interactive prompts:

• Would you like to import or export? (import/export)
• What would you like to <import|export>? (all/files/db)

Example:

$ npx wp-lemon content backup
Would you like to import or export? (import/export): export
What would you like to export? (all/files/db): all
Running export
Backup command completed successfully.

⚠️ Important:

• Importing will overwrite your local database/uploads when selected
• Ensure <project-name>.sql and/or uploads.zip exist before import
• Requires wp-cli; file archive actions require zip/unzip

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