WP-Migrate Documentation

A CLI tool for migrating WordPress sites between servers. Automatically detects SSH, SFTP, or FTP access and uses the fastest method available.

Installation

macOS & Linux

Run the installer script which automatically detects your system and downloads the correct binary:

$ curl -fsSL https://wp-migrate.dev/install.sh | bash

This installs wp-migrate to /usr/local/bin (requires sudo).

Manual Installation

Download the appropriate binary for your platform from GitHub Releases:

• wp-migrate-macos - macOS (Intel & Apple Silicon via Rosetta)
• wp-migrate-linux - Linux

Quick Start

Interactive Wizard

The easiest way to run a migration is with the interactive wizard:

$ wp-migrate

The wizard will prompt you for source and destination credentials, then run the migration automatically.

Command-Line Mode

For automation or scripted migrations, create a YAML config file and run:

$ wp-migrate --config migration.yaml

Licensing

WP-Migrate includes 3 free migrations to try the tool. After that, you'll need to purchase a license.

Activating a License

$ wp-migrate activate YOUR-LICENSE-KEY

Deactivating a License

To move your license to a new machine:

$ wp-migrate deactivate

Check License Status

$ wp-migrate status

Configuration

Create a YAML configuration file for scripted or repeatable migrations:

# migration.yaml
source:
  ftp_host: ftp.oldsite.com
  ftp_user: oldsite_user
  ftp_pass: ${SOURCE_FTP_PASS}  # Environment variable
  wp_path: /public_html

destination:
  ftp_host: ftp.newsite.com
  ftp_user: newsite_user
  ftp_pass: ${DEST_FTP_PASS}
  wp_path: /public_html
  db_host: localhost
  db_name: newsite_wp
  db_user: newsite_dbuser
  db_pass: ${DEST_DB_PASS}
  new_url: https://newsite.com

Configuration Reference

Commands

Common Flags

Pre-DNS Testing

Test your migrated site before switching DNS by adding the server_ip option to your destination config:

destination:
  # ... other settings ...
  new_url: https://newsite.com
  server_ip: 192.168.1.100  # Destination server IP

After migration completes, add an entry to your local /etc/hosts file:

192.168.1.100  newsite.com

Now you can visit https://newsite.com in your browser to test the migrated site on the new server before updating DNS.

How It Works

WP-Migrate automatically detects the best available method for each server:

1. Server Detection

When connecting to a server, WP-Migrate checks for:

• SSH access - Enables rsync file transfer and direct MySQL/WP-CLI access
• WP-CLI - Used for database operations when available
• MySQL access - Direct database export/import
• SFTP/FTPS - Secure file transfer
• FTP - Fallback file transfer method

2. File Transfer

• With SSH: Uses rsync for incremental, compressed transfers (4-10x faster)
• Without SSH: Uses FTP/SFTP with parallel transfers and retry logic

3. Database Migration

• With WP-CLI: Direct export/import using wp db export and wp db import
• Without WP-CLI: Deploys a temporary PHP agent for database operations

4. URL Replacement

WP-Migrate performs serialization-aware search-replace:

• Properly handles PHP serialized arrays (preserving string lengths)
• Replaces URLs in all database tables
• Handles both HTTP and HTTPS URLs
• Preserves theme settings, widget configurations, and plugin data

Security

PHP Agent Security

When SSH is not available, WP-Migrate deploys a temporary PHP agent for database operations. The agent includes multiple security measures:

• Randomized filename - Agent is deployed with a random 32-character filename
• Token authentication - All requests require a secure token
• Auto-expiry - Agent automatically expires after 1 hour
• Self-deletion - Agent deletes itself after cleanup command
• IP restriction - Optional IP whitelist support

Credentials

• Credentials are never logged or stored permanently
• Use environment variables in config files to avoid committing secrets
• License keys are stored locally in ~/.wp-migrate/

Recommended Practices

• Use SFTP or FTPS instead of plain FTP when possible
• Use SSH keys instead of passwords when available
• Set environment variables for passwords rather than putting them in config files
• Delete config files containing credentials after migration

Support

Need help? Here's how to get support:

• Email: support@wp-migrate.dev
• GitHub Issues: Report bugs or request features