# Disembark: instructions for AI agents

Disembark is a free, open-source (MIT) WordPress plugin that moves a WordPress site from one host to another. The destination pulls files and database straight from the source, server to server. It saves a rollback point first, remaps the table prefix and rewrites every old URL (including inside serialized data, JSON and page-builder CSS).

You are probably here because a person asked you to migrate or copy a WordPress site with Disembark. This page tells you how to do it from a terminal with WP-CLI, unattended, and how to undo it.

- Plugin: https://github.com/DisembarkHost/disembark (download: https://github.com/DisembarkHost/disembark/releases/latest/download/disembark.zip)
- CLI (optional, for very large sites or backups to a local machine): https://github.com/DisembarkHost/disembark-cli
- Website: https://disembark.host

## What you need

1. **SSH to the destination** (the new host) with WP-CLI available. Every command below runs there unless it says otherwise.
2. **The source's connect line**, which looks like `disembark connect https://old-site.com <token>`. Get it one of two ways:
   - The person copies it from the source's wp-admin: Tools → Disembark → Settings. (The "Hand it to an AI agent" card there contains it.)
   - If you also have SSH to the source, install Disembark there (step 1 below) and run `wp disembark connect-line`.
3. **Disembark 3.0 or newer on the destination.** Check with `wp disembark pull --help`. If that command doesn't exist, update the plugin (step 1).

Treat the token like a password. It grants full read access to the source's files and database. Don't paste it anywhere public or into commit messages, logs you share, or issue trackers.

## Before you change anything

A pull **replaces the destination**: its files, its database, and its user accounts become the source's. Confirm with the person, in plain words, which site is the source and which is the destination before you run the pull. If the destination has content worth keeping, stop and ask.

## Move a site (server to server)

```bash
# 1. Install or update Disembark on the destination (repeat on the source if you have SSH there)
wp plugin install https://github.com/DisembarkHost/disembark/releases/latest/download/disembark.zip --activate --force

# 2. Pull the source into the destination
wp disembark pull https://old-site.com <token> --yes --format=json
#    or paste the whole connect line:
wp disembark pull disembark connect https://old-site.com <token> --yes --format=json
```

With `--format=json`, progress goes to stderr and one JSON object goes to stdout when the command finishes:

```json
{
  "ok": true,
  "source": "https://old-site.com",
  "destination": "https://new-site.com",
  "rollback_id": "62bcb2c4539c63e4d8c82629",
  "undo": "wp disembark rollback 62bcb2c4539c63e4d8c82629",
  "files_deployed": 48213,
  "host_files_kept": ["wp-content/mu-plugins/kinsta-mu-plugins", "wp-content/object-cache.php"],
  "statements": 61842,
  "converted": { "utf8mb4_0900_ai_ci → utf8mb4_unicode_520_ci": 48 },
  "prefix": { "from": "wp_", "to": "wp_a1b2_" },
  "paths": { "/home/old/public_html/": "/www/newsite_123/public/" },
  "urls": { "from": "https://old-site.com", "to": "https://new-site.com", "cells_changed": 1284, "files_rewritten": 3 },
  "code_mentions": ["wp-content/themes/custom/functions.php"],
  "multisite_constants": ["define( 'MULTISITE', true );", "..."],
  "left_out": { "files": 1204, "bytes": 3221225472, "paths": ["wp-content/cache", "old-backup.zip"], "names": ["error_log"], "empty_tables": ["wp_wfhits", "wp_actionscheduler_logs"] },
  "loaders_disabled": [".user.ini: /home/old/public_html/wordfence-waf.php"],
  "caches_cleared": ["WP Rocket", "Kinsta"],
  "plugins_turned_off": ["simple-cloudflare-turnstile/simple-cloudflare-turnstile.php"],
  "login_url": "https://new-site.com/secret-door/",
  "checks": [{ "level": "warn", "id": "plugin_downgrades", "title": "Older plugin versions will replace newer ones" }],
  "verify": { "ok": false, "problems": 1, "rows": { "checked": 48, "mismatched": [] }, "pages": [{ "label": "Home page", "url": "https://new-site.com/", "status": 500, "ms": 412, "problem": "Answers 500: a PHP error in plugin old-cache-plugin" }], "culprits": [], "leftovers": { "rows": 0, "tables": [] } },
  "quiet_mode": { "on": true, "off": "wp disembark quiet-mode off" },
  "note": "User accounts are now the source's: log in with the source site's credentials."
}
```

`checks`, `verify`, `converted`, `definers_removed`, `prefix`, `paths`, `urls`, `code_mentions`, `multisite_constants`, `catch_up`, `left_out`, `files_removed`, `loaders_disabled`, `caches_cleared`, `plugins_turned_off`, `login_url` and `quiet_mode` appear only when they apply. When `login_url` is present, a plugin moved the login page: give the person that address, since `wp-login.php` won't work. `plugins_turned_off` lists login captchas (on a quiet copy at a new address) and force-SSL plugins (on a copy served over `http://`) that would have locked the person out; tell them to turn those back on once the site has its own captcha keys or certificate. A failure exits 1 and prints `{"ok": false, "step": "...", "error": "...", "rollback_id": "...", "undo": "...", "resume": "..."}`. When `undo` is present, the destination may be partly changed. Tell the person and offer to run it. A failed database import leaves the destination's database as it was (the import builds copies of the tables and swaps them in only when every statement succeeds); the error says so. When `resume` is present, the pull can carry on where it stopped (see below).

Runtime: the pull runs in one process with no time limit, and a large site can take a long time (it's bound by the source's disk and both hosts' network). Run it with a generous timeout or in the background (`nohup wp disembark pull … > pull.log 2>&1 &`), and don't run two pulls into the same site at once.

### If a pull stops

Every step is recorded, so a pull that stops (a dropped SSH session, a killed process, an error) can carry on where it stopped.

```bash
wp disembark unfinished                      # what stopped, how far it got, how to resume it
wp disembark pull --resume=latest --yes --format=json
wp disembark discard <id> --yes              # or throw it away (rolls back first if it got that far)
```

Resuming uses the options the pull started with; finished steps are replayed in seconds.

A step that keeps failing (429, 502, 503 or 504 answers, or a dropped connection) gives up after 20 tries again or 15 minutes of failures in a row, and the JSON includes `resume`. `--max-retries=<n>` and `--max-retry-minutes=<n>` change the limits, and 0 lifts one. For a long run nobody watches, pass `--max-retries=0 --max-retry-minutes=0` to keep trying. `restore`, `rollback`, `discard` and `search-replace` take the same two options.

A pull started in wp-admin can only be resumed in wp-admin (Tools → Disembark → Move lists it with Resume). `wp disembark pull --resume` refuses it, but `wp disembark discard <id>` throws it away from either side.

### Catch-up pulls (the final pull before a switch-over)

After a pull, the destination remembers the source's files. `--catch-up` copies only files new or changed since then, removes files the last pull brought that are gone from the source (backed up in the rollback point), and copies the database again in full. For a move to a new host: do a full pull, let the person check the copy, then have them freeze the source (maintenance mode, or at least paused orders and comments) and run `wp disembark pull <connect line> --catch-up --yes --format=json` just before switching DNS. `catch_up` in the JSON says how many files changed and were removed.

#### Checks before the move

After "What to bring" and before any file is copied, the pull checks that the move can finish: free disk space (the files and database still to download, the rollback point, and a second copy of the incoming tables), that the database user can create, rename and drop tables, table names that would pass 64 characters with this site's prefix, table-name case on servers that store names in lower case, and read-only folders. It also warns about older plugin versions replacing newer ones, a PHP or WordPress version going backwards, low PHP memory and hosts that keep code read-only. They're printed and listed under `checks` in the JSON. A blocking one stops the pull before anything changes (`step: "checks"`): tell the person, and resume with `--skip-checks` only if they want to go ahead anyway.

### One site of a network or WP Freighter install

When the source is a multisite network or a WP Freighter install, a pull can bring just one of its sites, as a standalone site. Pulling a subsite's (or a mapped tenant's) own address does this by itself. From the install's main address, a pull without `--site` stops before copying anything and lists the sites with their IDs; run it again with `--site=<blog ID, tenant ID, main, or the site's address>`. A whole install isn't moved as one: that's refused before anything changes. `site` in the JSON says which site came (with its prefix). Archived subsites can be pulled the same way, and so can sites of old networks that started as WordPress MU (the `blogs.dir` layout). Only that site's tables come over:
- **Users:** a network subsite brings its members, the authors of its posts, and the network's super admins with no role on it, who arrive as administrators (`--no-super-admins` leaves those out).
- **Network-wide tables:** they come across empty (`--shared-tables` brings their rows).
- **Uploads:** they move to `wp-content/uploads`, from `uploads/sites/<id>` or `blogs.dir/<id>/files`, and their old addresses are rewritten.
- **Plugins and themes:** only the ones the site uses come along. Network-activated plugins arrive active, except ones whose header says `Network: true`, which stay inactive.
- **Refreshing it later:** run the same pull with `--catch-up`; pasting the install's connect line again finds the earlier pull of that site.

The import into this site is an ordinary pull from there on. A Freighter tenant without its own domain only answers at the main address, so it has to be pulled from the main site's connect line with `--site`.

### Into a network or a WP Freighter install

When the site you run the pull on is the main site of a multisite network or a WP Freighter install, `--into=new` brings the source in as a new subsite or tenant, and `--into=<id>` replaces that subsite or tenant. Without `--into`, the pull replaces the main site itself, so ask the person which they want. On a network the network keeps its users either way: the incoming site's users join them, matched by email, never as super admins. For a new site:
- **Address:** `--slug` names a new subsite's path or subdomain, and `--domain` a new tenant's domain when Freighter's domain mapping is on. Both default to the source's.

What happens to the incoming site:
- **Its own data:** its tables and uploads stay its own.
- **Plugins and themes:** they're only added to the shared folders, never replacing ones other sites run; `shared_kept` lists the ones kept.
- **Users (network only):** they join the network's, matched by email (`users` in the JSON).
- **Quiet mode:** it stays off.

`into` in the JSON gives the new site's ID, prefix and address. Rolling back removes a new site completely.

### Notifications

`--notify=you@example.com` (or an https:// Slack, Discord or other webhook URL; comma-separate several) sends a message when the pull finishes or stops, even from a copy in quiet mode. Useful for long pulls running in the background.

## What the pull does

1. Checks the destination (table prefix, home URL).
2. Copies the source's files and database into a staging folder, in batches.
3. Reads what it staged.
4. Saves a rollback point (a full database snapshot, plus a copy of every file it overwrites), then turns on quiet mode when the source has a different address (see below).
5. Puts the files in place.
6. Imports the database and remaps the table prefix if the two sites differ.
7. Rewrites the source's address to the destination's, in the database and in text files under uploads.
8. Cleans up the staging folder, flushes rewrite rules and the object cache.

### What gets left behind

By default the pull leaves behind what a move usually doesn't need, when the source has it: archives and database dumps in the site root, page and asset caches, PHP error logs, Wordfence's firewall files (`wordfence-waf.php`, `wp-content/wflogs`), and the rows of log tables (WooCommerce and Action Scheduler logs, email logs, redirect and 404 logs, Wordfence traffic and scan data, other security plugin logs). Those tables still come across, empty. The text output lists what was left behind and what else could be (activity logs, visitor statistics, WooCommerce shopping sessions, image-optimizer originals); the JSON has `left_out`.

- `--skip=wp-content/uploads/2014,wp-content/big.csv` leaves out more folders or files (relative to the web root).
- `--skip-rows=wp_woocommerce_sessions` brings more tables empty.
- `--template=<name>` starts from a template saved in the dashboard instead of the defaults.
- `--bring-everything` leaves nothing behind. Use it when the person wants an exact copy, logs included.

A firewall loader (`auto_prepend_file` in `.user.ini`, `php.ini` or `.htaccess`) pointing at a file that isn't on the destination is commented out after the files are placed, and listed in `loaders_disabled`. If the person uses Wordfence, tell them to re-run its firewall optimization on the new host.

### What the destination keeps

- Its own `wp-config.php` (database credentials, salts, constants).
- Its own copy of Disembark.
- Its host setup: mu-plugins it already has, mu-plugins that belong to a hosting platform (WP Engine, Kinsta, GoDaddy, Pantheon, WordPress.com, Bluehost and others), and the `object-cache.php`, `advanced-cache.php` and `db.php` drop-ins. These are listed in `host_files_kept`. Add `--bring-host-files` only if the person asks for the source's versions.

The source's own custom mu-plugins, themes, plugins, uploads and root files (`robots.txt`, `.htaccess`, …) do come across, as does WordPress core from the source.

### Quiet mode

When the source and destination addresses differ, the pull turns on **quiet mode** before anything arrives, so the copy can't act like the live site: emails are held (not sent), WP-Cron and Action Scheduler are paused, WooCommerce checkout is closed and its webhooks paused, calls to live payment, marketing, shipping-label and email APIs are blocked, and search engines are discouraged. This matters most for stores: without it, the copy would run the source's queued jobs (customer emails, catalog syncs) a second time.

- **It stands down by itself** once the site's address changes (for example a search & replace to the final domain at go-live). Until then it stays on.
- **Lift it** when the person says the destination is now the live site: `wp disembark quiet-mode off`. Check it with `wp disembark quiet-mode`; `wp disembark quiet-mode emails` lists what was held.
- **Skip it** with `--skip-quiet-mode` only when the person wants the destination fully live straight away.
- Tell the person it's on. A site that "doesn't send emails" or "won't take orders" right after a move is almost always this.

## After the pull

The pull checks its own result as its last step and reports it under `verify` in the JSON:

- `rows`: every imported table counted against the row count the source exported (`mismatched` lists any that differ; `null` when the source runs an older Disembark).
- `pages`: the home page, the login page, the newest post of each public post type and an archive of each taxonomy, loaded over HTTP. A `problem` is a PHP error (named after the plugin or theme behind it when the page or error log says), a 404, or a redirect off the site. `old_address` counts mentions of the old address in that page's HTML.
- `leftovers`: database rows that still mention the old address, per table. A table without a primary key can't be rewritten and shows up here.

Report `verify.ok`, and every problem, to the person. Run the checks again any time with `wp disembark verify [<id>] [--format=json]` (for example after deactivating a plugin that broke pages). Also confirm:

```bash
wp option get home && wp option get siteurl
wp plugin list --status=active
```

Then:

- **Log in:** user accounts are now the source's, so the person logs in with the source site's credentials. `wp user list --role=administrator` shows who can.
- **`multisite_constants`:** the source is a multisite network. Add those `define()` lines to the destination's `wp-config.php` above "That's all, stop editing!", then check `wp site list`.
- **`code_mentions`:** theme or plugin files that still contain the old address. Disembark never edits code. List them for the person.
- **Address:** the pull rewrote the source's address to the destination's current `home` URL. If the person wants a different final domain (say the old domain once DNS moves), preview and run a replace (this saves a rollback point first):

```bash
wp disembark search-replace https://new-site.example https://www.final-domain.com --dry-run
wp disembark search-replace https://new-site.example https://www.final-domain.com --yes --format=json
```

  Quiet mode stands down on its own after that replace, since the address changed. Confirm with `wp disembark quiet-mode`.

## Undo

```bash
wp disembark restore-points                 # list them (--format=json for parsing)
wp disembark rollback latest --yes          # or a specific id from the list
wp disembark rollback <id> --database-only --yes   # put back the database, leave the files as they are
wp disembark rollback <id> --only --yes     # undo that one point alone, leaving later moves in place
```

A rollback replaces the database with the snapshot and puts back the files the pull changed. Anything changed since is lost.

Rolling back to a point undoes every later restore point first, newest first, so the site ends up as it was when that point was saved. The command prints those later points before it asks. A rollback moves a point's saved files back into place, so they go back once: `restore-points` shows `put back` in its files column afterwards, and a later rollback to that point restores its database only. On a standalone site, visitors see WordPress's maintenance page while the rollback runs; WP-CLI carries on. On a multisite network, each site lists only its own restore points: run the rollback with `--url=<that site>`.

## Clean up (only once the person confirms the move is good)

```bash
wp disembark delete-restore-point all --yes   # on the destination: removes the snapshots from uploads/disembark
wp disembark token --generate                 # on the source: invalidates the token you were given
```

If the person wants Disembark gone afterwards: `wp plugin deactivate disembark && wp plugin delete disembark`. Deleting it removes its settings, the site token, its cached update check and its scheduled clean-up (on every site of a network). Two things stay on purpose: `wp-content/uploads/disembark/`, so delete the restore points first or their files stay behind, and quiet mode, which runs from its own mu-plugin until `wp disembark quiet-mode off`.

## Other routes

- **No SSH on the destination:** the person can do the same pull in wp-admin: Tools → Disembark → Pull, then paste the source's connect line. It pauses on a "What to bring" screen (the same defaults, as checkboxes), has a Cancel button that cleans up, can be resumed from the same page if it stops, and offers a catch-up when the site has pulled from that source before.
- **Push instead of pull:** from the source's wp-admin, Tools → Disembark → Push sends it to a destination that runs Disembark (handy for staging to live).
- **A backup zip on the server:** `wp disembark restore <zip> --yes` restores a zip Disembark made, or another host's downloadable backup (Kinsta, WP Engine, cPanel and others: the site's files plus a `.sql` or `.sql.gz` dump). It finds the dump on its own when it's clear; otherwise it stops before changing anything and lists the dumps, and `--database=<path in zip>` names one. A zip with no dump needs `--files-only`. On a network's or WP Freighter install's main site, `--into=new --slug=<slug>` (or `--domain=<domain>`) brings it in as a new subsite or tenant.
- **Backups, or very large sites (many GB):** the Disembark CLI backs up a site to a local folder in resumable pieces and restores it into another connected site. Install it with `wget https://github.com/DisembarkHost/disembark-cli/releases/latest/download/disembark.phar && chmod +x disembark.phar`, then see `./disembark.phar help` (`connect`, `backup`, `sync`, `restore`, `restore --rollback=<id>`).

## Command reference (run on the site they act on)

| Command | What it does |
|---|---|
| `wp disembark connect-line` | Prints this site's connect line. |
| `wp disembark token [--generate]` | Prints (or replaces) this site's token. |
| `wp disembark pull <url> <token> [--yes] [--site=<id\|address\|main>] [--shared-tables] [--[no-]super-admins] [--bring-root[=<names>]] [--into=<new\|id>] [--slug=<slug>] [--domain=<domain>] [--catch-up] [--full-database] [--skip=<paths>] [--skip-rows=<tables>] [--template=<name>] [--bring-everything] [--bring-host-files] [--skip-quiet-mode] [--notify=<to>] [--max-retries=<n>] [--max-retry-minutes=<n>] [--skip-checks] [--skip-verify] [--format=json]` | Pulls another Disembark site into this one. |
| `wp disembark restore <zip> [--yes] [--database=<path>] [--files-only] [--into=<new\|id>] [--slug=<slug>] [--domain=<domain>] [--source-url=<url>] [--notify=<to>] [--skip-quiet-mode] [--format=json]` | Restores a backup zip that is on the server (Disembark's, or another host's). |
| `wp disembark pull --resume=<id\|latest> [--skip-checks] [--format=json]` | Carries on a pull that stopped. |
| `wp disembark verify [<id>] [--format=json]` | Checks a finished move again: row counts, pages, leftover old addresses. |
| `wp disembark unfinished [--format=json]` | Lists moves that stopped before finishing. |
| `wp disembark discard <id> [--yes]` | Throws away an unfinished move (rolls back first if needed). |
| `wp disembark quiet-mode [status\|on\|off\|emails] [--format=json]` | Shows, turns on or lifts quiet mode; `emails` lists held emails. |
| `wp disembark restore-points [--format=table\|json\|ids]` | Lists rollback points, newest first. |
| `wp disembark rollback <id\|latest> [--database-only] [--only] [--yes] [--format=json]` | Puts the site back to a rollback point, undoing later points first. |
| `wp disembark delete-restore-point <id\|all> [--yes]` | Deletes rollback points. |
| `wp disembark search-replace <from> <to> [--dry-run] [--tables=a,b] [--yes] [--format=json]` | Serialize- and JSON-safe replace across the database; saves a rollback point first. |

Every command runs unattended. `--yes` skips the confirmation. Without it, a command that changes the site exits with an error instead of waiting for input when there is no terminal. Exit code 0 means success and 1 means failure.

## Rules of thumb

- Confirm source and destination with the person before a pull. It overwrites the destination.
- Read the JSON, not the progress text.
- Never truncate, rotate or delete a host's log files while checking the result. Read new lines only.
- Report the `undo` command to the person after every pull and search & replace.
- Say when quiet mode is on, and lift it only when the person confirms the destination is live.
- Leave the restore points in place until the person says the move is good.

