wpmovejs

TypeScript/Node.js CLI to move/sync WordPress between environments. Inspired by the Ruby tool "wordmove" with a modern, explicit UX.

Requirements

• Node.js 18+
• rsync
• ssh
• wp-cli on local, and on remotes for remote DB operations

Install

• Primary (npmjs.com):
  • npm i -g @adarok/wpmovejs
  • Package: https://www.npmjs.com/package/@adarok/wpmovejs
• Project-local:
  • npm i -D @adarok/wpmovejs
  • npx wpmovejs --help

Quick Start

# 1) Create a comprehensive config
wpmovejs init
# Overwrite if it already exists
wpmovejs init --force

# 2) Edit wpmove.yml for your envs (local, staging, production)

# OR: Sniff a remote server to auto-populate an environment
wpmovejs sniff -e staging -s [email protected] -p /var/www/html

# With custom SSH port
wpmovejs sniff -e production -s [email protected] -p /home/admin/public_html --port 2222

# 3) Check your setup
wpmovejs doctor --environment local

# 4) See configured environments
wpmovejs list

# 5) Push db + uploads to remote
wpmovejs push -e production --only db,uploads

# 6) Pull db + uploads from remote
wpmovejs pull -e production --only db,uploads

# 7) Push specific plugins only
wpmovejs push -e production -p --items gdpr-cookie-compliance,contact-form-7

# 8) Pull specific theme only
wpmovejs pull -e staging -t --items twentytwentyfour

# Tip: preview changes without touching DB/hooks
wpmovejs push -e production --all --dry-run

Configuration: wpmove.yml

Run wpmovejs init to generate a full, commented template. Key fields:

• wordpress_path: WordPress root path (must be absolute, e.g., /var/www/html). If omitted, uses current working directory.
• wp_cli: Command/binary to run wp-cli.
• ssh: Remote connection (host, user, port, path).
• db: Database credentials (host, name, user, password, charset).
• urls: One or more site URLs for search-replace; pairs map by index.
• exclude: Always-ignored patterns for file sync (applies both directions).
• sync: rsync tuning (excludes, includes, delete).
• paths: Override common paths if your layout is non-standard.
• hooks: Pre/post commands for push and pull (local/remote).
• forbid: Block specific push/pull operations per environment (safety measure).

Example (trimmed):

local:
  wordpress_path: /var/www/html
  wp_cli: wp
  db:
    host: 127.0.0.1
    name: wordpress
    user: root
    password: ''
    charset: utf8mb4
  urls: [http://localhost]
  exclude: [.git/]
  sync:
    excludes: [wp-content/cache/]
    includes: []
    delete: false
  paths:
    wp_content: wp-content
    wp_config: wp-config.php
  hooks:
    push:
      before:
        local: [echo "Backing up local before push"]
      after:
        remote: [wp cache flush]

production:
  ssh:
    host: example.com
    user: deploy
    port: 22
    path: /var/www/html
  wp_cli: wp
  db:
    host: 127.0.0.1
    name: wordpress
    user: wp
    password: secret
  urls: [https://example.com]
  exclude: [.well-known/acme-challenge/]
  sync:
    excludes: [wp-content/cache/]
    includes: []
    delete: false

Commands

• init: Create a comprehensive wpmove.yml template.
• doctor --environment <env>: Verify prerequisites and validate config.
• list: Show configured environments and their targets.
• sniff -e <env> -s <user@host> -p <path> [--port <number>]: Connect to a remote server, read wp-config.php, and automatically create a new environment in wpmove.yml. Exits with an error if the environment already exists.
• browse [-e <env>]: Open the first URL from env.urls in your default browser. macOS uses open, Windows uses start, Linux tries xdg-open then fallbacks.
• push -e <env>: Push db/files from local to <env>.
• pull -e <env>: Pull db/files from <env> to local.
• ssh -e <env> [cmd...]: Open interactive SSH or run a remote command (cd to ssh.path by default; --no-cd to disable).
• shell -e <env>: Open wp shell locally/remotely (respects wordpress_path/ssh.path; supports --local, --no-cd).
• db shell|cli -e <env> [args...]: Open DB client via wp db cli locally/remotely (supports --local, --no-cd).
• wp -e <env> [args...]: Run any wp-cli command in env context (flags passed through; --path injected automatically).

Global:

• -v/--verbose: Print executed commands.

Push/Pull targets:

• Flags: -w/--wordpress, -u/--uploads, -t/--themes, -p/--plugins, -m/--mu-plugins, -l/--languages, -d/--db, --all.
• --only <targets>: Comma-separated alternative (e.g., --only db,uploads).
• --items <names>: Comma-separated list of specific plugin or theme names to sync (use with -p/-t).
  • Example: wpmovejs push -e staging -p --items akismet,jetpack (sync only those two plugins)
  • Example: wpmovejs pull -e production -t --items twentytwentyfour (sync only that theme)
• --dry-run: Preview file ops; DB and hooks are skipped entirely.

Forbid Configuration

The forbid option allows you to block specific push/pull operations per environment. This is a safety measure to prevent accidental overwrites, especially useful for production environments.

production:
  forbid:
    push:
      db: true         # Prevent pushing database to production
      uploads: true    # Prevent pushing uploads to production
    pull:
      db: false        # Allow pulling database from production

Available targets: db, wordpress, plugins, themes, uploads, mu_plugins, languages.

When a forbidden operation is attempted, wpmovejs will display a warning and skip that target:

[warn] Push of 'db' is forbidden by production environment configuration

Hooks

Hooks let you run shell commands before and after push or pull operations. Commands can run locally or on the remote server.

local:
  hooks:
    push:
      before:
        local:
          - echo "Starting push from local"
          - wp db export backup.sql
      after:
        local:
          - rm backup.sql
    pull:
      before:
        local:
          - wp db export pre-pull-backup.sql
      after:
        local:
          - wp cache flush

production:
  hooks:
    push:
      after:
        remote:
          - wp cache flush
          - wp rewrite flush
    pull:
      before:
        remote:
          - wp db export /tmp/backup-before-pull.sql

Hook execution order:

1. local.hooks.<op>.before — local commands
2. remote.hooks.<op>.before — remote commands (via SSH)
3. file/database sync happens
4. local.hooks.<op>.after — local commands
5. remote.hooks.<op>.after — remote commands (via SSH)

Key behaviors:

• Remote commands automatically cd to ssh.path before executing
• Commands run via sh -lc (login shell) for proper environment/PATH
• Hooks are skipped entirely during --dry-run
• Use -v/--verbose to see hook commands as they execute

Common use cases:

• Backup database before sync: wp db export backup.sql
• Flush caches after sync: wp cache flush
• Clear object cache: wp cache flush
• Rebuild permalinks: wp rewrite flush
• Run deployment scripts: ./deploy.sh
• Notify services: curl -X POST https://hooks.slack.com/...

File Sync Behavior

• Root-based rsync from WordPress root with include/exclude filters.
• Environment excludes applied both ways: final = local.exclude ∪ remote.exclude ∪ destination.sync.excludes.
• WordPress core target excludes wp-content/* (so core only) and /wp-config.php by default.
• Use sync.includes to surface specific paths when needed.

Database Sync Behavior

• Export → transfer → import → wp search-replace pairs → cleanup temp files.
• URL pairs map by index; if lengths differ, remaining entries reuse the first value.
• Dry-run skips all DB work and hooks (only previews file changes).

Utilities

SSH:

• wpmovejs ssh -e production
• wpmovejs ssh -e production --no-cd
• wpmovejs ssh -e production wp core version --allow-root

Shells:

• wpmovejs shell -e local
• wpmovejs db shell -e production -- --pager=less -A

wp-cli passthrough:

• wpmovejs wp -e staging plugin list --format=json
• wpmovejs wp -e staging search-replace https://staging.example.com https://example.com --skip-columns=guid --all-tables

Browse:

• wpmovejs browse (uses local environment by default)
• wpmovejs browse -e production
  • Requires at least one URL defined in env.urls.

Tips

• Use --dry-run first to validate filters before syncing files.
• Keep urls accurate to avoid broken serialized data.
• Add sensitive files (like wp-config.php, .env) to exclude to be extra safe.
• .env is auto-loaded; use --verbose for troubleshooting.
• SSH config precedence: if you do not set ssh.port in wpmove.yml, wpmovejs defers to your ~/.ssh/config Host settings (including Port, IdentityFile, ProxyJump, etc.). If you set ssh.port, that explicit value is used.

Development

npm i
npm run build
node dist/cli.js --help

# During development
npm run dev

Contributions welcome.