wp-manage

wp-manage syncs content from a remote WordPress environment to your local DDEV setup and deploys to remote servers over SSH.

ddev wp-manage <command> <env> [target]

---

Setup

1. Create an environment config

   ddev wp-manage init production

   This creates .wp-manage-environments/production.conf. Each environment gets its own file — you can have as many as you need (staging, production, etc).

2. Fill in the config

   Open the generated file and fill in all values:

   .wp-manage-environments/production.conf

   # ---- SSH ----
   REMOTE_USER="runcloud"
   REMOTE_HOST="your-server.com"
   REMOTE_SSH_PORT="22"
   
   # ---- WORDPRESS ----
   REMOTE_WP_PATH="/home/runcloud/webapps/your-app"
   UPLOADS_DIR="web/app/uploads"
   
   # ---- LOCAL ----
   LOCAL_PROJECT_PATH="~/Sites/your-project"
   
   # ---- DEPLOY ----
   GIT_BRANCH="main"
   CACHE_PLUGIN="none"

   Note

   The .wp-manage-environments/ directory is gitignored — environment configs contain server credentials and should never be committed.

---

Commands

sync

Pull content from the remote environment to your local DDEV instance.

ddev wp-manage sync <env> db        # database only
ddev wp-manage sync <env> uploads   # uploads only
ddev wp-manage sync <env> all       # database + uploads

What sync db does:

• Exports the remote database via WP-CLI, gzips it, and transfers it via rsync
• Imports it into your local DDEV instance with ddev import-db
• Cleans up temp files on both ends

What sync uploads does:

• Rsyncs wp-content/uploads/ from the remote to local
• Uses --delete so the local directory mirrors the remote exactly

Requirements: ssh, rsync, ddev, and WP-CLI on the remote server.

---

deploy

Deploy to a remote server over SSH.

ddev wp-manage deploy <env>

The default deploy sequence is:

1. git fetch origin && git reset --hard origin/<GIT_BRANCH>
2. composer install --no-dev --prefer-dist --no-interaction --optimize-autoloader (if composer.json exists)
3. npm install && npm run build (if package.json exists)
4. Cache flush (based on CACHE_PLUGIN)

Custom deploy commands

Set DEPLOY_CMDS in the config to replace the default sequence entirely:

DEPLOY_CMDS="composer install --no-dev && php artisan config:cache"

Cache plugins

Set CACHE_PLUGIN to automatically flush the cache after deployment:

Value	Plugin
none	No cache flush (default)
wp	WP Super Cache
w3tc	W3 Total Cache
wp-rocket	WP Rocket
litespeed	LiteSpeed Cache

---

plugins

Install optional plugins from the curated list.

ddev wp-manage plugins                    # interactive menu
ddev wp-manage plugins list               # list available plugins
ddev wp-manage plugins install <key>      # install by key

---

Config reference

Key	Description	Default
REMOTE_USER	SSH username	—
REMOTE_HOST	SSH hostname or IP	—
REMOTE_SSH_PORT	SSH port	22
REMOTE_WP_PATH	Absolute path to WordPress root on remote	—
UPLOADS_DIR	Uploads directory relative to REMOTE_WP_PATH	wp-content/uploads
LOCAL_PROJECT_PATH	Absolute path to local project root	—
LOCAL_TMP_DIR	Local temp directory for DB dumps	/tmp/wp-sync
REMOTE_TMP_DIR	Remote temp directory for DB dumps	/tmp/wp-sync
DB_FILENAME	Filename for the exported SQL file	db.sql
GIT_BRANCH	Branch to deploy	main
COMPOSER_BIN	Path to Composer binary	composer
NPM_BIN	Path to npm binary	npm
DEPLOY_CMDS	Custom deploy commands (replaces default sequence)	—
CACHE_PLUGIN	Cache plugin to flush after deploy	none