WP-CLI’s search-replace command handles serialized data automatically, validates replacements before executing, and shows exactly what changed. It’s the only safe way to modify WordPress database content at scale.

In this guide, you’ll master WP-CLI search-replace for site migrations, domain changes, protocol updates, and any database modification requiring precision and safety.

Why WP-CLI Search-Replace is Critical

WordPress serialized data contains length values that break when modified with simple find-replace operations.

Problems with Manual Database Search-Replace

Serialized data corruption: Direct MySQL replacement breaks array and object serialization.

Partial replacements: URLs in JSON, meta fields, and options get missed.

No validation: Can’t preview changes before executing them.

No reporting: Don’t know what was changed or how many replacements occurred.

Irreversible: Once executed, can’t undo without restoring backups.

WP-CLI Search-Replace Advantages

Serialization-safe: Automatically recalculates lengths in serialized strings.

Dry-run mode: Preview all changes before executing them.

Comprehensive: Searches all tables, columns, and data types.

Detailed reporting: Shows exactly what will change and where.

Table-specific: Target specific tables or exclude sensitive data.

According to WordPress migration studies, 80% of failed migrations are due to incorrect URL replacement breaking serialized data.

Search-Replace Fundamentals

Master basic search-replace operations safely.

Basic Search-Replace Syntax

# Basic replacement
wp search-replace 'old-text' 'new-text'

# Replace in specific tables
wp search-replace 'old' 'new' wp_posts wp_postmeta

# Replace in all tables (dangerous, use carefully)
wp search-replace 'old' 'new' --all-tables

# Skip specific columns
wp search-replace 'old' 'new' --skip-columns=guid

Always Use Dry-Run First

# Preview changes without executing (CRITICAL!)
wp search-replace 'oldsite.com' 'newsite.com' --dry-run

# Dry-run with detailed report
wp search-replace 'http://' 'https://' --dry-run --report

# See exact replacement count
wp search-replace 'old' 'new' --dry-run --report --precise

Critical Rule: NEVER run search-replace without --dry-run first. Always preview changes.

Understanding Serialized Data

# WordPress serialized data example:
# a:3:{s:4:"name";s:4:"John";s:3:"age";i:30;}
#      ^ length     ^ length

# Direct MySQL replacement breaks this:
# UPDATE wp_options SET option_value =
# REPLACE(option_value, 'John', 'Jonathan');
# Result: a:3:{s:4:"name";s:8:"Jonathan";...}
#                        ^ WRONG! Should be s:8

# WP-CLI handles this automatically:
wp search-replace 'John' 'Jonathan' wp_options

# WP-CLI recalculates: s:4 becomes s:8 automatically

Learn more about WP-CLI search-replace documentation.

Common Search-Replace Use Cases

Handle the most frequent WordPress database modification scenarios.

Domain Migration

#!/bin/bash
# migrate-domain.sh - Complete domain change

OLD_DOMAIN="oldsite.com"
NEW_DOMAIN="newsite.com"

# Backup first (ALWAYS!)
wp db export backup-before-domain-change.sql.gz

# Dry-run to preview
echo "Previewing changes..."
wp search-replace "https://$OLD_DOMAIN" "https://$NEW_DOMAIN" --dry-run --report

# Ask for confirmation
read -p "Proceed with replacement? (y/n) " -n 1 -r
echo
if [[ ! $REPLY =~ ^[Yy]$ ]]; then
    echo "Operation cancelled"
    exit 0
fi

# Execute replacements
echo "Executing replacements..."

# Replace full URLs
wp search-replace "https://$OLD_DOMAIN" "https://$NEW_DOMAIN"
wp search-replace "http://$OLD_DOMAIN" "https://$NEW_DOMAIN"

# Replace protocol-relative URLs
wp search-replace "//$OLD_DOMAIN" "//$NEW_DOMAIN"

# Update WordPress options directly
wp option update home "https://$NEW_DOMAIN"
wp option update siteurl "https://$NEW_DOMAIN"

# Flush caches
wp cache flush
wp rewrite flush

echo "✓ Domain migration complete"

HTTP to HTTPS Migration

#!/bin/bash
# migrate-to-https.sh

DOMAIN="example.com"

# Backup
wp db export backup-before-https.sql.gz

# Dry-run
wp search-replace "http://$DOMAIN" "https://$DOMAIN" --dry-run

# Execute
wp search-replace "http://$DOMAIN" "https://$DOMAIN"

# Update options
wp option update home "https://$DOMAIN"
wp option update siteurl "https://$DOMAIN"

echo "✓ Migrated to HTTPS"

Use Case: Essential for SEO and security—Google requires HTTPS for ranking.

Path Changes (Subdirectory Moves)

# Move from subdirectory to root
wp search-replace 'https://example.com/blog' 'https://example.com'

# Move from root to subdirectory
wp search-replace 'https://example.com' 'https://example.com/wordpress'

# Move between subdirectories
wp search-replace 'https://example.com/old' 'https://example.com/new'

Content Text Replacement

# Replace company name in all content
wp search-replace 'Old Company LLC' 'New Company Inc' wp_posts

# Fix common typos across site
wp search-replace 'recieve' 'receive' wp_posts wp_postmeta

# Update email addresses
wp search-replace 'contact@oldcompany.com' 'contact@newcompany.com'

# Replace shortcodes
wp search-replace '[old_shortcode]' '[new_shortcode]' wp_posts

Advanced Search-Replace Techniques

Handle complex scenarios with precision.

Regex Pattern Replacement

# Enable regex mode
wp search-replace 'pattern' 'replacement' --regex

# Replace all HTTP/HTTPS variations
wp search-replace 'https?://oldsite\.com' 'https://newsite.com' --regex

# Remove URL parameters
wp search-replace '\?utm_[^\s"]+' '' --regex wp_posts

# Fix malformed URLs
wp search-replace 'http://http://' 'http://' --regex

Warning: Test regex patterns thoroughly with --dry-run. Incorrect patterns cause unexpected replacements.

Table-Specific Operations

# Replace in posts and metadata only
wp search-replace 'old' 'new' wp_posts wp_postmeta

# Replace in all tables except options
wp search-replace 'old' 'new' --all-tables-with-prefix --skip-tables=wp_options

# List all tables first
wp db tables

# Replace in custom tables
wp search-replace 'old' 'new' wp_custom_table

Export Replacement Report

# Generate CSV report of all changes
wp search-replace 'old' 'new' --export=changes.csv

# Generate report with dry-run
wp search-replace 'old' 'new' --dry-run --report > replacement-report.txt

# Count replacements
REPLACEMENTS=$(wp search-replace 'old' 'new' --dry-run --format=count)
echo "Will replace $REPLACEMENTS occurrences"

Learn about WordPress database tables structure.

Skip Sensitive Columns

# Don't modify GUIDs (recommended)
wp search-replace 'old' 'new' --skip-columns=guid

# Skip multiple columns
wp search-replace 'old' 'new' --skip-columns=guid,post_date

# Skip user passwords and meta
wp search-replace 'old' 'new' wp_users --skip-columns=user_pass

Best Practice: Always skip guid column—changing GUIDs breaks feed readers and external references.

Safe Migration Workflow

Complete migration process with validation and rollback capability.

Complete Migration Script

#!/bin/bash
set -euo pipefail

# Configuration
SOURCE_URL="https://staging.example.com"
TARGET_URL="https://example.com"
BACKUP_DIR="/backups"
LOG_FILE="/var/log/migration.log"

log() {
    echo "[$(date '+%Y-%m-%d %H:%M:%S')] $@" | tee -a "$LOG_FILE"
}

log "=== WordPress Migration Started ==="

# Validate WordPress
if ! wp core is-installed; then
    log "ERROR: WordPress not installed"
    exit 1
fi

# Create backup
log "Creating backup..."
BACKUP_FILE="$BACKUP_DIR/pre-migration-$(date +%Y%m%d-%H%M%S).sql.gz"
wp db export "$BACKUP_FILE"

BACKUP_SIZE=$(stat -c%s "$BACKUP_FILE")
if [ "$BACKUP_SIZE" -lt 1000 ]; then
    log "ERROR: Backup too small, aborting"
    exit 1
fi
log "✓ Backup created: $BACKUP_FILE"

# Dry-run validation
log "Validating replacements..."
if ! wp search-replace "$SOURCE_URL" "$TARGET_URL" --dry-run --report &> /dev/null; then
    log "ERROR: Dry-run failed"
    exit 1
fi

# Count expected replacements
REPLACEMENTS=$(wp search-replace "$SOURCE_URL" "$TARGET_URL" --dry-run --report | grep -c "$SOURCE_URL" || true)
log "Found $REPLACEMENTS occurrences to replace"

if [ "$REPLACEMENTS" -eq 0 ]; then
    log "WARNING: No replacements found, check URLs"
fi

# Execute replacement
log "Executing search-replace..."
wp search-replace "$SOURCE_URL" "$TARGET_URL" --report

# Also replace without protocol
wp search-replace "//staging.example.com" "//example.com"

# Update options directly
log "Updating WordPress options..."
wp option update home "$TARGET_URL"
wp option update siteurl "$TARGET_URL"

# Verify replacements
log "Verifying replacements..."
REMAINING=$(wp search-replace "$SOURCE_URL" "$TARGET_URL" --dry-run --report | grep -c "$SOURCE_URL" || true)

if [ "$REMAINING" -gt 0 ]; then
    log "WARNING: $REMAINING occurrences still remain"
else
    log "✓ All occurrences replaced"
fi

# Clear caches
wp cache flush
wp rewrite flush

log "=== Migration Complete ==="
log "Rollback backup: $BACKUP_FILE"

Rollback Procedure

#!/bin/bash
# rollback-migration.sh

BACKUP_FILE="$1"

if [ -z "$BACKUP_FILE" ]; then
    echo "Usage: $0 <backup-file.sql.gz>"
    exit 1
fi

if [ ! -f "$BACKUP_FILE" ]; then
    echo "ERROR: Backup file not found: $BACKUP_FILE"
    exit 1
fi

echo "Rolling back to: $BACKUP_FILE"
read -p "This will overwrite current database. Continue? (y/n) " -n 1 -r
echo

if [[ ! $REPLY =~ ^[Yy]$ ]]; then
    echo "Rollback cancelled"
    exit 0
fi

# Restore database
wp db import "$BACKUP_FILE"

# Flush caches
wp cache flush
wp rewrite flush

echo "✓ Rollback complete"

Troubleshooting Search-Replace

Fix common search-replace issues.

URLs Not Changing

# Check current URLs in database
wp search-replace 'oldsite.com' 'oldsite.com' --dry-run --report | head -20

# Try all URL variations
wp search-replace 'http://oldsite.com' 'https://newsite.com'
wp search-replace 'https://oldsite.com' 'https://newsite.com'
wp search-replace 'http://www.oldsite.com' 'https://newsite.com'
wp search-replace '//oldsite.com' '//newsite.com'

# Force update options
wp option update home 'https://newsite.com'
wp option update siteurl 'https://newsite.com'

Serialization Errors

# Check for serialization issues
wp search-replace 'old' 'new' --precise

# Skip problematic tables
wp search-replace 'old' 'new' --skip-tables=wp_options

# Replace table by table
for TABLE in $(wp db tables --format=csv); do
    echo "Processing: $TABLE"
    wp search-replace 'old' 'new' "$TABLE" --dry-run
done

Performance Issues

# Large databases may timeout, increase PHP limits
php -d memory_limit=512M wp search-replace 'old' 'new'

# Process tables individually for very large databases
wp search-replace 'old' 'new' wp_posts
wp search-replace 'old' 'new' wp_postmeta
wp search-replace 'old' 'new' wp_options

Next Steps

You now have professional WordPress search-replace skills for safe database migrations.

Recommended Learning Path

Week 1: Basic replacements

• Practice dry-run workflows
• Test domain changes on staging
• Learn serialization concepts

Week 2: Advanced techniques

• Master regex patterns
• Handle complex migrations
• Build verification scripts

Week 3: Production migrations

• Create complete migration workflows
• Implement rollback procedures
• Document migration playbooks

Week 4: Automation

• Build migration scripts
• Add validation checks
• Automate testing

Advanced Topics

1. Multisite Search-Replace – Network-wide replacements
2. Large Database Migrations – Handle millions of records
3. Custom Table Migrations – Plugin-specific data

Get More Resources

Download migration scripts including:

• Complete migration automation
• Rollback procedures
• Validation checklists

Join our email course for:

• Weekly WP-CLI tutorials
• Migration best practices
• Advanced database techniques

Conclusion

WP-CLI search-replace is the only safe way to modify WordPress database content, handling serialized data automatically while giving you complete control and visibility.

What we covered:

✅ Search-replace fundamentals with dry-run validation
✅ Common use cases (domain changes, HTTPS migration, paths)
✅ Advanced techniques (regex, table-specific, reporting)
✅ Safe migration workflows with backups and rollback
✅ Troubleshooting common search-replace issues

Master these techniques, and you’ll handle WordPress migrations and database modifications with confidence—whether changing domains, updating URLs, or migrating content.

Ready for more? Learn WordPress database optimization or advanced WP-CLI automation.

Questions about WP-CLI search-replace? Drop a comment below!

Found this helpful? Share with other WordPress developers.

The post WP-CLI Search-Replace: Safe Database Modifications for WordPress Migration appeared first on WP-CLI Mastery.

In this advanced guide, you’ll learn to create production-ready custom WP-CLI commands from scratch. You’ll understand command structure, parameter handling, the WP_CLI API, and how to package your commands for distribution.

By the end, you’ll have the skills to build professional CLI tools that make WordPress management even more powerful.

Why Create Custom WP-CLI Commands?

Use Cases for Custom Commands

Plugin-Specific Operations

• Flush custom caches
• Run migrations
• Import/export plugin data
• Administrative tasks

Agency/Enterprise Workflows

• Client onboarding automation
• Standardized site audits
• Custom deployment tasks
• Compliance reporting

Development Tools

• Generate boilerplate code
• Database seeding
• Testing helpers
• Performance profiling

Benefits Over Manual Scripts

Integration with WP-CLI Ecosystem

• Automatic WordPress context loading
• Access to all WordPress functions
• Works with WP-CLI packages
• Follows CLI conventions

Professional API

• WP_CLI::success(), WP_CLI::error(), WP_CLI::warning()
• Built-in progress bars
• Table formatting
• Color output

Distribution

• Share via Composer packages
• Install with wp package install
• Version management

Prerequisites

Before creating custom commands, you should have:

• WP-CLI installed – Installation guide
• PHP knowledge – Object-oriented PHP basics
• WordPress familiarity – Understanding of WordPress hooks and functions
• Bash fundamentals – Bash scripting guide

Command Structure Basics

Command Anatomy

WP-CLI commands follow this structure:

wp <command> <subcommand> <arguments> --<flags>

Examples:

wp plugin install woocommerce
#  ^^^^^^ ^^^^^^^ ^^^^^^^^^^^
#  cmd    subcmd  argument

wp post list --post_type=page --format=table
#  ^^^^ ^^^^ ^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^
#  cmd  sub  flag=value        flag=value

Command Registration

Commands are registered using WP_CLI::add_command():

WP_CLI::add_command('hello', 'My_Hello_Command');

This creates: wp hello

Class-Based vs Function-Based

Class-based (recommended):

class My_Command {
		public function greet($args, $assoc_args) {
				WP_CLI::success("Hello!");
		}
}

WP_CLI::add_command('mycommand greet', 'My_Command');

Function-based:

function my_greet_command($args, $assoc_args) {
		WP_CLI::success("Hello!");
}

WP_CLI::add_command('greet', 'my_greet_command');

Best practice: Use classes for better organization and multiple subcommands.

Your First Custom Commandnd}

Let’s create a simple custom command step-by-step.

Step 1: Create Plugin File

Create a plugin to hold your command:

<?php
/**
 * Plugin Name: My WP-CLI Commands
 * Description: Custom WP-CLI commands
 * Version: 1.0.0
 */

// Don't execute in non-CLI context
if (!defined('WP_CLI')) {
		return;
}

/**
 * Hello World command
 */
class Hello_Command {

		/**
		 * Prints a greeting
		 *
		 * ## EXAMPLES
		 *
		 *     wp hello greet
		 *     wp hello greet --name=John
		 */
		public function greet($args, $assoc_args) {
				$name = isset($assoc_args['name']) ? $assoc_args['name'] : 'World';

				WP_CLI::success("Hello, {$name}!");
		}
}

// Register the command
WP_CLI::add_command('hello', 'Hello_Command');

Step 2: Install Plugin

Save this as wp-content/plugins/my-cli-commands/my-cli-commands.php

Activate it:

wp plugin activate my-cli-commands

Step 3: Test Your Command

wp hello greet
# Success: Hello, World!

wp hello greet --name=John
# Success: Hello, John!

Congratulations! You’ve created your first custom WP-CLI command.

Step 4: View Help

WP-CLI automatically generates help documentation:

wp help hello greet

Using the WP_CLI Class

The WP_CLI class provides powerful methods for CLI interaction.

Output Methods

// Success message (green)
WP_CLI::success("Operation completed!");

// Error message (red) - exits script
WP_CLI::error("Something went wrong!");

// Warning message (yellow)
WP_CLI::warning("Proceeding with caution...");

// Info message (no color)
WP_CLI::log("Processing item 5 of 10");

// Debug message (only shown with --debug)
WP_CLI::debug("Variable value: " . $value);

Example:

public function process() {
		WP_CLI::log("Starting processing...");

		if (!file_exists($file)) {
				WP_CLI::warning("File not found, using defaults");
		}

		if ($error) {
				WP_CLI::error("Processing failed!");  // Exits here
		}

		WP_CLI::success("Processing complete!");
}

Progress Bars

For long-running operations:

public function import_posts($args) {
		$posts = range(1, 1000);

		$progress = \WP_CLI\Utils\make_progress_bar('Importing posts', count($posts));

		foreach ($posts as $post) {
				// Do import work
				sleep(0.01);  // Simulate work

				$progress->tick();
		}

		$progress->finish();
		WP_CLI::success("Imported " . count($posts) . " posts");
}

Output:

Importing posts  500/1000 [==============>              ] 50%

Confirmation Prompts

Confirm destructive operations:

public function delete_all_posts() {
		WP_CLI::confirm("Are you sure you want to delete ALL posts?");

		// User must type 'y' or 'yes' to continue
		// Otherwise, script exits

		// Proceed with deletion
		WP_CLI::success("All posts deleted");
}

Usage:

wp mycommand delete-all-posts
# Are you sure you want to delete ALL posts? [y/n]

Skip confirmation in scripts:

wp mycommand delete-all-posts --yes

Learn more in the official WP_CLI class documentation.

Parameter Handling with Synopsis

Synopsis defines your command’s parameters and flags.

Basic Synopsis

/**
 * Import data from file
 *
 * ## OPTIONS
 *
 * <file>
 * : Path to import file
 *
 * [--format=<format>]
 * : Import format (json, csv)
 * ---
 * default: json
 * options:
 *   - json
 *   - csv
 * ---
 *
 * ## EXAMPLES
 *
 *     wp mycommand import data.json
 *     wp mycommand import data.csv --format=csv
 *
 * @when after_wp_load
 */
public function import($args, $assoc_args) {
		list($file) = $args;  // Required positional argument

		$format = $assoc_args['format'];  // Has default value

		WP_CLI::log("Importing {$file} as {$format}");
}

Parameter Types

Required positional argument:

/**
 * <file>
 * : Path to file
 */

Usage: wp cmd import file.json

Optional positional argument:

/**
 * [<file>]
 * : Path to file (optional)
 */

Required flag:

/**
 * --user=<id>
 * : User ID (required)
 */

Usage: wp cmd process --user=1

Optional flag with default:

/**
 * [--format=<format>]
 * : Output format
 * ---
 * default: table
 * options:
 *   - table
 *   - json
 *   - csv
 * ---
 */

Boolean flag:

/**
 * [--dry-run]
 * : Run without making changes
 */

Usage: wp cmd process --dry-run

Check in code:

$dry_run = isset($assoc_args['dry-run']) && $assoc_args['dry-run'];

Accessing Parameters

public function command($args, $assoc_args) {
		// Positional arguments (ordered)
		$first_arg = isset($args[0]) ? $args[0] : '';
		$second_arg = isset($args[1]) ? $args[1] : '';

		// Or use list()
		list($file, $action) = $args;

		// Associative arguments (flags)
		$format = $assoc_args['format'];  // No default, may not exist
		$format = isset($assoc_args['format']) ? $assoc_args['format'] : 'table';

		// Get with default helper
		$format = \WP_CLI\Utils\get_flag_value($assoc_args, 'format', 'table');
}

Output Formatting

Table Format

Display data as tables:

public function list_users() {
		$users = get_users(array('number' => 10));

		$items = array();
		foreach ($users as $user) {
				$items[] = array(
						'ID' => $user->ID,
						'Username' => $user->user_login,
						'Email' => $user->user_email,
						'Role' => implode(', ', $user->roles)
				);
		}

		\WP_CLI\Utils\format_items('table', $items, array('ID', 'Username', 'Email', 'Role'));
}

Output:

+----+----------+------------------+-------------+
| ID | Username | Email            | Role        |
+----+----------+------------------+-------------+
| 1  | admin    | admin@site.com   | administrator |
| 2  | editor   | editor@site.com  | editor      |
+----+----------+------------------+-------------+

JSON Format

\WP_CLI\Utils\format_items('json', $items, array('ID', 'Username', 'Email'));

Output:

[
	{"ID":"1","Username":"admin","Email":"admin@site.com"},
	{"ID":"2","Username":"editor","Email":"editor@site.com"}
]

CSV Format

\WP_CLI\Utils\format_items('csv', $items, array('ID', 'Username', 'Email'));

Output:

ID,Username,Email
1,admin,admin@site.com
2,editor,editor@site.com

Supporting Multiple Formats

/**
 * [--format=<format>]
 * : Output format
 * ---
 * default: table
 * options:
 *   - table
 *   - json
 *   - csv
 *   - count
 * ---
 */
public function list($args, $assoc_args) {
		$format = \WP_CLI\Utils\get_flag_value($assoc_args, 'format', 'table');

		$items = $this->get_items();

		if ('count' === $format) {
				WP_CLI::log(count($items));
				return;
		}

		\WP_CLI\Utils\format_items($format, $items, array('ID', 'Title', 'Status'));
}

Error Handling

Validation

Always validate parameters:

public function import($args, $assoc_args) {
		list($file) = $args;

		// Check file exists
		if (!file_exists($file)) {
				WP_CLI::error("File not found: {$file}");
		}

		// Check file is readable
		if (!is_readable($file)) {
				WP_CLI::error("File is not readable: {$file}");
		}

		// Validate format
		$format = $assoc_args['format'];
		$allowed = array('json', 'csv');
		if (!in_array($format, $allowed)) {
				WP_CLI::error("Invalid format: {$format}. Must be: " . implode(', ', $allowed));
		}

		// Proceed with import...
}

Try-Catch

Handle exceptions gracefully:

public function process() {
		try {
				$this->do_risky_operation();
				WP_CLI::success("Operation completed");
		} catch (Exception $e) {
				WP_CLI::error("Operation failed: " . $e->getMessage());
		}
}

Exit Codes

Commands should return appropriate exit codes:

• 0 – Success
• 1 – Error (automatic with WP_CLI::error())

Complete Example: Site Audit Command

Let’s build a real-world command that audits a WordPress site.

<?php
/**
 * Plugin Name: Site Audit Command
 * Description: Custom WP-CLI command for site auditing
 * Version: 1.0.0
 */

if (!defined('WP_CLI')) {
		return;
}

/**
 * Performs comprehensive site audits
 */
class Site_Audit_Command {

		/**
		 * Run a complete site audit
		 *
		 * ## OPTIONS
		 *
		 * [--format=<format>]
		 * : Output format
		 * ---
		 * default: table
		 * options:
		 *   - table
		 *   - json
		 * ---
		 *
		 * [--save=<file>]
		 * : Save results to file
		 *
		 * ## EXAMPLES
		 *
		 *     wp site-audit run
		 *     wp site-audit run --format=json
		 *     wp site-audit run --save=audit-report.json
		 *
		 * @when after_wp_load
		 */
		public function run($args, $assoc_args) {
				WP_CLI::log("Running site audit...");

				$results = array();

				// WordPress version
				$results[] = $this->check_wordpress_version();

				// Plugin updates
				$results[] = $this->check_plugin_updates();

				// Theme updates
				$results[] = $this->check_theme_updates();

				// Database size
				$results[] = $this->check_database_size();

				// Upload directory size
				$results[] = $this->check_uploads_size();

				// Orphaned data
				$results[] = $this->check_orphaned_data();

				// Get format
				$format = \WP_CLI\Utils\get_flag_value($assoc_args, 'format', 'table');

				// Output results
				if ('json' === $format) {
						WP_CLI::log(json_encode($results, JSON_PRETTY_PRINT));
				} else {
						\WP_CLI\Utils\format_items('table', $results, array('Check', 'Status', 'Details'));
				}

				// Save to file if requested
				if (isset($assoc_args['save'])) {
						file_put_contents($assoc_args['save'], json_encode($results, JSON_PRETTY_PRINT));
						WP_CLI::success("Audit saved to: " . $assoc_args['save']);
				}

				WP_CLI::success("Audit complete!");
		}

		private function check_wordpress_version() {
				global $wp_version;

				$updates = get_core_updates();
				$has_update = isset($updates[0]) && $updates[0]->response === 'upgrade';

				return array(
						'Check' => 'WordPress Version',
						'Status' => $has_update ? '⚠ Update Available' : '✓ Up to Date',
						'Details' => 'Current: ' . $wp_version
				);
		}

		private function check_plugin_updates() {
				$updates = get_plugin_updates();
				$count = count($updates);

				return array(
						'Check' => 'Plugin Updates',
						'Status' => $count > 0 ? "⚠ {$count} available" : '✓ All updated',
						'Details' => $count > 0 ? implode(', ', array_keys($updates)) : 'None'
				);
		}

		private function check_theme_updates() {
				$updates = get_theme_updates();
				$count = count($updates);

				return array(
						'Check' => 'Theme Updates',
						'Status' => $count > 0 ? "⚠ {$count} available" : '✓ All updated',
						'Details' => $count > 0 ? implode(', ', array_keys($updates)) : 'None'
				);
		}

		private function check_database_size() {
				global $wpdb;

				$size = $wpdb->get_var("
						SELECT SUM(data_length + index_length) / 1024 / 1024
						FROM information_schema.TABLES
						WHERE table_schema = '{$wpdb->dbname}'
				");

				$size_mb = round($size, 2);
				$status = $size_mb > 500 ? '⚠ Large' : '✓ Normal';

				return array(
						'Check' => 'Database Size',
						'Status' => $status,
						'Details' => "{$size_mb} MB"
				);
		}

		private function check_uploads_size() {
				$upload_dir = wp_upload_dir();
				$path = $upload_dir['basedir'];

				$size = $this->get_directory_size($path);
				$size_mb = round($size / 1024 / 1024, 2);
				$status = $size_mb > 5000 ? '⚠ Large' : '✓ Normal';

				return array(
						'Check' => 'Uploads Directory',
						'Status' => $status,
						'Details' => "{$size_mb} MB"
				);
		}

		private function check_orphaned_data() {
				global $wpdb;

				// Count orphaned post meta
				$orphaned = $wpdb->get_var("
						SELECT COUNT(*)
						FROM {$wpdb->postmeta} pm
						LEFT JOIN {$wpdb->posts} p ON p.ID = pm.post_id
						WHERE p.ID IS NULL
				");

				$status = $orphaned > 0 ? "⚠ {$orphaned} found" : '✓ None';

				return array(
						'Check' => 'Orphaned Post Meta',
						'Status' => $status,
						'Details' => $orphaned > 0 ? "Run cleanup recommended" : 'Clean'
				);
		}

		private function get_directory_size($path) {
				$size = 0;

				foreach (new RecursiveIteratorIterator(new RecursiveDirectoryIterator($path)) as $file) {
						if ($file->isFile()) {
								$size += $file->getSize();
						}
				}

				return $size;
		}
}

WP_CLI::add_command('site-audit', 'Site_Audit_Command');

Usage

# Run audit
wp site-audit run

# JSON output
wp site-audit run --format=json

# Save to file
wp site-audit run --save=audit-2025.json

Output:

+---------------------+-------------------+------------------+
| Check               | Status            | Details          |
+---------------------+-------------------+------------------+
| WordPress Version   | ✓ Up to Date      | Current: 6.4.2   |
| Plugin Updates      | ⚠ 3 available     | woocommerce, ... |
| Theme Updates       | ✓ All updated     | None             |
| Database Size       | ✓ Normal          | 45.23 MB         |
| Uploads Directory   | ⚠ Large           | 5432.12 MB       |
| Orphaned Post Meta  | ⚠ 156 found       | Run cleanup...   |
+---------------------+-------------------+------------------+
Success: Audit complete!

Packaging Commands

Create Composer Package

Structure your command as a Composer package:

my-wp-cli-command/
├── composer.json
├── command.php
└── README.md

composer.json:

{
		"name": "vendor/my-wpcli-command",
		"description": "Custom WP-CLI command for site auditing",
		"type": "wp-cli-package",
		"require": {
				"php": ">=7.4"
		},
		"autoload": {
				"files": ["command.php"]
		},
		"extra": {
				"commands": [
						"site-audit"
				]
		}
}

Install via Composer

Users can install your command:

wp package install vendor/my-wpcli-command

Or via composer.json:

{
		"require": {
				"vendor/my-wpcli-command": "^1.0"
		}
}

Learn more: WP-CLI Package Index

Testing Custom Commands

Manual Testing

# Test basic functionality
wp site-audit run

# Test with flags
wp site-audit run --format=json

# Test error handling (invalid flag)
wp site-audit run --format=invalid

Automated Testing with Behat

For serious projects, use WP-CLI’s testing framework:

# Install testing framework
composer require --dev wp-cli/wp-cli-tests

Example test:

Feature: Site audit command

	Scenario: Run basic audit
		Given a WP install

		When I run `wp site-audit run`
		Then STDOUT should contain "Audit complete"
		And the return code should be 0

	Scenario: Save audit to file
		Given a WP install

		When I run `wp site-audit run --save=test-audit.json`
		Then the test-audit.json file should exist
		And STDOUT should contain "Audit saved"

Learn more: WP-CLI Testing Documentation

Distribution

GitHub Repository

Host your command on GitHub:

1. Create repo: my-wpcli-command
2. Push code with composer.json
3. Tag releases: v1.0.0, v1.1.0, etc.

WP-CLI Package Index

Submit to WP-CLI Package Index:

1. Follow package guidelines
2. Submit pull request to package index
3. Wait for review and approval

WordPress Plugin Directory

Optionally distribute as WordPress plugin:

• Works automatically when plugin is activated
• Discoverable via WordPress.org
• Easier for non-technical users

Real-World Examples

Official WP-CLI Packages

Study these for inspiration:

• wp-cli/doctor-command – Health checks
• wp-cli/profile-command – Performance profiling
• wp-cli/scaffold-command – Code generation

Popular Third-Party Commands

• WooCommerce CLI – WooCommerce management
• ACF CLI – Advanced Custom Fields operations
• Yoast SEO CLI – SEO management

Browse more: WP-CLI Package Index

Troubleshooting

Command Not Found

Problem: wp mycommand returns “Error: ‘mycommand’ is not a registered wp command.”

Solutions:

1. Check plugin is activated:

wp plugin list

2. Verify WP_CLI is defined:

if (!defined('WP_CLI')) {
		return; // Command won't register
}

3. Check command registration:

WP_CLI::add_command('mycommand', 'My_Command');

Parameters Not Working

Problem: Flags are ignored or cause errors.

Solutions:

1. Check synopsis syntax in docblock
2. Verify parameter names match:

$format = $assoc_args['format'];  // Must match --format

3. Provide defaults for optional parameters:

$format = \WP_CLI\Utils\get_flag_value($assoc_args, 'format', 'table');

Memory Limit Errors

Problem: Command fails with “Allowed memory size exhausted.”

Solution: Process items in batches:

public function process_all() {
		$per_page = 100;
		$page = 1;

		do {
				$items = get_posts(array(
						'posts_per_page' => $per_page,
						'paged' => $page
				));

				foreach ($items as $item) {
						// Process item
				}

				$page++;

		} while (count($items) === $per_page);
}

Next Steps

You now know how to create production-ready custom WP-CLI commands!

Continue Learning

1. Bash Functions for WordPress – Combine with shell scripts
2. WordPress CI/CD with GitHub Actions – Use commands in pipelines
3. WP-CLI Config Files – Advanced configuration

Build These Commands

Practice projects:

• Content migration command
• Security audit command
• Performance optimization command
• Database cleanup command
• Multi-site sync command

Master WordPress Automation

Want to build advanced automation systems with custom commands, APIs, and deployment pipelines?

Join the WPCLI Mastery waitlist and get:

• Advanced command development patterns
• Real-world command examples library
• Package creation templates
• Early bird course pricing ($99 vs $199)

Conclusion

Creating custom WP-CLI commands lets you extend WordPress automation with your specific workflow needs. Whether you’re building internal tools, distributing plugins, or streamlining client management, custom commands are essential for professional WordPress development.

Key takeaways:

• Use classes for organization and multiple subcommands
• Leverage WP_CLI class methods for professional output
• Define parameters with synopsis for clear documentation
• Support multiple output formats (table, JSON, CSV)
• Package with Composer for easy distribution
• Test thoroughly before releasing

The custom commands you build today become reusable tools that save time forever.

Ready to build? Start with the site audit example and adapt it to your needs.

Questions about custom WP-CLI commands? Drop a comment below!

Found this helpful? Share with other WordPress developers building CLI tools.

Next: Learn how to integrate external APIs with WordPress using WP-CLI commands.

The post How to Create Custom WP-CLI Commands: Developer’s Guide appeared first on WP-CLI Mastery.

Why Use WP-CLI for Performance Optimization

Traditional WordPress performance optimization through the dashboard is time-consuming and often incomplete. WP-CLI enables systematic, repeatable optimizations that can be automated, scripted, and applied across multiple sites simultaneously.

The command-line approach offers distinct advantages: batch processing of operations, precise control over optimization tasks, ability to schedule regular maintenance, detailed logging of changes, and integration with deployment pipelines. These capabilities make WP-CLI indispensable for professional WordPress performance management.

1. Database Optimization and Cleanup

Database bloat significantly impacts query performance. Over time, WordPress databases accumulate revisions, spam comments, orphaned metadata, and expired transients that slow down queries.

# Check database size before optimization
wp db size --tables

# Optimize all database tables
wp db optimize

# Remove post revisions older than 30 days
wp post delete $(wp post list --post_type=revision --format=ids --date_query='[{"before":"30 days ago"}]') --force

# Clean up spam and trashed comments
wp comment delete $(wp comment list --status=spam --format=ids) --force
wp comment delete $(wp comment list --status=trash --format=ids) --force

# Remove orphaned post metadata
wp db query "DELETE pm FROM wp_postmeta pm LEFT JOIN wp_posts wp ON wp.ID = pm.post_id WHERE wp.ID IS NULL"

# Clean expired transients
wp transient delete --expired

# Remove all transients (use cautiously)
wp transient delete --all

Create a comprehensive database cleanup script:

#!/bin/bash
# db-cleanup.sh - Comprehensive database optimization

WP_PATH="/var/www/html"

echo "Starting database optimization..."

# Backup before cleanup
wp --path="$WP_PATH" db export backup-pre-cleanup-$(date +%Y%m%d).sql

# Get initial database size
INITIAL_SIZE=$(wp --path="$WP_PATH" db size --human-readable --format=json | jq -r '.Size')
echo "Initial database size: $INITIAL_SIZE"

# Remove old post revisions (keep last 5 for each post)
wp --path="$WP_PATH" config set WP_POST_REVISIONS 5 --type=constant

# Delete old auto-drafts
wp --path="$WP_PATH" post delete $(wp --path="$WP_PATH" post list --post_status=auto-draft --format=ids) --force

# Clean comments
wp --path="$WP_PATH" comment delete $(wp --path="$WP_PATH" comment list --status=spam --format=ids) --force
wp --path="$WP_PATH" comment delete $(wp --path="$WP_PATH" comment list --status=trash --format=ids) --force

# Remove orphaned metadata
wp --path="$WP_PATH" db query "DELETE FROM wp_commentmeta WHERE comment_id NOT IN (SELECT comment_ID FROM wp_comments)"
wp --path="$WP_PATH" db query "DELETE FROM wp_postmeta WHERE post_id NOT IN (SELECT ID FROM wp_posts)"
wp --path="$WP_PATH" db query "DELETE FROM wp_termmeta WHERE term_id NOT IN (SELECT term_id FROM wp_terms)"

# Clean transients
wp --path="$WP_PATH" transient delete --expired

# Optimize tables
wp --path="$WP_PATH" db optimize

# Get final database size
FINAL_SIZE=$(wp --path="$WP_PATH" db size --human-readable --format=json | jq -r '.Size')
echo "Final database size: $FINAL_SIZE"
echo "Database optimization completed"

2. Cache Management

Effective cache management is crucial for performance. WP-CLI provides commands to manage object cache, page cache, and opcode cache.

# Flush object cache (Redis, Memcached, etc.)
wp cache flush

# Test cache functionality
wp cache set test_key test_value 300
wp cache get test_key

# For sites using Redis
wp redis info

# Clear page cache for specific plugins
# W3 Total Cache
wp w3-total-cache flush all

# WP Super Cache
wp cache flush

# Clear cache for specific pages/posts
wp transient delete --all

Implement intelligent cache warming:

#!/bin/bash
# cache-warm.sh - Warm up cache for important pages

SITE_URL="https://example.com"
WP_PATH="/var/www/html"

# Get list of published posts and pages
URLS=$(wp --path="$WP_PATH" post list --post_type=post,page --post_status=publish --field=url)

# Warm cache by requesting each URL
for url in $URLS; do
    echo "Warming cache: $url"
    curl -s -o /dev/null "$url"
    sleep 0.5  # Avoid overwhelming server
done

# Warm up homepage and key pages
curl -s -o /dev/null "$SITE_URL"
curl -s -o /dev/null "$SITE_URL/about"
curl -s -o /dev/null "$SITE_URL/contact"

echo "Cache warming completed"

3. Image Optimization

Images often account for the majority of page weight. WP-CLI can help automate image optimization tasks.

# Regenerate thumbnails for all images
wp media regenerate --yes

# Regenerate only missing thumbnails
wp media regenerate --only-missing --yes

# Regenerate images uploaded in specific timeframe
wp media regenerate --yes $(wp post list --post_type=attachment --format=ids --post_mime_type=image --year=2024)

# Install and configure image optimization plugin via CLI
wp plugin install ewww-image-optimizer --activate
wp option update ewww_image_optimizer_cloud_key 'YOUR_API_KEY'

# Bulk optimize existing images
wp ewwwio optimize all

4. Plugin Performance Audit

Identify and manage plugins that impact performance negatively.

# List all active plugins
wp plugin list --status=active

# Check for plugin updates
wp plugin list --update=available

# Deactivate unused plugins
wp plugin deactivate plugin-slug

# Remove unused plugins completely
wp plugin delete plugin-slug

# Identify plugins loading on every page
wp plugin list --status=active --field=name | while read plugin; do
    echo "Checking: $plugin"
    wp plugin path $plugin
done

Create a plugin performance audit script:

#!/bin/bash
# plugin-audit.sh - Audit plugin performance impact

WP_PATH="/var/www/html"

echo "=== Plugin Performance Audit ==="

# List active plugins with version info
echo -e "\nActive Plugins:"
wp --path="$WP_PATH" plugin list --status=active --fields=name,version,update,auto_update

# Check for outdated plugins
echo -e "\nPlugins requiring updates:"
wp --path="$WP_PATH" plugin list --update=available --fields=name,version,update_version

# Identify plugins with known performance issues
echo -e "\nChecking for resource-intensive plugins..."

# Get plugin file sizes
for plugin in $(wp --path="$WP_PATH" plugin list --status=active --field=name); do
    PLUGIN_PATH=$(wp --path="$WP_PATH" plugin path $plugin)
    SIZE=$(du -sh "$PLUGIN_PATH" 2>/dev/null | cut -f1)
    echo "$plugin: $SIZE"
done | sort -h

5. Autoload Optimization

Excessive autoloaded options slow down every WordPress request. Optimize autoloaded data to reduce overhead.

# Check autoload size
wp db query "SELECT SUM(LENGTH(option_value)) as autoload_size FROM wp_options WHERE autoload='yes'"

# List large autoloaded options
wp db query "SELECT option_name, LENGTH(option_value) as size FROM wp_options WHERE autoload='yes' ORDER BY size DESC LIMIT 20"

# Convert large options to non-autoload
wp option update large_option_name 'value' --autoload=no

# Remove obsolete autoloaded options
wp db query "DELETE FROM wp_options WHERE autoload='yes' AND option_name LIKE '%_transient_%'"

6. Query Monitoring and Optimization

Monitor database queries to identify performance bottlenecks.

# Enable query logging (for development)
wp config set SAVEQUERIES true --raw

# Check for slow queries in production
wp db query "SELECT * FROM information_schema.processlist WHERE command != 'Sleep' AND time > 5"

# Add database indexes for custom queries
wp db query "CREATE INDEX idx_meta_key_value ON wp_postmeta(meta_key, meta_value(100))"

# Analyze table structure
wp db query "SHOW INDEX FROM wp_posts"
wp db query "SHOW INDEX FROM wp_postmeta"

7. Content Delivery Network Integration

Configure CDN settings programmatically for consistent deployment.

# Update site URL for CDN
wp search-replace 'https://example.com/wp-content' 'https://cdn.example.com/wp-content' --dry-run

# After verifying, perform the replacement
wp search-replace 'https://example.com/wp-content' 'https://cdn.example.com/wp-content'

# Configure CDN plugin settings
wp option update cdn_url 'https://cdn.example.com'
wp option update cdn_enabled 1

8. Lazy Loading Implementation

Enable lazy loading for images and iframes to improve initial page load times.

# WordPress native lazy loading (5.5+)
wp option update wp_lazy_loading_enabled 1

# For older versions, use plugin
wp plugin install lazy-load --activate

# Configure lazy loading settings
wp option update lazy_load_images 1
wp option update lazy_load_iframes 1

9. Remove Unused CSS and JavaScript

Minimize loaded assets by disabling unnecessary scripts and styles.

# Identify loaded scripts on homepage
wp eval 'global $wp_scripts; print_r($wp_scripts->registered);'

# Dequeue unnecessary scripts via custom plugin
cat > wp-content/mu-plugins/performance-tweaks.php << 'EOF'
<?php
add_action('wp_enqueue_scripts', function() {
    // Remove jQuery migrate
    wp_deregister_script('jquery-migrate');

    // Remove emojis
    remove_action('wp_head', 'print_emoji_detection_script', 7);
    remove_action('wp_print_styles', 'print_emoji_styles');

    // Remove block library CSS if not using Gutenberg
    wp_dequeue_style('wp-block-library');
}, 100);
EOF

10. PHP Opcode Cache Configuration

Ensure opcode cache is properly configured for optimal PHP performance.

# Check if OPcache is enabled
wp eval 'var_dump(function_exists("opcache_get_status"));'

# Get OPcache statistics
wp eval 'print_r(opcache_get_status());'

# Clear OPcache when deploying code
wp eval 'opcache_reset();'

# Check PHP version and loaded extensions
wp cli info

11. Heartbeat API Optimization

The WordPress Heartbeat API can consume significant resources. Control its behavior to reduce server load.

# Disable Heartbeat API completely
cat > wp-content/mu-plugins/disable-heartbeat.php << 'EOF'
<?php
add_action('init', function() {
    wp_deregister_script('heartbeat');
}, 1);
EOF

# Or modify Heartbeat interval
cat > wp-content/mu-plugins/modify-heartbeat.php << 'EOF'
<?php
add_filter('heartbeat_settings', function($settings) {
    $settings['interval'] = 60; // 60 seconds instead of 15
    return $settings;
});
EOF

12. REST API Performance

Optimize REST API endpoints to reduce unnecessary overhead.

# Disable REST API for non-authenticated users
cat > wp-content/mu-plugins/restrict-rest-api.php << 'EOF'
<?php
add_filter('rest_authentication_errors', function($result) {
    if (!empty($result)) {
        return $result;
    }
    if (!is_user_logged_in()) {
        return new WP_Error(
            'rest_not_logged_in',
            'You are not logged in.',
            array('status' => 401)
        );
    }
    return $result;
});
EOF

13. Cron Optimization

WordPress cron can impact performance during peak traffic. Disable WP-Cron and use system cron instead.

# Disable WordPress cron
wp config set DISABLE_WP_CRON true --raw

# Add system cron job to handle WP cron
echo "*/15 * * * * wp --path=/var/www/html cron event run --due-now" | crontab -

# List scheduled cron events
wp cron event list

# Test cron execution
wp cron test

14. Asset Minification and Concatenation

Reduce HTTP requests and file sizes through minification.

# Install asset optimization plugin
wp plugin install autoptimize --activate

# Configure via CLI
wp option update autoptimize_html_optimize 1
wp option update autoptimize_js_optimize 1
wp option update autoptimize_css_optimize 1

# Clear optimization cache
wp autoptimize cache clear

15. Performance Monitoring and Benchmarking

Establish baseline metrics and monitor performance over time.

#!/bin/bash
# performance-benchmark.sh - Monitor site performance

WP_PATH="/var/www/html"
SITE_URL="https://example.com"

echo "=== WordPress Performance Benchmark ==="
echo "Date: $(date)"

# Database size
echo -e "\nDatabase Size:"
wp --path="$WP_PATH" db size --human-readable

# Autoload size
echo -e "\nAutoload Data:"
wp --path="$WP_PATH" db query "SELECT CONCAT(ROUND(SUM(LENGTH(option_value))/1024/1024,2),'MB') as autoload_size FROM wp_options WHERE autoload='yes'"

# Post counts
echo -e "\nContent Statistics:"
wp --path="$WP_PATH" post list --post_type=post --format=count --post_status=publish | xargs -I {} echo "Published Posts: {}"
wp --path="$WP_PATH" post list --post_type=page --format=count --post_status=publish | xargs -I {} echo "Published Pages: {}"

# Plugin count
echo -e "\nActive Plugins:"
wp --path="$WP_PATH" plugin list --status=active --format=count

# Theme check
echo -e "\nActive Theme:"
wp --path="$WP_PATH" theme list --status=active --field=name

# Response time test
echo -e "\nResponse Time:"
time curl -s -o /dev/null -w "Total: %{time_total}s\n" "$SITE_URL"

# Check for updates
echo -e "\nAvailable Updates:"
wp --path="$WP_PATH" core check-update
wp --path="$WP_PATH" plugin list --update=available --format=count | xargs -I {} echo "Plugins: {}"
wp --path="$WP_PATH" theme list --update=available --format=count | xargs -I {} echo "Themes: {}"

Automated Performance Optimization

Combine techniques into a comprehensive automation script:

#!/bin/bash
# performance-optimize.sh - Complete performance optimization

set -euo pipefail

WP_PATH="/var/www/html"
LOG_FILE="/var/log/wp-performance-$(date +%Y%m%d).log"

log() {
    echo "[$(date '+%Y-%m-%d %H:%M:%S')] $1" | tee -a "$LOG_FILE"
}

log "Starting performance optimization"

# Backup first
log "Creating backup"
wp --path="$WP_PATH" db export "backup-$(date +%Y%m%d-%H%M%S).sql"

# Database optimization
log "Optimizing database"
wp --path="$WP_PATH" db optimize
wp --path="$WP_PATH" transient delete --expired

# Clear caches
log "Clearing caches"
wp --path="$WP_PATH" cache flush

# Update everything
log "Checking for updates"
wp --path="$WP_PATH" core update --minor
wp --path="$WP_PATH" plugin update --all --exclude=custom-plugin
wp --path="$WP_PATH" theme update --all

# Regenerate missing thumbnails
log "Regenerating missing thumbnails"
wp --path="$WP_PATH" media regenerate --only-missing --yes

# Performance metrics
log "Collecting performance metrics"
DB_SIZE=$(wp --path="$WP_PATH" db size --human-readable --format=json | jq -r '.Size')
log "Database size: $DB_SIZE"

log "Performance optimization completed"

Related Links

• WP-CLI Performance Commands
• WordPress Performance Best Practices
• Database Optimization Guide
• WordPress Caching Strategies
• Query Monitor Plugin

The post Optimize WordPress Performance with WP-CLI: 15 Proven Techniques appeared first on WP-CLI Mastery.