studio-cli

WordPress Development with Studio CLI

Studio CLI is a command-line tool for creating and managing local WordPress sites powered by WordPress Playground (PHP WASM). It enables full WordPress development without external dependencies — no Apache, MySQL, or Docker needed.

Prerequisites

Build the CLI before first use (from the Studio repository root):

npm run cli:build

Run commands with:

studio <command>          # If globally installed
node dist/cli/main.js <command>  # From the Studio repo

All site commands default to the current working directory via --path. Navigate to a site directory or pass --path /path/to/site explicitly.

Core Concepts

• Local Sites: WordPress instances running via PHP WASM with SQLite — no MySQL needed
• Preview Sites: Temporary sites hosted on WordPress.com for sharing with clients (30-day expiration)
• Blueprints: JSON configuration files for automated site setup (plugins, themes, settings)
• Custom Domains: Local .local domains with optional HTTPS via self-signed certificates
• WP-CLI: Full WordPress CLI integration for managing content, plugins, themes, and database

Quick Command Reference

Task	Command
Create site	studio site create --name "My Site"
Start site	studio site start
Stop site	studio site stop
List sites	studio site list
Site info	studio site status
Delete site	studio site delete [--files]
Configure	studio site set --php 8.3 --wp 6.5
Run WP-CLI	studio wp plugin list
Login	studio auth login
Create preview	studio preview create
Update preview	studio preview update <host>
List previews	studio preview list
Delete preview	studio preview delete <host>

Plugin & Theme Development

The general pattern for WordPress plugin or theme development:

1. Create a dedicated site: studio site create --name "Dev" --php 8.2 --wp latest
2. Write code in wp-content/plugins/<name>/ or wp-content/themes/<name>/
3. Activate via WP-CLI: studio wp plugin activate <name> or studio wp theme activate <name>
4. Test across PHP versions: studio site set --php 8.3
5. Optionally add a custom domain: studio site set --domain myproject.local --https

For complete scaffolding examples (plugin file headers, block theme templates, cross-version testing matrices, and WooCommerce setup), see references/workflows.md.

Sharing Preview Sites with Clients

To create a shareable preview of a local site:

# 1. Authenticate with WordPress.com (one-time)
studio auth login
# Opens browser for OAuth — paste token when prompted

# 2. Create a preview site (from the site directory)
studio preview create
# Returns URL like: https://site-abc123.wordpress.com

# 3. Share the URL with clients

# 4. After making local changes, push updates
studio preview update site-abc123.wordpress.com

# 5. List all previews
studio preview list

# 6. Clean up when done
studio preview delete site-abc123.wordpress.com

Preview sites include wp-content/ and wp-config.php. They exclude .git/ and node_modules/. Preview sites expire after 30 days.

Site Configuration

Adjust site settings without recreation:

# Change PHP version
studio site set --php 8.3

# Upgrade WordPress
studio site set --wp 6.5

# Add custom domain with HTTPS
studio site set --domain myproject.local --https

# Change site name
studio site set --name "New Name"

# Enable Xdebug (one site at a time)
studio site set --xdebug

The site automatically restarts when configuration changes require it.

Using Blueprints

Blueprints automate site setup with pre-configured plugins, themes, and settings:

# Create site from a local blueprint
studio site create --name "Blueprint Site" --blueprint ./blueprint.json

# Create site from a URL blueprint
studio site create --name "WooCommerce Dev" --blueprint https://example.com/woo-blueprint.json

Blueprint JSON follows the WordPress Playground Blueprint format. Studio automatically filters unsupported features for compatibility.

WP-CLI Integration

Run any WP-CLI command against local sites:

# Content management
studio wp post list
studio wp post create --post_title="Hello" --post_status=publish

# Plugin management
studio wp plugin install woocommerce --activate
studio wp plugin list
studio wp plugin deactivate akismet

# Theme management
studio wp theme install flavor --activate
studio wp theme list

# Database operations
studio wp db query "SELECT * FROM wp_options LIMIT 5"
studio wp search-replace 'old-domain.com' 'new-domain.com'

# User management
studio wp user list
studio wp user create editor [email protected] --role=editor

# WordPress info
studio wp core version
studio wp core update-db

# Global WP-CLI (no site context)
studio wp --studio-no-path cli info

When a site is running, WP-CLI commands execute against the live server. When stopped, a temporary PHP WASM instance handles the command.

Multi-Site Development

Manage multiple sites simultaneously:

# Create separate environments
studio site create --path ~/sites/staging --name "Staging" --wp latest
studio site create --path ~/sites/dev --name "Development" --wp 6.4

# Work with specific sites
studio wp plugin list --path ~/sites/staging
studio wp plugin list --path ~/sites/dev

# Stop all sites at once
studio site stop --all

# List all sites
studio site list

Troubleshooting

• Site won't start: Check studio site status for port conflicts. Delete and recreate if necessary.
• Preview upload fails: Verify authentication with studio auth status. Re-login if token expired (2-week validity).
• Custom domain not resolving: The CLI modifies /etc/hosts which requires elevated privileges. Check the hosts file entry.
• WP-CLI command not found: Ensure the site path is correct. Use --path flag or navigate to the site directory.

Additional Resources

Reference Files

• references/cli-commands.md — Load when specific command flags, option types, or output format details are needed beyond the quick reference table above. Contains full argument tables for every command.
• references/workflows.md — Load when building a plugin, theme, WooCommerce store, or client preview workflow from scratch. Contains full code scaffolds, blueprint JSON examples, database operations, content migration steps, and multi-environment patterns.