CLI for syncing WordPress themes to remote servers.
The same workflow Shopify devs get with shopify theme dev, but for WordPress.

Install · Quick Start · Commands · Configuration · Wiki

---

The Problem

😩 The Old Way                          ✨ The WP Dev Sync Way
─────────────────────                   ─────────────────────
1. Edit theme file locally              1. Edit theme file locally
2. Open FileZilla                       2. That's it. It's already
3. Navigate to remote dir                  on your server.
4. Upload file manually
5. Refresh browser
6. Repeat 500 times a day

No more FTP clients. No more manual uploads. Save a file locally and it's on your server in seconds.

---

📦 Install

npm install -g wp-dev-sync

Other install methods

# Manual install (clone + link)
git clone https://github.com/reandimo/wp-dev-sync.git
cd wp-dev-sync && npm link

Requirements: Bash (Git Bash on Windows) + rsync (SSH) or lftp (FTP)

---

🚀 Quick Start

cd /path/to/my-wordpress-site     # 1. Go to your project

npx wp-dev-sync init                  # 2. Creates .env config file

nano .env                         # 3. Set your server credentials

npx wp-dev-sync setup                 # 4. Verify everything works

npx wp-dev-sync watch                 # 5. Start syncing! 🎉

That's it. Every file you save now appears on your server automatically.

---

📋 Commands

╭──────────────────────────────────────────────────────╮
│                                                      │
│   ⟳  watch     Watch + auto-sync on file changes    │
│   ↑  push      One-time upload to remote             │
│   ↓  pull      One-time download from remote         │
│   ◇  diff      Compare local vs remote (dry-run)    │
│   ◈  env       Manage multiple environments          │
│   ★  tunnel    Public URL for client previews        │
│   ◆  setup     Preflight check (deps + connection)   │
│   ◇  init      Create .env from template             │
│                                                      │
╰──────────────────────────────────────────────────────╯

---

⚙️ Configuration

All config lives in a .env file in your project root:

# ── What to sync ─────────────────────────────────────
LOCAL_PATH=./wp-content/themes/my-theme        # Local dir
REMOTE_PATH=/var/www/html/wp-content/themes/my-theme  # Remote dir

# ── Connection ───────────────────────────────────────
SYNC_PROTOCOL=ssh          # ssh or ftp
REMOTE_USER=deploy
REMOTE_HOST=myserver.com
REMOTE_PORT=22             # 22 for SSH, 21 for FTP
REMOTE_PASSWORD=           # FTP only

# ── Behavior ─────────────────────────────────────────
SYNC_EXCLUDE=.git,node_modules,.DS_Store,*.log,.env
SYNC_DELETE=false          # true = mirror exact state

.syncignore

For more control, create a .syncignore file in your project root (or run npx wp-dev-sync init). One pattern per line, like .gitignore:

# .syncignore
node_modules
vendor
.git
.env
*.log
*.map
public/hot
public/.vite
.idea
.vscode

Both .syncignore and SYNC_EXCLUDE work together — patterns from both are merged.

Example Setups

🏠 WordPress Classic (cPanel / Shared Hosting)

LOCAL_PATH=./wp-content/themes/my-theme
REMOTE_PATH=/home/user/public_html/wp-content/themes/my-theme
SYNC_PROTOCOL=ftp
REMOTE_USER=cpanel-user@domain.com
REMOTE_HOST=ftp.domain.com
REMOTE_PORT=21
REMOTE_PASSWORD=your-ftp-password

🪨 WordPress Bedrock

LOCAL_PATH=./web/app/themes/my-theme
REMOTE_PATH=/var/www/mysite/current/web/app/themes/my-theme
SYNC_PROTOCOL=ssh
REMOTE_USER=deploy
REMOTE_HOST=myserver.com
REMOTE_PORT=22

🖥️ VPS (DigitalOcean, Linode, Vultr)

LOCAL_PATH=./wp-content/themes/my-theme
REMOTE_PATH=/var/www/html/wp-content/themes/my-theme
SYNC_PROTOCOL=ssh
REMOTE_USER=root
REMOTE_HOST=203.0.113.10
REMOTE_PORT=22
SYNC_DELETE=true

⚡ WP Engine

LOCAL_PATH=./wp-content/themes/my-theme
REMOTE_PATH=/sites/mysite/wp-content/themes/my-theme
SYNC_PROTOCOL=ssh
REMOTE_USER=mysite
REMOTE_HOST=mysite.ssh.wpengine.net
REMOTE_PORT=22

🔌 Plugin Development

LOCAL_PATH=./wp-content/plugins/my-plugin
REMOTE_PATH=/var/www/html/wp-content/plugins/my-plugin
SYNC_PROTOCOL=ssh
REMOTE_USER=deploy
REMOTE_HOST=myserver.com
REMOTE_PORT=22
SYNC_EXCLUDE=.git,node_modules,tests,vendor

---

🔄 Protocols

┌──────────────────────┬──────────────────────┐
│  SSH (rsync)         │  FTP (lftp)          │
│  ══════════          │  ═════════           │
│  ✔ Delta transfer    │  ✔ Universal access  │
│  ✔ Encrypted         │  ✔ No server setup   │
│  ✔ Passwordless      │  ✔ Works everywhere  │
│  ✔ ~200 bytes/edit   │  ✘ Full file upload  │
│                      │  ✘ Unencrypted       │
│  ★ Recommended       │  ○ Fallback option   │
└──────────────────────┴──────────────────────┘

Install rsync (SSH)

choco install rsync          # Windows
brew install rsync           # macOS
sudo apt install rsync       # Linux

SSH key setup (one-time):

ssh-keygen -t ed25519
ssh-copy-id -p 22 user@myserver.com

Install lftp (FTP)

choco install lftp           # Windows
brew install lftp            # macOS
sudo apt install lftp        # Linux

---

👀 Watch Mode

npx wp-dev-sync watch starts with a smart reconciliation that compares local and remote files before syncing:

╭── info ──────────────────────────────────────────────────╮
│                                                          │
│  The files listed below differ between the local and     │
│  remote versions. What would you like to do?             │
│    ● assets/style.css                                    │
│    ● templates/page.json                                 │
│                                                          │
╰──────────────────────────────────────────────────────────╯

?  Reconciliation Strategy:
▸  Keep the local version
   Keep the remote version

Each category gets its own prompt: local-only (upload or delete), remote-only (download or delete), and differing (keep local or keep remote). Then syncs with a gradient progress bar and starts watching for changes.

┌───────────┬──────────────┬───────────┐
│ OS        │ Watcher      │ Latency   │
├───────────┼──────────────┼───────────┤
│ macOS     │ fswatch      │ ~0.5s     │
│ Linux     │ inotifywait  │ ~0.5s     │
│ Windows   │ Polling      │ ~2s       │
└───────────┴──────────────┴───────────┘

Pro tip: Pair with Vite HMR for the ultimate WordPress dev experience:

# Terminal 1                    # Terminal 2
npm run dev                     npx wp-dev-sync watch
# Vite handles CSS/JS HMR      # WP Dev Sync handles PHP uploads

---

🚇 Tunnels

Share your staging site with clients via a public URL:

# .env
TUNNEL_TOOL=cloudflared      # or: ngrok
TUNNEL_DOMAIN=staging.mysite.com

npx wp-dev-sync tunnel
# → https://random-words.trycloudflare.com

---

🔍 Diff

Compare local and remote without syncing — like git status for your server:

npx wp-dev-sync diff

  Local only (1 files) — present locally, missing on remote
    +  index.php

  Remote only (3 files) — present on remote, missing locally
    -  .editorconfig
    -  README.md
    -  setup.js

  Modified (2 files) — differ between local and remote
    ~  assets/style.css
    ~  templates/page.json

  1 local only  3 remote only  2 modified

---

🌍 Environments

Manage multiple server configs without editing .env manually:

npx wp-dev-sync env create staging        # Create from current .env
npx wp-dev-sync env create production     # Create another

# Edit each: .env.staging, .env.production

npx wp-dev-sync env switch staging        # Activate staging
npx wp-dev-sync env switch                # Interactive picker
npx wp-dev-sync env list                  # Show all environments

  ▸  staging          ssh@deploy@staging.mysite.com:/themes/my-theme
     production       ftp@user@ftp.mysite.com:/public_html/themes/my-theme

---

🔥 SYNC_DELETE

Value	What happens	Safety
false	Only uploads new/changed files. Never deletes remotely.	✅ Safe
true	Mirrors local state exactly. Remote-only files get deleted.	⚠️ Careful

---

🔧 Troubleshooting

rsync: command not found (Windows)

The CLI auto-adds Chocolatey/Scoop paths. If it still fails:

export PATH="/c/ProgramData/chocolatey/bin:$PATH"

SSH: Connection refused

• Check SSH is enabled on your server
• Try alternative ports: 2222, 7822, 18765
• SSH hostname may differ from FTP (ssh.host.com vs ftp.host.com)

FTP: Login incorrect

• Some hosts require full email as username (user@domain.com)
• Check IP whitelisting in your hosting panel
• Test with FileZilla first to isolate the issue

Sync is slow

• Switch from FTP to SSH if possible (10x faster)
• Exclude large dirs: SYNC_EXCLUDE=.git,node_modules,vendor,public/fonts
• Windows polling (2s) is normal behavior

---

🏗️ Architecture

wp-dev-sync/
├── bin/wp-dev-sync              # CLI entry point
├── lib/
│   ├── _env.sh              # .env loader + Windows PATH fix
│   ├── _ui.sh               # Terminal UI (colors, banners, spinners)
│   └── _sync.sh             # Core sync engine (rsync + lftp)
├── commands/
│   ├── watch.sh             # File watcher + auto-sync
│   ├── push.sh              # One-time upload
│   ├── pull.sh              # One-time download
│   ├── diff.sh              # Compare local vs remote
│   ├── env.sh               # Multi-environment manager
│   ├── tunnel.sh            # Cloudflare / ngrok tunnel
│   └── setup.sh             # Preflight dependency check
└── docs/                    # Full wiki documentation

---

💡 Not just WordPress

While wp-dev-sync is built for WordPress theme development, it works with any directory you need to sync remotely. Just set LOCAL_PATH and REMOTE_PATH to whatever you need.

# Sync a React app
LOCAL_PATH=./build
REMOTE_PATH=/var/www/html/myapp

# Sync a Jekyll site
LOCAL_PATH=./_site
REMOTE_PATH=/var/www/html/blog

---

📖 Full Documentation  ·  🐛 Report Bug  ·  💡 Request Feature

_{Built by Renan Diaz}