connectlocal_
ConnectLocal/Docs/Connect to Cloudways

THE CONNECTION MANUAL

Connect to Cloudways

Connect Cloudways to Local, push and pull your site, and sync selected files.

On this page

Install the Cloudways add-on using the installation guide, then follow the setup below.

Requirements

  • Local 6 or newer. Built and tested against Local 10.1.2 on macOS.
  • A Cloudways WordPress application. Cloudways servers ship with WP-CLI and rsync.
  • For API mode: a Cloudways access token (starts with cw_) from Account → API Integration (https://platform.cloudways.com/api).
    • Pick Full Access, or Limited Access that covers servers and applications, application credentials and SSH access, SSH keys, backups, cache and operations.
    • Use a current Cloudways access token; legacy API-key availability depends on the provider.
  • For SFTP/SSH mode: the application's Application Credentials (Applications → your app → Access Details), with SSH access enabled.

Use

  1. Open a site in Local and go to Tools → Cloudways.
  2. Connect in one of two ways:
    • Cloudways API (recommended): paste your access token, pick the application (grouped by server) and click Link. The add-on then:
      • turns on SSH access for the app if it is off;
      • uses the app's credential, or creates one if none exists;
      • registers its SSH key on that credential;
      • waits for the key to work and finds the WordPress webroot.
    • SFTP/SSH credentials: enter the server IP, the app credential's username and either its password or the add-on's public key. If you use the key, add it under Application Credentials → SSH Keys in Cloudways first.
  3. Push or pull from the panel's Push to Cloudways / Pull from Cloudways tabs. Once the site is linked, you can also use the Cloudways: Pull / Push buttons in the site header.
    • Push options:
      • Files and/or Database
      • Take a Cloudways application backup first (API mode)
      • Delete files on Cloudways that aren't in Local (on by default, like WP Engine)
      • Purge Cloudways caches afterwards
    • Pull options:
      • Files and/or Database
      • Back up the Local database first
      • Delete Local files that aren't on Cloudways (on by default, like WP Engine)

Progress appears in Local's site overlay. When the transfer finishes, a banner reports success or the error.

Pull a Cloudways site into a new Local site

  1. Click + (Create a site) in Local and choose Pull from Cloudways.
  2. Pick the Cloudways app (API) or enter SFTP/SSH credentials. Name the Local site; it defaults to the app's name. The page previews the .local domain and folder, which follow your Local new-site defaults and avoid existing sites.
  3. Click Create site & pull.
    • The connection is checked first, so a wrong password or key never leaves an empty site behind.
    • Local then creates a normal site (its default PHP, MySQL and web server), the add-on links it, and pulls the files and database.

Compare & sync files (selective sync)

Go to Tools → Cloudways → Compare & sync files and click Compare with Cloudways. Nothing changes until you choose files. The result lists every differing file in three groups:

  • Different on each side: shows Local's and Cloudways' size and modification time, and which copy is newer.
  • Only in Local
  • Only on Cloudways

Filter by path, tick individual files or whole groups, then click Push selected or Pull selected. The confirmation tells you what will be uploaded, downloaded or deleted.

  • What moves: only the ticked files. The database is never touched, and Cloudways caches are purged after a selective push.
  • Deletions: a ticked file that exists only on the receiving side is deleted there, so both sides end up matching. For example, pushing a file that is only on Cloudways removes it from Cloudways.
  • How differences are found: by default, rsync compares size + modification time, which is fast. Tick Compare file contents (slower) to compare checksums. That catches edits that kept the same size and date, but it reads every file on both sides.
  • Exclusions: the push/pull exclusions below apply here too, so wp-config.php, .htaccess and cache drop-ins never show up as differences.

What a database push does

  1. Exports the Local database and rewrites MySQL 8 utf8mb4_0900_* collations to MariaDB-compatible ones.
  2. On Cloudways, saves the current database to local-backup-before-push.sql in the app's tmp/ folder (or private_html/), outside public_html and readable only by the app user. It also reads the current home URL and table_prefix.
  3. Uploads the dump outside the webroot, then runs wp db reset and wp db import. If the import fails, it restores the backup automatically. The uploaded dump is always deleted afterwards.
  4. Sets table_prefix to match Local if the two differ.
  5. Runs wp search-replace across all tables (--precise, guid skipped) for:
    • //site.local → the URL WordPress had on Cloudways;
    • the JSON-escaped form \/\/site.local, which block editors and page builders store;
    • http:// → https:// when the Cloudways site was on HTTPS.

What a database pull does

  1. On Cloudways, exports the database with --single-transaction, so the live site isn't locked. It also reads home and table_prefix.
  2. Downloads the export and deletes it from the server. Then it makes the dump importable by Local's MySQL:
    • removes the /*M!999999\- enable the sandbox mode */ line that newer MariaDB writes;
    • rewrites MariaDB 11 uca1400 collations.
  3. Saves the Local database to app/sql/local-backup-before-pull.sql (optional).
  4. Runs wp db reset and wp db import through Local's own WP-CLI service, which uses the site's PHP and MySQL. If the import fails, it restores the backup.
  5. Sets the local table_prefix to Cloudways' if the two differ.
  6. Runs search-replace (--precise, guid skipped) from the Cloudways URL to the Local URL. It also covers:
    • the app's temporary *.cloudwaysapps.com address (API mode);
    • the JSON-escaped forms;
    • fixing https://site.local back to http:// when the Local site doesn't use HTTPS.

What is never transferred

These are excluded in both directions. Excluded paths are also protected from --delete, so each side keeps its own copy. Cloudways keeps its wp-config.php and .htaccess, and Local keeps its own. Cloudways' Redis/Breeze drop-ins never reach Local, where they'd break the site.

  • Environment config: wp-config.php, .htaccess, .user.ini
  • Cache drop-ins and output: object-cache.php, advanced-cache.php, wp-content/cache/, Breeze config
  • VCS and tool binaries: .git/, node_modules/.bin, vendor/bin
  • Root-level *.sql dumps
  • Local's helper files

To skip more, add rsync patterns (one per line) to app/public/.cloudways-push-ignore or .cloudways-pull-ignore. These work like .wpe-push-ignore and .wpe-pull-ignore.

Themes and plugins symlinked from elsewhere

A theme or plugin that you develop in another folder and symlink into the Local site (for example wp-content/themes/mytheme → ~/code/mytheme) is pushed as real files, because the server has no such folder to point to. It is never pulled into: a pull leaves the symlink and the folder it points to untouched, so server copies can't overwrite or delete your working files. Symlinks within the site stay symlinks, and broken symlinks are skipped (and logged).

← Back to documentationDownload an add-on ↗