[00] Subset Sync, For developers
WP-CLI commands
Every wp subset sync command in Subset Sync and Sync Pro, with its options, defaults and examples as wp help prints them.
Subset Sync adds its commands under wp subset sync. The Pro commands, files and schedule, appear once Subset Sync Pro is active. Run wp help subset sync <command> on your site to see the same text there.
The commands used to live under wp subset migration, and before that wp migration. Both old names still work, with a warning to use wp subset sync instead, and both will be removed in Subset Sync 1.0. wp migration doesn’t include key, settings or the Pro commands.
push
Pushes this site’s database, its media library or both to a remote site.
wp subset sync push <remote> [<key>] [--media] [--media-only] [--all-media] [--delete-media] [--exclude=<patterns>] [--exclude-tables=<patterns>] [--tables=<patterns>] [--subsite=<id|url>] [--find=<values>] [--replace=<values>] [--include-transients] [--skip-spam] [--skip-revisions] [--skip-auto-drafts] [--lean] [--skip-backup] [--dry-run] [--confirm-production=<domain>] [--yes] [--verbose] [--format=<format>]
| Option | Default | What it does |
|---|---|---|
<remote> | None | A saved connection’s name (see connections), or the remote site’s URL from its connection info, with <key>. |
<key> | None | The remote site’s connection key. Leave it out when <remote> is a saved connection’s name. |
Every other option is in migration options. With a saved connection, any of the media, exclude and table options you leave out come from the options that connection remembers.
wp subset sync push Staging --media
wp subset sync push https://staging.example.com AbC123… --media
pull
Pulls a remote site’s database, its media library or both into this site. It takes the same arguments and options as push. With --delete-media, it deletes local media that doesn’t exist on the remote.
wp subset sync pull <remote> [<key>] [--media] [--media-only] [--all-media] [--delete-media] [--exclude=<patterns>] [--exclude-tables=<patterns>] [--tables=<patterns>] [--subsite=<id|url>] [--find=<values>] [--replace=<values>] [--include-transients] [--skip-spam] [--skip-revisions] [--skip-auto-drafts] [--lean] [--skip-backup] [--dry-run] [--confirm-production=<domain>] [--yes] [--verbose] [--format=<format>]
wp subset sync pull Production --media
wp subset sync pull https://example.com AbC123… --media
Migration options
These options are shared by push, pull, export and import, and restore and resume take some of them. The last column says which commands take each one.
| Option | Default | What it does | Commands |
|---|---|---|---|
--media | Off | Also transfers the media library. | push, pull |
--media-only | Off | Transfers the media library but not the database. | push, pull |
--all-media | Off | Transfers every media file, not only new and changed ones. | push, pull |
--delete-media | Off | Deletes media on the destination that doesn’t exist on the source. | push, pull |
--exclude=<patterns> | None | Comma-separated glob patterns of media files to skip. | push, pull |
--exclude-tables=<patterns> | None | Comma-separated table names or wildcard patterns to leave out, without the table prefix, such as actionscheduler_*. The destination keeps its own copy of a left-out table. Can’t be combined with --tables. | push, pull, export |
--tables=<patterns> | None | Comma-separated table names or wildcard patterns to migrate instead of every table, without the table prefix. Can’t be combined with --exclude-tables. | push, pull, export |
--subsite=<id|url> | None | Migrates one subsite of whichever side is a multisite network, by ID or URL, instead of the whole network. See below for export. | push, pull, export |
--find=<values> | None | Extra find values, separated by |. Pairs with --replace. | push, pull, export, import |
--replace=<values> | None | Extra replace values, separated by |. | push, pull, export, import |
--include-transients | Off | Migrates transients too. | push, pull, export |
--skip-spam | Off | Leaves out spam and trashed comments. | push, pull, export |
--skip-revisions | Off | Leaves out post revisions. | push, pull, export |
--skip-auto-drafts | Off | Leaves out auto-drafts. | push, pull, export |
--lean | Off | Shorthand for --skip-spam --skip-revisions --skip-auto-drafts. | push, pull, export |
--skip-backup | Off | Doesn’t back up the destination database before replacing it. | push, pull, import, restore |
--dry-run | Off | Prints the preview and exits without changing anything on either site. | push, pull |
--confirm-production=<domain> | None | Required when the site being replaced is marked as a production site: its domain, to confirm. | push, pull, import, restore |
--yes | Off | Skips the confirmation prompt. It doesn’t skip --confirm-production. | push, pull, import, restore |
--verbose | Off | In a terminal, prints every log line above the progress list, including a line for each table copied. Output to a file or pipe always has every line. | push, pull, export, import, restore, resume |
--format=<format> | table | table prints progress as it happens. json prints progress to standard error, then one JSON summary object to standard output at the end, whether the migration finished, failed or didn’t complete. | push, pull, export, import |
In a terminal, table shows a list of the job’s stages that updates in place. Finished stages are ticked with how long they took, and the running one has a progress bar, the table or file it’s on, and its speed and time left. Log lines worth reading, such as backups taken and warnings, print above the list. Piped or redirected output prints a progress line per step instead, the same as before.
The options, users and usermeta tables, and the network tables on multisite, are always migrated: --exclude-tables can’t leave them out and --tables always includes them. With --subsite on a push or pull, a subsite goes to a single site, or a single site goes to an existing subsite. Users are merged into the network by login, and other subsites aren’t touched.
diff
Compares this site’s database and media library with a remote one’s, without changing anything on either side.
wp subset sync diff <remote> [<key>] [--exclude=<patterns>] [--format=<format>]
| Option | Default | What it does |
|---|---|---|
<remote> | None | A saved connection’s name, or the remote site’s URL with <key>. |
<key> | None | The remote site’s connection key. Leave it out for a saved connection. |
--exclude=<patterns> | None | Comma-separated glob patterns of media files to leave out of the comparison. |
--format=<format> | table | table or json. |
wp subset sync diff Staging
wp subset sync diff https://staging.example.com AbC123…
export
Exports the database to a .sql.gz file. It takes the export options in migration options, plus the two below. With --subsite, it exports one subsite of this network, by ID or URL, as a plain single-site dump: only that subsite’s own tables and users, ready to import into a single site.
wp subset sync export <file> [--target-url=<url>] [--target-path=<path>] [--exclude-tables=<patterns>] [--tables=<patterns>] [--subsite=<id|url>] [--find=<values>] [--replace=<values>] [--include-transients] [--skip-spam] [--skip-revisions] [--skip-auto-drafts] [--lean] [--verbose] [--format=<format>]
| Option | Default | What it does |
|---|---|---|
<file> | None | Where to write the export. |
--target-url=<url> | None | Rewrites this site’s URL to this one in the export. |
--target-path=<path> | None | Rewrites this site’s file path to this one in the export. |
wp subset sync export ~/backup.sql.gz --target-url=https://example.test
import
Replaces this site’s database with a .sql or .sql.gz file. It takes --find, --replace, --skip-backup, --confirm-production, --yes, --verbose and --format from migration options.
wp subset sync import <file> [--find=<values>] [--replace=<values>] [--skip-backup] [--confirm-production=<domain>] [--yes] [--verbose] [--format=<format>]
| Option | Default | What it does |
|---|---|---|
<file> | None | The dump to import. |
status
Shows the current or most recently finished migration’s status without moving it on, unlike resume. It exits with 0 whether or not there’s a job, so a script can poll it.
wp subset sync status [--format=<format>]
| Option | Default | What it does |
|---|---|---|
--format=<format> | table | table or json. json prints the same progress object the admin screen polls, or null when there’s no job. |
wp subset sync status
wp subset sync status --format=json
resume
Carries on with an interrupted migration from where it stopped. It works for migrations started from WP-CLI or the admin screen.
wp subset sync resume [--verbose]
cancel
Cancels an unfinished migration and cleans up.
wp subset sync cancel
backups
Lists or deletes this site’s database backups, which are taken before a pull, an import or an incoming push. See Backups and history.
wp subset sync backups [<action>] [<name>] [--fields=<fields>] [--format=<format>] [--yes]
| Option | Default | What it does |
|---|---|---|
<action> | list | list or delete. |
<name> | None | The backup’s name, from the list. Required for delete. |
--fields=<fields> | All | Comma-separated fields to show: name, created, size, path. Only for list. |
--format=<format> | table | table, csv, json, yaml or count. Only for list. |
--yes | Off | Deletes without asking first. |
wp subset sync backups
wp subset sync backups delete backup-20261020-091500-0123456789abcdef.sql.gz --yes
restore
Restores one of this site’s backups. The current database is backed up first. It takes --skip-backup, --confirm-production, --yes and --verbose from migration options.
wp subset sync restore <name> [--skip-backup] [--confirm-production=<domain>] [--yes] [--verbose]
| Option | Default | What it does |
|---|---|---|
<name> | None | The backup’s name, from wp subset sync backups. |
history
Lists the last 50 finished migrations (push, pull, export and import), newest first, whether they started from the admin screen or WP-CLI.
wp subset sync history [--format=<format>]
| Option | Default | What it does |
|---|---|---|
--format=<format> | table | table or json. |
wp subset sync history
wp subset sync history --format=json
connection-info
Prints this site’s connection info, which another site needs to push to or pull from it.
wp subset sync connection-info [--reset]
| Option | Default | What it does |
|---|---|---|
--reset | Off | Generates a new key first. Existing connections stop working. |
connections
Saves, lists or removes named connections, so push, pull and diff can name one instead of taking a remote URL and key.
wp subset sync connections <action> [<name>] [<remote-url>] [<key>] [--format=<format>]
| Option | Default | What it does |
|---|---|---|
<action> | None | list, add, rename, rekey or remove. |
<name> | None | The connection’s name. Required for every action except list. |
<remote-url> | None | Required for add and rekey. For rename, the new name instead. |
<key> | None | Required for add and rekey. |
--format=<format> | table | table, csv, json, yaml or count. Only for list. |
wp subset sync connections list
wp subset sync connections add Staging https://staging.example.com AbC123…
wp subset sync connections rename Staging "Staging (old)"
wp subset sync connections rekey Staging https://staging.example.com XyZ789…
wp subset sync connections remove Staging
allow
Allows or refuses incoming push and pull connections. If the setting it would change is locked by the WPMIG_ALLOW_PUSH or WPMIG_ALLOW_PULL constant in wp-config.php, it’s refused and nothing changes.
wp subset sync allow [--push=<on|off>] [--pull=<on|off>]
| Option | Default | What it does |
|---|---|---|
--push=<on|off> | Unchanged | Allows other sites to push to this one. |
--pull=<on|off> | Unchanged | Allows other sites to pull from this one. |
key
key regenerate replaces this site’s connection key with a new one, the same as Settings → Reset key. Every site connected to this one stops working until it gets the new connection info, which the command prints. On each of them, rekey the saved connection with wp subset sync connections rekey, or paste the new info on its Connection tab.
wp subset sync key regenerate [--yes]
| Option | Default | What it does |
|---|---|---|
--yes | Off | Doesn’t ask for confirmation. |
wp subset sync key regenerate --yes
settings
Lists, reads and changes the on and off settings on the Settings tab: allow_push, allow_pull, verify_ssl and is_production. A setting locked by a wp-config.php constant can’t be changed here either. The connection key has its own command, key.
wp subset sync settings list [--format=<format>]
wp subset sync settings get <name>
wp subset sync settings set <name> <value>
wp subset sync settings reset [--yes]
| Subcommand | Options | What it does |
|---|---|---|
list | --format: table (default), json, csv or yaml | Lists every setting, its value and its source: default, saved or constant. |
get | None | Prints one setting’s value: true or false. |
set | None | Changes one setting. Values take true/false, on/off, yes/no or 1/0. Refused if a constant locks the setting. |
reset | --yes skips the confirmation | Puts every setting back to its default. A setting locked by a constant keeps the constant’s value, and this site’s key is kept, so connected sites keep working. |
wp subset sync settings get is_production
wp subset sync settings set is_production on
files (Pro)
Pushes and pulls themes, plugins and must-use plugins between sites. Each theme or plugin that changes is copied in full to a staging directory on the destination, and swapped in once every one is ready. Selected packages end up identical to the source’s, so files the source doesn’t have are deleted from them. See Themes and plugins.
These are left alone:
- packages only the destination has
- Subset Sync and Subset Sync Pro
- symlinks
.git,.svn,.hg,node_modulesand.DS_Store, anywhere
Plugins aren’t activated or deactivated. Which plugins are active is stored in the database, so a database migration carries it.
files push and files pull
files push sends this site’s themes and plugins to another site. The other site needs Subset Sync Pro active, with Push to this site and Accept theme and plugin files on (wp subset sync files allow --push=on there). files pull brings another site’s themes and plugins here. The other site needs Subset Sync Pro active with Pull from this site on.
wp subset sync files push <remote> [<key>] [--themes[=<slugs>]] [--plugins[=<slugs>]] [--mu-plugins[=<names>]] [--exclude=<patterns>] [--dry-run] [--confirm-production=<domain>] [--yes]
wp subset sync files pull <remote> [<key>] [--themes[=<slugs>]] [--plugins[=<slugs>]] [--mu-plugins[=<names>]] [--exclude=<patterns>] [--dry-run] [--confirm-production=<domain>] [--yes]
| Option | Default | What it does |
|---|---|---|
<remote> | None | The other site’s URL, or the name of a saved connection. |
<key> | None | The other site’s connection key, when <remote> is a URL. |
--themes[=<slugs>] | None | Every theme, or a comma-separated list of them. |
--plugins[=<slugs>] | None | Every plugin, or a comma-separated list. Single-file plugins go by file name, such as hello.php. |
--mu-plugins[=<names>] | None | Every must-use plugin, or a comma-separated list. Must-use plugins aren’t included unless you ask for them. |
--exclude=<patterns> | None | Comma-separated glob patterns neither side touches, matched against <slug>/<path> and the file name, such as *.log,my-theme/assets/src/*. |
--dry-run | Off | Shows what would change, and stops. |
--confirm-production=<domain> | None | The destination’s domain, typed out, when it’s marked as a production site. |
--yes | Off | Doesn’t ask for confirmation. |
# Every theme and plugin, to a saved connection.
wp subset sync files push Staging
# One theme and two plugins.
wp subset sync files push Staging --themes=my-theme --plugins=acme-blocks,acme-forms
wp subset sync files pull Production --themes --plugins=acme-blocks
Other files commands
| Command | Options | What it does |
|---|---|---|
files list | --format: table (default), csv, json or count | Lists this site’s themes, plugins and must-use plugins as a transfer sees them. |
files allow | --push=<on|off> | Shows or changes whether other sites may push theme and plugin files here. |
files status | --format: table (default) or json | Shows the current or last transfer, without moving it on. |
files resume | --confirm-production=<domain>, the destination’s domain; --yes skips the confirmation | Carries on with the current transfer after an error or an interruption. A transfer that was planned but not confirmed asks again. |
files cancel | None | Cancels the current transfer. Nothing it staged is swapped in. |
files settings list | --format: table (default), json, csv or yaml | Lists every Pro setting, its value and its source: default, saved or constant. |
files settings get | <name>; --format: plain (default) or json | Prints one Pro setting’s value. |
files settings set | <name> <value> | Changes one Pro setting. Booleans take true/false, yes/no, on/off or 1/0. |
files settings reset | --yes skips the confirmation | Puts every Pro setting back to its default. A setting fixed in wp-config.php keeps the constant’s value. |
The Pro setting is allow_files_push. The backup schedule has its own command, schedule.
wp subset sync files settings list
wp subset sync files settings set allow_files_push on
schedule (Pro)
Backs up the database on a schedule. Scheduled backups are ordinary Subset Sync backups: backups lists them and restore restores one.
wp subset sync schedule status [--format=<format>]
wp subset sync schedule set [--every=<frequency>] [--at=<time>] [--keep=<number>] [--notify=<on|off>]
wp subset sync schedule run
| Command | Options | What it does |
|---|---|---|
schedule status | --format: table (default) or json | Shows the schedule, the backup in progress and how the last one went. |
schedule set | See below | Changes the schedule. |
schedule run | None | Backs up now, in the current process, without waiting for the schedule. |
schedule set option | What it does |
|---|---|
--every=<frequency> | off, twicedaily, daily or weekly. |
--at=<time> | The time of day to start, as 24-hour HH:MM in the site’s timezone. |
--keep=<number> | Backups to keep, counting the ones taken before migrations. At least the free plugin’s three. |
--notify=<on|off> | Emails the admin when a scheduled backup fails. |
Options you leave out keep their current values.
wp subset sync schedule set --every=daily --at=02:30 --keep=14