https://github.com/reandimo/wp-dev-sync
Sync your local environment with your remote Wordpress
https://github.com/reandimo/wp-dev-sync
ftp ftp-sync remote sync wordpress
Last synced: 11 days ago
JSON representation
Sync your local environment with your remote Wordpress
- Host: GitHub
- URL: https://github.com/reandimo/wp-dev-sync
- Owner: reandimo
- Created: 2026-03-28T19:00:25.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-03-31T22:13:24.000Z (3 months ago)
- Last Synced: 2026-06-18T03:34:09.743Z (11 days ago)
- Topics: ftp, ftp-sync, remote, sync, wordpress
- Language: Shell
- Homepage: https://reandimo.github.io/wp-dev-sync/
- Size: 149 KB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
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
```bash
npm install -g wp-dev-sync
```
Other install methods
```bash
# 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
```bash
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:
```bash
# ── 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`:
```bash
# .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)
```bash
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
```bash
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)
```bash
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
```bash
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
```bash
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)
```bash
choco install rsync # Windows
brew install rsync # macOS
sudo apt install rsync # Linux
```
**SSH key setup (one-time):**
```bash
ssh-keygen -t ed25519
ssh-copy-id -p 22 user@myserver.com
```
Install lftp (FTP)
```bash
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:
```bash
# 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:
```bash
# .env
TUNNEL_TOOL=cloudflared # or: ngrok
TUNNEL_DOMAIN=staging.mysite.com
```
```bash
npx wp-dev-sync tunnel
# → https://random-words.trycloudflare.com
```
---
## 🔍 Diff
Compare local and remote without syncing — like `git status` for your server:
```bash
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:
```bash
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:
```bash
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.
```bash
# 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