WordPress Migration — Local to Live

Name: WordPress Migration — Local to Live
Availability: InStock
Author: Sandeep Kelvadi

Free Verified 602 lines By Sandeep Kelvadi Marketing Automation

Description

Comprehensive workflow for migrating WordPress sites from local dev to live hosting, or syncing content between environments. Covers three migration methods — BlogVault full-site migration, manual FTP + database import, and REST API content sync for individual pages.

What This Skill Teaches Claude

Pre-migration checklist — 10-point checklist covering hosting, DNS, SSL, PHP version matching, email MX records, and content freezes
BlogVault migration — Full-site migration between hosts with URL replacement via Better Search Replace
Manual FTP + DB migration — Database import via phpMyAdmin, WPEngine mu-plugin cleanup, wp-content upload
REST API content sync — Page-level sync using Docker DB exports, WP-CLI content extraction, and browser console push
Image pipeline — Extract referenced images, check live existence, download missing, bulk upload
Template sync for block themes — REST API template push, navigation menu handling for FSE themes
Post-live verification — DNS propagation, SSL, broken image detection, analytics reconnection, cache clearing
Hosting-specific workflows — WPEngine, Kinsta, WordPress.com/Jetpack, and SiteGround specific steps

Key Capabilities

MySQL content export with newline unescaping (avoids the \n visibility bug)
WP-CLI preferred over raw MySQL for clean content extraction
Automated image audit — compares local references against live uploads
Browser-injectable JS payload for pushing content via REST API
Photon CDN cache-busting for WordPress.com hosted sites
URL replacement patterns for both full migrations and page-level syncs

Includes

SKILL.md — Full migration reference with 3 methods, checklists, and 10 gotchas learned the hard way
sync-local-to-live.sh — Automated bash script for Docker-to-live content sync with dry-run mode

What Claude Learns

→ 1. Run pre-migration checklist — verify hosting credentials, DNS, SSL, PHP version, MX records, and freeze content edits
→ 2. Choose migration method — BlogVault for full-site, manual FTP+DB for no-plugin scenarios, REST API for page-level sync
→ 3. Export page content from local Docker database using WP-CLI (preferred) or MySQL SELECT with newline unescaping
→ 4. Extract and audit referenced images — identify which exist on live, download missing from local
→ 5. Replace local URLs with live URLs in exported content
→ 6. Upload missing images to live Media Library before pushing content
→ 7. Push cleaned content via REST API using browser console with nonce authentication
→ 8. Sync block theme templates and navigation menus via REST API
→ 9. Run post-live verification — DNS propagation, SSL check, broken image scan, analytics reconnection
→ 10. Handle hosting-specific quirks — WPEngine mu-plugin cleanup, Kinsta CNAME setup, Photon CDN cache busting

Installation

Add to your Claude project:

```bash
# Copy skill files to your project
cp -r ~/.claude/skills/wp-migration/ your-project/.claude/skills/wp-migration/

# Or reference globally in ~/.claude/settings.json
```

The sync script can be run standalone:

```bash
chmod +x sync-local-to-live.sh
./sync-local-to-live.sh 
  --local-url http://localhost:8088 
  --live-url https://www.example.com 
  --db-container wp-db-1 
  --db-user wpuser --db-pass wppass --db-name wordpress 
  --page-slug my-page 
  --output-dir /tmp/wp-sync
```

Stack & Dependencies

WordPress REST API WP-CLI Docker MySQL PHP Bash BlogVault Better Search Replace

Related Skills

Frequently Asked Questions

What technologies does WordPress Migration u2014 Local to Live require?

This skill works with WordPress, REST API, WP-CLI, Docker, MySQL, PHP, Bash, BlogVault, and Better Search Replace. Make sure these are available in your project before using the skill with Claude Code.

How detailed is the WordPress Migration u2014 Local to Live skill?

WordPress Migration u2014 Local to Live contains 602 lines of structured instructions covering 10 key areas. It provides comprehensive guidance including specific implementation patterns, not just surface-level tips.

Is WordPress Migration u2014 Local to Live free to use?

Yes, WordPress Migration u2014 Local to Live is completely free. You can download the SKILL.md file or copy it to your clipboard directly from the skill page.

What will Claude Code learn from this skill?

Claude Code will gain expertise in: 1. Run pre-migration checklist u2014 verify hosting credentials, DNS, SSL, PHP version, MX records, and freeze content edits; 2. Choose migration method u2014 BlogVault for full-site, manual FTP+DB for no-plugin scenarios, REST API for page-level sync; 3. Export page content from local Docker database using WP-CLI (preferred) or MySQL SELECT with newline unescaping; and 7 more areas.

Download SKILL.md

# WordPress Migration — Local to Live

Comprehensive workflow for migrating WordPress sites from local dev to live hosting, or syncing content between environments.

## When to Use

- Migrating a full WordPress site from local (DevKinsta, Docker, LocalWP) to live hosting
- Syncing specific pages/content from local to an existing live site
- Moving a site between hosting providers
- User says "migrate", "sync to live", "push to production", "deploy site"

## Pre-Migration Checklist

Before touching anything:

1. **Hosting details** — FTP/SSH credentials, cPanel access, provider type (WPEngine, Kinsta, SiteGround, WordPress.com)
2. **Domain details** — Registrar, DNS access, current A/CNAME records
3. **Email details** — MX records, GSuite/provider info (don't break email!)
4. **PHP version** — Must match local and live (or live 1 level lower max)
5. **WordPress version** — Same or 1 level lower on live
6. **SSL** — Verify for both `domain.com` AND `www.domain.com`
7. **Freeze content** — Ask client/owner to stop editing until migration complete
8. **Fresh backup** — Take backup of BOTH local and live before starting
9. **Cache plugins** — Note which are active, may need to deactivate during migration
10. **Add `www` variant** — Ensure `www.sitename.com` is added when configuring domain

## Migration Methods

### Method 1: BlogVault (Full Site Migration)

Best for: Moving entire site between hosts.

1. Take fresh backup in BlogVault of both staging and live
2. Check PHP version matches on both environments
3. Get live site FTP details
4. Install WordPress on live (recommended: don't override existing)
5. Add "Under Construction" page (logo + message)
6. In BlogVault → select Migrate under staging site
7. Enter FTP details → Select folder → Set destination URL → Continue
8. After migration: Install **Better Search Replace** plugin
9. Replace URLs:
   - `https://oldurl.com` → `https://newurl.com`
   - `http://oldurl.com` → `https://newurl.com`

### Method 2: Manual Migration (FTP + DB)

Best for: When BlogVault fails or isn't available.

1. Download latest backup from staging/local
2. **Clean WPEngine mu-plugins** (if migrating from WPEngine):
   ```
   DELETE these files:
   wp-content/mu-plugins/wpe-wp-sign-on-plugin/
   wp-content/mu-plugins/wpe-wp-sign-on-plugin.php
   wp-content/mu-plugins/wpengine-security-auditor.php
   wp-content/advanced-cache.php
   wp-content/object-cache.php
   ```
3. Upload wp-content folder via FTP/cPanel File Manager
4. Import database via phpMyAdmin:
   - Drop all existing tables in live DB
   - Import the .sql file from backup
5. Update `siteurl` and `home` in `wp_options` table
6. Use Better Search Replace for full URL replacement

### Method 3: REST API Content Sync (Pages Only)

Best for: Syncing specific page content to an existing live site. This is what we use most often.

**Critical: Follow this exact order.**

#### Step 1: Compare Content

Always compare local vs live BEFORE making changes:

```bash
# Get local page content length
docker exec $DB_CONTAINER mysql -u$DB_USER -p$DB_PASS $DB_NAME -N -e \
  "SELECT LENGTH(post_content) FROM wp_posts WHERE post_name='$SLUG' AND post_status='publish' AND post_type='page' ORDER BY ID DESC LIMIT 1"

# Compare with live (via browser JS console on WP admin)
# fetch('/wp-json/wp/v2/pages?slug=SLUG&context=edit&_fields=content', {credentials:'same-origin', headers:{'X-WP-Nonce': nonce}})
```

#### Step 2: Export & Clean Content

```bash
# Export from local Docker DB
docker exec $DB_CONTAINER mysql -u$DB_USER -p$DB_PASS $DB_NAME -N -e \
  "SELECT post_content FROM wp_posts WHERE post_name='$SLUG' AND post_status='publish' AND post_type='page' ORDER BY ID DESC LIMIT 1" \
  > /tmp/page-content.txt

# CRITICAL: Unescape MySQL output
python3 -c "
with open('/tmp/page-content.txt', encoding='latin-1') as f:
    content = f.read()
content = content.replace('http://localhost:PORT', 'https://livesite.com')
# MySQL escapes newlines as literal \n — must decode
import json
with open('/tmp/page-payload.json', 'w') as f:
    json.dump({'content': content}, f)
"
```

**GOTCHA:** MySQL `SELECT` output escapes `\n` as literal two-character strings. If you push this directly via REST API, the page will show `\n\n\n\n` as visible text. Always unescape before pushing.

**PREFERRED METHOD — Use WP-CLI instead of MySQL:**
```bash
# Install WP-CLI in the container (if not present)
docker exec $CONTAINER bash -c "curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar && chmod +x wp-cli.phar && mv wp-cli.phar /usr/local/bin/wp"

# Export clean content — no escaping issues
docker exec $CONTAINER wp post get $(docker exec $CONTAINER wp post list --post_type=page --name=$SLUG --field=ID --allow-root 2>/dev/null) --field=post_content --allow-root > /tmp/page-content.txt
```
WP-CLI outputs raw block content with real newlines — no `\n` escaping, no `latin-1` encoding issues. This is the safest way to extract content for syncing. Only fall back to MySQL `SELECT` if WP-CLI is unavailable.

#### Step 3: Upload Images First

```bash
# Extract image URLs from content
python3 -c "
import re
with open('/tmp/page-content.txt', encoding='latin-1') as f:
    content = f.read()
urls = sorted(set(re.findall(r'http://localhost:\d+/wp-content/uploads/[^\"\s]+', content)))
for u in urls:
    print(u.split('/')[-1])
"

# Download from local
for img in $IMAGE_LIST; do
  curl -s -o "/tmp/images/$img" "http://localhost:PORT/wp-content/uploads/2026/03/$img"
done

# Check which already exist on live (skip duplicates!)
for img in $IMAGE_LIST; do
  code=$(curl -s -o /dev/null -w "%{http_code}" "https://livesite.com/wp-content/uploads/2026/03/$img")
  if [ "$code" != "200" ]; then echo "UPLOAD: $img"; fi
done
```

Upload missing images via WP Admin → Media → Add New (bulk upload via Playwright file_upload or manually).

#### Step 4: Push Content

From WP Admin browser console:
```javascript
// Get nonce
const nonceResp = await fetch('/wp-admin/admin-ajax.php?action=rest-nonce', {credentials:'same-origin'});
const nonce = await nonceResp.text();

// For large content, inject via script tag from local HTTP server
// python3 -m http.server 9876 (serve the payload file)
// Then in browser: load script that sets window.__content = payload

// Push to page
await fetch('/wp-json/wp/v2/pages/PAGE_ID', {
  method: 'POST', credentials: 'same-origin',
  headers: {'Content-Type':'application/json', 'X-WP-Nonce': nonce},
  body: JSON.stringify({content: window.__content})
});
```

#### Step 5: Verify

```javascript
// Check all pages for broken images
const pages = ['/', '/blog/', '/my-work/', '/talks/', '/photography/', '/books/', '/about/'];
for (const page of pages) {
  const resp = await fetch(page);
  const html = await resp.text();
  const imgs = html.match(/wp-content\/uploads\/[^"'\s]+\.(jpg|png|jpeg|webp)/g) || [];
  const unique = [...new Set(imgs)];
  let broken = 0;
  for (const img of unique) {
    const r = await fetch('/' + img, {method:'HEAD'});
    if (r.status >= 400) broken++;
  }
  console.log(`${page}: ${unique.length} imgs, ${broken} broken`);
}
```

## Template Sync (Block Themes)

For Twenty Twenty-Five and other block themes:

```javascript
// Push template content via REST API
await fetch('/wp-json/wp/v2/templates/twentytwentyfive//archive', {
  method: 'POST', credentials: 'same-origin',
  headers: {'Content-Type':'application/json', 'X-WP-Nonce': nonce},
  body: JSON.stringify({content: templateBlockMarkup})
});

// Reset a template to theme default
// Site Editor → Templates → Select template → Actions → Reset
```

**Navigation menus** in block themes are `wp_navigation` post type — managed via Site Editor, not Appearance → Menus. A single nav menu post is shared across header and footer.

## URL Replacement

For full migrations, use **Better Search Replace** plugin:
- Replace `https://oldurl.com` → `https://newurl.com`
- Replace `http://oldurl.com` → `https://newurl.com`
- For Kinsta: Use built-in Search & Replace tool

For REST API syncs: Replace in content string before pushing.

## WordPress Settings Sync

```bash
# Category base (remove /category/ prefix)
Settings → Permalinks → Category base → set to "."

# Site icon via REST API
POST /wp-json/wp/v2/settings with { site_icon: MEDIA_ID }

# Tagline via REST API
POST /wp-json/wp/v2/settings with { description: "new tagline" }
```

## Post-Live Checklist

### Critical (Do Immediately)
- [ ] DNS/A record propagation — check via https://dnschecker.org/
- [ ] SSL working for `domain.com` AND `www.domain.com`
- [ ] `site_url` and `home` correct in wp-options
- [ ] Uncheck "Discourage search engines" (Settings → Reading)
- [ ] Test domain with and without `www`
- [ ] Check for 302 redirects that should be 301

### Content Verification
- [ ] All pages returning 200
- [ ] All images loading (zero 404s across all pages)
- [ ] All internal links working
- [ ] Navigation menu matches local (header + footer)
- [ ] Forms working (test submission)
- [ ] Responsive check (mobile/tablet)
- [ ] No `\n` or escaped characters visible in page content

### Analytics & SEO
- [ ] Google Tag Manager connected
- [ ] Google Analytics tracking
- [ ] Google Search Console verified
- [ ] Submit sitemap.xml in Search Console
- [ ] Button/event tracking working
- [ ] Yoast SEO — add logo, company details, configure sitemap options

### Cleanup
- [ ] Delete unwanted pages (drafts, duplicates, Sample Page)
- [ ] Delete unwanted themes (keep active + one default)
- [ ] Delete unwanted/inactive plugins
- [ ] Add backup plugin (BlogVault or verify Jetpack backups)
- [ ] Clear all caches (WP Rocket, Jetpack, CDN)

### Performance
- [ ] Cache plugin configured and working
- [ ] Image optimization active (EWWW/ShortPixel)
- [ ] PHP version optimal for hosting plan (SiteGround UltraFast PHP)
- [ ] Disable Contact Form 7 refill if not needed (performance)

## Hosting-Specific Notes

### WPEngine
Delete mu-plugin files after migration:
```
wp-content/mu-plugins/wpe-wp-sign-on-plugin/
wp-content/mu-plugins/wpe-wp-sign-on-plugin.php
wp-content/mu-plugins/wpengine-security-auditor.php
wp-content/advanced-cache.php
wp-content/object-cache.php
```
Deploy from staging to live ONLY within WPEngine. If using WP Rocket, follow their staging URL cleanup guide.

### Kinsta
1. Add site/domain in Kinsta dashboard
2. Verify domain with TXT records (Kinsta provides)
3. Point domain with A record (Kinsta provides)
4. Set as primary domain
5. For Cloudflare: Add CNAME record (`Name: @` or subdomain, `Target: username.hosting.kinsta.cloud`, Proxied)
6. For www variant: Add separate CNAME (`Name: www`, same target)
7. Use Kinsta's built-in Search & Replace tool (no plugin needed)

### WordPress.com / Jetpack
- Images served via Photon CDN (`i0.wp.com`)
- Photon caches 404 responses — if images were missing before upload, add `?v=2` cache-busting parameter to image URLs
- Site Icon set via REST API: `POST /wp-json/wp/v2/settings` with `{site_icon: ID}`

### SiteGround
- PHP update available for GoGeek/Cloud plans (UltraFast PHP)
- Use their staging tools for test deployments

## Common Gotchas (Learned the Hard Way)

1. **Always compare page content before fixing images** — Local is the source of truth. Don't upload images for outdated live content.
2. **EWWW converts PNG→JPG on upload** — After upload, verify actual filenames match what the page content references. Fix with find-replace via REST API.
3. **Photon CDN caches stale 404s** — Add `?v=2` to image URLs in block content to force CDN refresh.
4. **MySQL exports escape newlines** — `\n` becomes literal two characters. Unescape before pushing to live or you'll see `\n\n\n` on the page. **Use WP-CLI `wp post get --field=post_content` instead** — it outputs clean content with no escaping issues. Only fall back to MySQL if WP-CLI is unavailable.
5. **WordPress adds `-1` to duplicate filenames** — Upload images exactly ONCE. Check what exists first.
6. **Block theme nav menus are posts** — Not classic menus. Managed via Site Editor → Navigation.
7. **REST API plugin endpoints don't work with encoded slashes** — Use WP Admin bulk actions UI instead for plugin management.
8. **Always sync content THEN images** — Not the other way around. Content determines which images are needed.
9. **MX records** — Don't touch MX records during migration unless email is also moving. Breaking email is worse than breaking the site.
10. **Fresh backup before AND after** — Take backups of both source and destination before starting. Take another backup of live after successful migration.

Description

What This Skill Teaches Claude

Key Capabilities

Includes

What Claude Learns

Installation

Stack & Dependencies

Related Skills

Lead Gen Email

Aeo Optimization

Revops

salesforce-marketing-cloud-automation

Frequently Asked Questions

AI Marketing Skills Newsletter