WDG AI Dev Environment

Appearance

Connect and Sync from WP Engine ​

WP Engine ships no dedicated sync CLI. Everything runs over its SSH gateway (<install>.ssh.wpengine.net), which exposes WP-CLI and the site filesystem. wdg my-site sync wpengine streams a wp db export from the gateway, imports it locally, search-replaces URLs, and can optionally rsync uploads and plugins.

Prerequisites ​

  • ssh and rsync on your PATH (both ship with macOS; on Debian/Ubuntu install openssh-client and rsync).
  • The shared WP Engine git-deploy private key, which lives in WDG's shared 1Password vault.
  • SSH gateway access for your key in the WP Engine portal.

SSH key setup ​

The sync authenticates with the shared git-deploy key. Its default path is ~/.ssh/wdg-wpengine-gitkey. Save the key from 1Password and lock down its permissions:

bash
mkdir -p ~/.ssh
# paste the key contents into the file, then:
chmod 600 ~/.ssh/wdg-wpengine-gitkey

If you store the key somewhere else, point at it with --ssh-key=PATH.

Before doing any work the sync runs a non-interactive connectivity probe: it confirms ssh and rsync are present, the key file exists, and the gateway accepts the key and runs real tooling. The probe runs a whitelisted WP-CLI command (wp option get home) inside the install's site directory rather than a bare command like echo ok (see the troubleshooting note below for why).

Finding the install name ​

On WP Engine each environment (production, staging, development) is a separate install with its own name, so the install name is also the environment selector. The install name is the SSH gateway user and host prefix.

You can find it in the WP Engine User Portal, or let the CLI list installs for you. When you run the sync without --install, it queries the WP Engine Hosting Platform API and presents an interactive picker. The API path needs:

  • curl and jq on your PATH, and
  • API credentials exported as WPE_API_USER and WPE_API_PASSWORD. Generate them in the WP Engine User Portal under Profile -> API Access.

The API is used only for discovery; it cannot download backups or files. If the credentials are absent or the request fails, the picker falls back to a manual install-name prompt.

Sync command ​

bash
wdg my-site sync wpengine --install=NAME [--media] [--plugins] [--ssh-key=PATH] [--prod-url=DOMAIN]

Flags:

  • --install=NAME: the WP Engine install name (for example coenetorg). --site=NAME is an accepted alias. If omitted, the API picker or manual prompt resolves it.
  • --media: also rsync the uploads directory.
  • --plugins: also rsync the plugins directory. This flag is WP Engine specific. Third-party plugins are gitignored on WP Engine, so they are absent from the cloned git-deploy repo and a freshly cloned project can fatal (for example Call to undefined function get_field()) until the plugins are present.
  • --ssh-key=PATH: SSH private key for the gateway. Default ~/.ssh/wdg-wpengine-gitkey.
  • --prod-url=DOMAIN: an additional production domain to search-replace to the local URL (for example coenet.org).

Example ​

bash
wdg my-site sync wpengine --install=coenetorg --prod-url=coenet.org --media --plugins

This exports the database from the coenetorg install, imports it, replaces the live URL and coenet.org with your local URL, then rsyncs uploads and plugins.

💡 TIP

Run wdg my-site sync wpengine with no --install for interactive mode. With WPE_API_USER / WPE_API_PASSWORD set you get the API picker; otherwise you get a manual install-name prompt.

Troubleshooting

  • Probe times out / hangs. WP Engine's SSH gateway runs a restricted ForceCommand wrapper that executes real tooling (wp, git, rsync, mysql) but hangs indefinitely on commands it does not honor; on some installs a bare echo ok never returns. The connectivity probe therefore runs a whitelisted wp option get home and is wrapped in a 30-second timeout, so an unreachable or hanging gateway fails fast (the SSH ConnectTimeout only covers TCP connect and auth, not remote command execution). If the probe fails, confirm the install name is correct, the key at the configured path is the shared git-deploy key (chmod 600), and your IP or key has SSH gateway access in the WP Engine portal.
  • Empty database export. If the export comes back empty the sync aborts before importing. Confirm the install name resolves to a real WordPress install with a database.
  • Missing plugins after a clone. Because third-party plugins are gitignored on WP Engine, a cloned git-deploy repo has none of them and the site can fatal. Re-run the sync with --plugins to pull them.
  • Permission error writing media or plugins. wp-content is typically owned by www-data inside the container, so the host user may not be able to write to a bind-mounted directory. Relax permissions from inside the running container, then re-run the sync: docker exec -u 0 wdg-wp-my-site chmod -R g+rwX /var/www/html/wp-content.

Copyright © 2026 WDG