WP-CLI · SiteRelay handbook

Everything SiteRelay's screens do can be done from a terminal with WP-CLI. The commands run the same jobs as the screens: they show up in History, keep restore points, and can be undone from either place.

A command runs its job from start to finish in the terminal. If you stop it (or the connection to the server drops), pick it up with wp relay jobs resume <id>.

wp help relay <command> shows the same help on the server.

Command	What it does
`wp relay pull`	Copy another site into this one
`wp relay push`	Send this site to another one
`wp relay backups`	Create, list, download, restore and delete backups
`wp relay export`	Export the database to `.sql` or `.sql.gz`
`wp relay import`	Import a `.sql`/`.sql.gz`, or add a backup `.zip`
`wp relay find-replace`	Find and replace across the database
`wp relay jobs`	History: list, show, report, run again, undo, resume, cancel
`wp relay keys`	Create, list and revoke access keys
`wp relay mode`	Get or set the site mode
`wp relay subsites`	List a network's subsites

Commands that change the site ask for confirmation. Add --yes to skip the question in scripts.

On a network, add --subsite=<id or address> to choose the subsite. wp relay subsites lists them.

Options shared by several commands

Find & replace (pull, push, export, import, find-replace). One pair on the command line; more pairs in the screens.

Option	Meaning
`--find=<text>`	Text to replace
`--replace=<text>`	What to replace it with
`--regex`	`--find` is a regular expression, such as `/foo(\d+)/`
`--case-sensitive`	Match case
`--replace-guids`	Also replace in post GUIDs (leave off unless you need it)

Tables (pull, push, export, find-replace).

Option	Meaning
`--tables=<tables>`	`all` (default), `none`, or comma-separated table names
`--exclude-tables=<tables>`	Comma-separated table names to leave out

Files (pull, push).

Option	Choices
`--themes=<choice>`	`all`, `active`, `none`, `name,name` or `except:name,name`
`--plugins=<choice>`	`all`, `active`, `none`, `name,name` or `except:name,name`
`--mu-plugins=<choice>`	`all`, `none`, `name,name` or `except:name,name`
`--uploads=<choice>`	`all`, `changed`, `since:YYYY-MM-DD` or `none`
`--others=<choice>`	Other wp-content folders: `all`, `none`, `name,name` or `except:name,name`
`--exclude=<rules>`	Comma-separated rules for files to leave out, such as `*.zip,uploads/2019`. `!rule` brings one back
`--mirror`	Also move aside what only the receiving site has (kept in its restore point)
`--low-disk`	Write uploads straight into place (no restore point for uploads)
`--whole-site`	Every table and every file, mirrored: the receiving site becomes an exact copy

wp relay pull

Copies another site's database (and chosen files) into this one.

wp relay pull <connection> [--label=<label>] [--allow-insecure] [--whole-site]
  [--tables=<tables>] [--exclude-tables=<tables>] [--find=<text>] [--replace=<text>]
  [--regex] [--case-sensitive] [--replace-guids] [--themes=<choice>] [--plugins=<choice>]
  [--mu-plugins=<choice>] [--uploads=<choice>] [--others=<choice>] [--exclude=<rules>]
  [--mirror] [--low-disk] [--subsite=<subsite>] [--new-subsite=<address>]
  [--subsite-title=<title>] [--remote-subsite=<subsite>] [--dry-run] [--yes]

Option	Meaning
`<connection>`	A connection string from Access keys on the other site, or the id of a saved connection
`--label=<label>`	A name for a new connection
`--allow-insecure`	Allow plain http or a self-signed certificate (a local site, for example)
`--subsite=<subsite>`	This site is a network: the subsite the pull replaces
`--new-subsite=<address>`	This site is a network: create a subsite at this address instead
`--subsite-title=<title>`	The new subsite's title
`--remote-subsite=<subsite>`	The other site is a network: the subsite to copy from (its id or address)
`--dry-run`	Show what would happen and change nothing

Plus the shared find & replace, tables and files options.

wp relay pull "relay1.…" --whole-site --yes
wp relay pull "relay1.…" --remote-subsite=net.example.com/shop --whole-site --yes
wp relay pull "relay1.…" --tables=all --plugins=all --uploads=changed --yes

wp relay push

Sends this site's database (and chosen files) to another site.

wp relay push <connection> [--label=<label>] [--allow-insecure] [--whole-site]
  [--tables=<tables>] [--exclude-tables=<tables>] [--find=<text>] [--replace=<text>]
  [--regex] [--case-sensitive] [--replace-guids] [--themes=<choice>] [--plugins=<choice>]
  [--mu-plugins=<choice>] [--uploads=<choice>] [--others=<choice>] [--exclude=<rules>]
  [--mirror] [--low-disk] [--subsite=<subsite>] [--remote-subsite=<subsite>]
  [--remote-subsite-title=<title>] [--dry-run] [--yes]

Option	Meaning
`<connection>`	A connection string from Access keys on the other site, or the id of a saved connection
`--label=<label>`	A name for a new connection
`--allow-insecure`	Allow plain http or a self-signed certificate
`--subsite=<subsite>`	This site is a network: the subsite to send
`--remote-subsite=<subsite>`	The other site is a network: the subsite the push replaces, or `new:<address>` to create one
`--remote-subsite-title=<title>`	The title of the subsite `new:<address>` creates
`--dry-run`	Show what would happen and change nothing

Plus the shared find & replace, tables and files options.

wp relay push 6f1c…-saved-connection-id --themes=active --plugins=all --uploads=all

wp relay backups

Full copies of this site (database and files) to keep, download or restore.

Command	What it does
`wp relay backups create [--label=<label>] [--subsite=<subsite>]`	Makes a backup of the database and files
`wp relay backups list [--format=<format>]`	Lists backups. Formats: `table` (default), `json`, `csv`, `yaml`, `ids`, `count`
`wp relay backups download <id> <file> [--yes]`	Copies a backup's `.zip` to a file, as Download does. `--yes` overwrites the file without asking
`wp relay backups restore <id> [--subsite=<subsite>] [--new-subsite=<address>] [--subsite-title=<title>] [--yes]`	Restores a backup: the site's database and files become the backup's. On a network, `--subsite` is the subsite it replaces, or `--new-subsite` creates one
`wp relay backups delete <id> [--yes]`	Deletes a backup file

To restore a backup made on another site, add it first with wp relay import backup.zip. It then shows in wp relay backups list.

wp relay export

Exports this site's database to an .sql or .sql.gz file.

wp relay export <file> [--gzip] [--tables=<tables>] [--exclude-tables=<tables>]
  [--find=<text>] [--replace=<text>] [--regex] [--case-sensitive] [--replace-guids]
  [--subsite=<subsite>] [--yes]

Option	Meaning
`<file>`	Where to write it. A name ending in `.gz` is gzip-compressed
`--gzip`	Compress even without `.gz` in the name
`--yes`	Overwrite the file without asking

Find & replace here changes only the exported file, not the site.

wp relay export site.sql.gz --exclude-tables=wp_actionscheduler_logs

wp relay import

Imports a database dump (.sql or .sql.gz from SiteRelay, mysqldump or phpMyAdmin), or adds a SiteRelay backup .zip.

wp relay import <file> [--find=<text>] [--replace=<text>] [--regex] [--case-sensitive]
  [--replace-guids] [--subsite=<subsite>] [--new-subsite=<address>]
  [--subsite-title=<title>] [--yes]

The dump's WordPress tables replace this site's, and its URLs and paths become this site's. A restore point is kept. A .zip is added to Backups instead: restore it with wp relay backups restore.

On a network, --subsite is the subsite the import replaces, or --new-subsite and --subsite-title create one.

wp relay import blueprint.sql.gz --yes

wp relay find-replace

Finds and replaces text across this site's database. Serialized and JSON data stay intact.

wp relay find-replace [--find=<text>] [--replace=<text>] [--regex] [--case-sensitive]
  [--replace-guids] [--tables=<tables>] [--exclude-tables=<tables>]
  [--subsite=<subsite>] [--dry-run] [--yes]

--dry-run shows what would change, with examples, and changes nothing. It's the command-line version of the preview.

wp relay find-replace --find=http://old.test --replace=https://new.test --dry-run

wp relay jobs

SiteRelay's History.

Command	What it does
`wp relay jobs list [--type=<type>] [--status=<status>] [--page=<page>] [--format=<format>]`	Lists jobs, newest first, 20 per page
`wp relay jobs show <id> [--format=text\|json]`	Shows a job: what it did and its latest events
`wp relay jobs report <id> [--file=<path>]`	Prints the job's report (as Download report in History), or writes it to a file
`wp relay jobs rerun <id> [--yes]`	Runs an export, find & replace, pull or push again with the same settings
`wp relay jobs restore <id> [--yes]`	Undoes a job through its restore point. For a push, the undo happens on the other site
`wp relay jobs resume <id>`	Continues a job that was paused, or whose command was stopped
`wp relay jobs cancel <id> [--yes]`	Cancels an unfinished job. Temporary data is removed and live data isn't changed

--type: export, find_replace, import, pull, push, restore, backup or backup_restore.
--status: completed, failed, cancelled, running, paused, pending or abandoned.
--format (list): table (default), json, csv, yaml, ids, count.

wp relay keys

Access keys: who may pull from or push to this site.

Command	What it does
`wp relay keys create --label=<label> --permission=<pull\|push\|both> [--expires=<when>] [--one-time]`	Creates a key and prints its connection string, shown only once
`wp relay keys list [--format=<format>]`	Lists keys with their permission, status, expiry and use
`wp relay keys revoke <id> [--yes]`	Revokes a key: the other site can no longer use it

--expires: 1h, 24h, 7d, never (default), or a date and time.
--one-time: the key works for one migration.

wp relay keys create --label="Staging" --permission=pull --expires=24h

wp relay mode

The site mode: whether other sites may pull from or push to this one.

Command	What it does
`wp relay mode get [--format=<format>]`	Shows the mode, whether it's set in `wp-config.php`, and the auto-lock
`wp relay mode set <locked\|pull-only\|push-only\|open> [--auto-lock=on\|off]`	Sets the mode, and optionally Lock after an incoming push

wp relay mode set pull-only

wp relay subsites

Lists the network's subsites, with the ids and addresses --subsite takes.

wp relay subsites [--format=table|json|csv|yaml|ids|count]

Stuck? Troubleshooting explains every message SiteRelay shows, and what to send when you ask for help.

#Options shared by several commands

#wp relay pull

#wp relay push

#wp relay backups

#wp relay export

#wp relay import

#wp relay find-replace

#wp relay jobs

#wp relay keys

#wp relay mode

#wp relay subsites