Skip to main content

Network Setup

Overview

WP-CLI can install a fresh multisite network or convert an existing single-site install into multisite. This is the fastest, most repeatable way to bootstrap network environments for agencies, SaaS products, and enterprise WordPress teams.

Understanding Multisite Setup Paths​

You typically choose one of two setup flows:

  • Fresh network install with wp core multisite-install
  • Convert existing site with wp core multisite-convert

Before running either flow, decide your URL architecture:

  • Subdirectory network: example.com/site-a/
  • Subdomain network: site-a.example.com
Decide URL Strategy Early

Switching from subdirectory to subdomain (or vice versa) later is possible but operationally expensive.

Fresh Network Installation​

Install Multisite (Subdirectory)​

# Install a new multisite network using subdirectories
wp core multisite-install \
  --url=example.com \
  --title="Example Network" \
  --admin_user=admin \
  --admin_password='strong-pass-here' \
  --admin_email=admin@example.com

Example output:

Success: Network installed. Don't forget to set up rewrite rules.

Install Multisite (Subdomain)​

# Install network where each site gets its own subdomain
wp core multisite-install \
  --url=example.com \
  --title="Example Network" \
  --admin_user=admin \
  --admin_password='strong-pass-here' \
  --admin_email=admin@example.com \
  --subdomains

Requirement: Wildcard DNS and web server config for *.example.com.

Converting Existing Single-Site to Multisite​

Convert In-Place​

# Convert current single-site installation
wp core multisite-convert --title="Converted Network"

After conversion, update the generated multisite rules in:

  • wp-config.php
  • .htaccess (or your Nginx server block)

Convert with Subdomains​

# Convert and use subdomain mode
wp core multisite-convert --title="Converted Network" --subdomains

Use this when each tenant or department needs an isolated hostname.

Pre-Flight Checks​

Confirm Site URL and Environment​

wp option get siteurl
wp core version
wp config path

Backup Before Conversion​

# Backup database
wp db export multisite-preconvert-$(date +%Y%m%d-%H%M).sql

# Backup config files
cp wp-config.php wp-config.php.bak
cp .htaccess .htaccess.bak

Post-Install Validation​

Validate Network Bootstrapping​

# List network sites
wp site list

# Confirm multisite constants are loaded
wp eval 'echo is_multisite() ? "true" : "false";'

Create and Test First Subsite​

# Create a test site
wp site create --slug=staging --title="Staging Site" --email=ops@example.com

# Verify it exists
wp site list --fields=blog_id,url --format=table

Real-World Scenarios​

Scenario 1: Agency Client Network​

wp core multisite-install \
  --url=agency.example.com \
  --title="Agency Sites" \
  --admin_user=networkadmin \
  --admin_password='replace-me' \
  --admin_email=infra@example.com \
  --subdomains

Scenario 2: University Department Sites​

wp core multisite-install \
  --url=university.example.edu \
  --title="University Network" \
  --admin_user=networkadmin \
  --admin_password='replace-me' \
  --admin_email=webteam@example.edu

Scenario 3: Convert Existing Brand Site into Network​

wp db export before-network.sql
wp core multisite-convert --title="Brand Network"

Best Practices​

1. Treat Setup as Infrastructure-as-Code​

Keep your exact install/convert commands in deployment docs or scripts.

2. Use Strong Credentials and Secret Management​

export WP_ADMIN_PASS='use-a-secret-store'
wp core multisite-install --url=example.com --title="Network" --admin_user=admin --admin_password="$WP_ADMIN_PASS" --admin_email=admin@example.com

3. Validate DNS Before --subdomains​

dig site1.example.com

4. Stage Conversion Before Production​

Run conversion in staging and test login, media uploads, and permalinks for multiple subsites.

5. Keep a Fast Rollback Plan​

Have DB and config backups ready so you can restore quickly if rewrite or domain rules break.

Troubleshooting​

Network Works but Subsites 404​

# Re-save rewrite rules from CLI context
wp rewrite flush --hard

Also verify web server rewrite config is updated for multisite.

Subdomain Sites Not Resolving​

Check wildcard DNS (*.example.com) and reverse proxy/web server host routing.

Admin Login Redirect Loops​

# Verify core network URL options
wp option get siteurl
wp option get home

Mismatched URLs or proxy SSL settings are common causes.

Quick Reference​

Essential Commands​

# Fresh install
wp core multisite-install --url=<domain> --title="<title>" --admin_user=<user> --admin_password='<pass>' --admin_email=<email>
wp core multisite-install --url=<domain> --title="<title>" --admin_user=<user> --admin_password='<pass>' --admin_email=<email> --subdomains

# Convert existing site
wp core multisite-convert --title="<network title>"
wp core multisite-convert --title="<network title>" --subdomains

# Verify
wp site list
wp eval 'echo is_multisite() ? "true" : "false";'

Comparison: Setup Approaches​

ApproachCommandBest Use Case
Fresh Installwp core multisite-installNew platforms and clean environments
In-Place Convertwp core multisite-convertExisting site expanding into network
Subdirectory Modeno --subdomainsShared brand/domain structure
Subdomain Mode--subdomainsTenant-style site isolation
Key Takeaway

Use multisite-install for new builds, multisite-convert for existing sites, and lock your URL mode before production launch.

Next Steps​