Skip to main content

Theme Customization with WP-CLI

Overview

While WP-CLI cannot replicate the visual Theme Customizer interface, it provides powerful commands for managing theme modifications (theme mods), scaffolding custom themes, and automating theme-related configurations.

Understanding Theme Customization in WP-CLI​

Theme customization in WordPress typically happens through the visual Customizer (Appearance → Customize). However, WP-CLI offers complementary capabilities:

  • Managing theme modifications (theme mods) programmatically
  • Scaffolding custom themes from templates
  • Exporting/importing theme settings
  • Automating theme configuration across multiple sites
Important Limitation

WP-CLI cannot provide live visual previews like the Theme Customizer. For visual design work, use wp-admin. Use WP-CLI for automation, bulk operations, and programmatic theme management.

Managing Theme Modifications (Theme Mods)​

Theme mods are settings stored in the database that control theme appearance and behavior.

View Current Theme Mods​

# Get all theme mods for the active theme
wp theme mod list

# Get a specific theme mod value
wp theme mod get header_textcolor

Set Theme Modifications​

# Set a theme mod value
wp theme mod set header_textcolor "#ff0000"

# Set background color
wp theme mod set background_color "ffffff"

# Set custom logo (requires attachment ID)
wp theme mod set custom_logo 123

Remove Theme Modifications​

# Remove a specific theme mod
wp theme mod remove header_textcolor

# Remove all theme mods (reset to defaults)
wp option delete theme_mods_twentytwentyfour
Finding Attachment IDs

To find the attachment ID for logos or images:

wp media list --fields=ID,title,file

Common Theme Mod Examples​

# First, upload the logo and get its ID
wp media import /path/to/logo.png --porcelain
# Returns: 456

# Set the logo
wp theme mod set custom_logo 456

Example 2: Configure Header Settings​

# Set header text color
wp theme mod set header_textcolor "333333"

# Hide site title
wp theme mod set header_text 0

# Show site title
wp theme mod set header_text 1

Example 3: Background Customization​

# Set background color
wp theme mod set background_color "f5f5f5"

# Set background image (requires attachment ID)
wp theme mod set background_image 789

# Set background repeat
wp theme mod set background_repeat "no-repeat"

# Set background position
wp theme mod set background_position_x "center"

Scaffolding Custom Themes​

WP-CLI can generate a starter theme structure, saving hours of manual setup.

Create a Basic Theme​

# Scaffold a new theme
wp scaffold _s my-custom-theme --theme_name="My Custom Theme" --author="Your Name"

What this creates:

  • Complete theme directory structure
  • style.css with proper headers
  • functions.php with basic setup
  • Template files (index.php, header.php, footer.php, etc.)
  • Based on Underscores (_s) starter theme

Scaffold with Advanced Options​

# Create theme with specific options
wp scaffold _s my-theme \
  --theme_name="My Theme" \
  --author="John Doe" \
  --author_uri="https://example.com" \
  --sassify \
  --activate

Options explained:

  • --theme_name - Human-readable theme name
  • --author - Theme author name
  • --author_uri - Author website URL
  • --sassify - Include Sass/SCSS support
  • --activate - Activate theme immediately after creation

Scaffold Child Theme​

# Create a child theme
wp scaffold child-theme my-child-theme --parent_theme=twentytwentyfour --theme_name="My Child Theme"

This creates:

  • Child theme directory
  • style.css with proper parent theme reference
  • functions.php that enqueues parent styles

Exporting and Importing Theme Settings​

Export Theme Mods​

# Export all theme mods to JSON
wp theme mod list --format=json > theme-mods-backup.json

# Export specific theme mods
wp option get theme_mods_twentytwentyfour --format=json > twentytwentyfour-mods.json

Import Theme Mods​

# Import theme mods from exported file
# (Requires custom script or manual application)

# Set individual mods from backup
wp theme mod set header_textcolor "$(cat backup.json | jq -r '.header_textcolor')"
Bulk Import Script

For bulk importing, create a bash script that reads your JSON export and applies each setting:

#!/bin/bash
# import-theme-mods.sh
while IFS= read -r line; do
  key=$(echo $line | jq -r '.key')
  value=$(echo $line | jq -r '.value')
  wp theme mod set "$key" "$value"
done < theme-mods.json

Working with Menus via WP-CLI​

Menus are a key part of theme customization.

List Menus​

# List all menus
wp menu list

# Get menu details
wp menu item list <menu-id>

Create and Assign Menus​

# Create a new menu
wp menu create "Main Menu"

# Assign menu to a theme location
wp menu location assign main-menu primary

# Add items to menu
wp menu item add-post main-menu 123 --title="About Us"
wp menu item add-custom main-menu "Contact" https://example.com/contact

Automating Theme Configuration​

Example: Bulk Theme Setup Script​

#!/bin/bash
# setup-theme.sh - Automate theme configuration

# Set theme mods
wp theme mod set header_textcolor "333333"
wp theme mod set background_color "ffffff"

# Upload and set logo
LOGO_ID=$(wp media import /path/to/logo.png --porcelain)
wp theme mod set custom_logo $LOGO_ID

# Create and configure menu
wp menu create "Main Navigation"
wp menu location assign main-navigation primary
wp menu item add-post main-navigation 2 --title="Home"
wp menu item add-post main-navigation 5 --title="About"

echo "Theme configuration complete!"

Multi-Site Theme Configuration​

# Apply same theme settings across all sites in a network
for site_url in $(wp site list --field=url); do
  wp theme mod set header_textcolor "333333" --url=$site_url
  wp theme mod set background_color "ffffff" --url=$site_url
  echo "Configured theme for $site_url"
done

Advanced Theme Customization​

Modify Theme Support Features​

# Check what features current theme supports
wp theme list --fields=name,version,status

# Enable/disable features (requires functions.php modification)
# WP-CLI can't directly modify theme support, but can scaffold code

Generate Custom Template Files​

# Scaffold a custom page template
wp scaffold template-part my-custom-template --theme=my-theme

# This creates: wp-content/themes/my-theme/template-parts/my-custom-template.php

Troubleshooting Theme Customization​

Reset Theme to Defaults​

# Remove all theme modifications
wp option delete theme_mods_$(wp theme list --status=active --field=name)

# Deactivate and reactivate theme
ACTIVE_THEME=$(wp theme list --status=active --field=name)
wp theme activate twentytwentyfour
wp theme activate $ACTIVE_THEME

Check for Theme Errors​

# Enable debug mode
wp config set WP_DEBUG true --raw

# Check for PHP errors in theme files
wp eval 'error_log(print_r(get_theme_mods(), true));'

# View error log
tail -f /path/to/wp-content/debug.log

Best Practices​

1. Always Backup Before Customization​

# Export current theme mods before making changes
wp theme mod list --format=json > backup-$(date +%Y%m%d).json

# Backup entire database
wp db export backup-$(date +%Y%m%d).sql

2. Use Child Themes for Customization​

# Never modify parent themes directly
wp scaffold child-theme my-child --parent_theme=twentytwentyfour
wp theme activate my-child

3. Test on Staging First​

# Clone production to staging
wp db export production.sql
# Transfer to staging
wp db import production.sql --url=staging.example.com

# Test customizations on staging
wp theme mod set header_textcolor "ff0000" --url=staging.example.com

4. Document Your Customizations​

# Create a customization log
echo "$(date): Set header color to #333333" >> theme-changes.log
wp theme mod set header_textcolor "333333"

Common Theme Mod Keys​

Different themes use different mod keys. Here are common ones:

Theme Mod KeyPurposeExample Value
custom_logoSite logoAttachment ID (e.g., 123)
header_textcolorHeader text colorHex color (e.g., "333333")
header_textShow/hide site title0 (hide) or 1 (show)
background_colorBackground colorHex color (e.g., "ffffff")
background_imageBackground imageAttachment ID
background_repeatBackground repeatrepeat, no-repeat, etc.
nav_menu_locationsMenu assignmentsArray of menu IDs
Finding Theme-Specific Mods

To discover what mods your theme uses:

wp theme mod list

Or check the theme's customizer.php or functions.php files.

Quick Reference​

Essential Commands​

# View all theme mods
wp theme mod list

# Get specific mod
wp theme mod get custom_logo

# Set mod
wp theme mod set header_textcolor "333333"

# Remove mod
wp theme mod remove header_textcolor

# Scaffold new theme
wp scaffold _s my-theme --activate

# Create child theme
wp scaffold child-theme my-child --parent_theme=twentytwentyfour

Common Workflows​

# Complete theme setup workflow
wp scaffold child-theme my-site-theme --parent_theme=twentytwentyfour
wp theme activate my-site-theme
wp theme mod set header_textcolor "333333"
LOGO_ID=$(wp media import logo.png --porcelain)
wp theme mod set custom_logo $LOGO_ID

Summary​

TaskWP-CLI CapabilityRecommended Approach
Visual Design❌ LimitedUse wp-admin Customizer
Theme Mods Management✅ Full supportUse WP-CLI for automation
Theme Scaffolding✅ ExcellentUse WP-CLI to save time
Bulk Configuration✅ ExcellentUse WP-CLI for multiple sites
Live Preview❌ Not availableUse wp-admin
Menu Management✅ Full supportUse WP-CLI for automation
Key Takeaway

WP-CLI excels at automating theme configuration and scaffolding themes, but cannot replace the visual Theme Customizer for design work. Use both tools strategically based on your needs.

Next Steps​