Skip to content

[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>]
OptionDefaultWhat it does
<remote>NoneA saved connection’s name (see connections), or the remote site’s URL from its connection info, with <key>.
<key>NoneThe 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.

OptionDefaultWhat it doesCommands
--mediaOffAlso transfers the media library.push, pull
--media-onlyOffTransfers the media library but not the database.push, pull
--all-mediaOffTransfers every media file, not only new and changed ones.push, pull
--delete-mediaOffDeletes media on the destination that doesn’t exist on the source.push, pull
--exclude=<patterns>NoneComma-separated glob patterns of media files to skip.push, pull
--exclude-tables=<patterns>NoneComma-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>NoneComma-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>NoneMigrates 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>NoneExtra find values, separated by |. Pairs with --replace.push, pull, export, import
--replace=<values>NoneExtra replace values, separated by |.push, pull, export, import
--include-transientsOffMigrates transients too.push, pull, export
--skip-spamOffLeaves out spam and trashed comments.push, pull, export
--skip-revisionsOffLeaves out post revisions.push, pull, export
--skip-auto-draftsOffLeaves out auto-drafts.push, pull, export
--leanOffShorthand for --skip-spam --skip-revisions --skip-auto-drafts.push, pull, export
--skip-backupOffDoesn’t back up the destination database before replacing it.push, pull, import, restore
--dry-runOffPrints the preview and exits without changing anything on either site.push, pull
--confirm-production=<domain>NoneRequired when the site being replaced is marked as a production site: its domain, to confirm.push, pull, import, restore
--yesOffSkips the confirmation prompt. It doesn’t skip --confirm-production.push, pull, import, restore
--verboseOffIn 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>tabletable 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>]
OptionDefaultWhat it does
<remote>NoneA saved connection’s name, or the remote site’s URL with <key>.
<key>NoneThe remote site’s connection key. Leave it out for a saved connection.
--exclude=<patterns>NoneComma-separated glob patterns of media files to leave out of the comparison.
--format=<format>tabletable 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>]
OptionDefaultWhat it does
<file>NoneWhere to write the export.
--target-url=<url>NoneRewrites this site’s URL to this one in the export.
--target-path=<path>NoneRewrites 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>]
OptionDefaultWhat it does
<file>NoneThe 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>]
OptionDefaultWhat it does
--format=<format>tabletable 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]
OptionDefaultWhat it does
<action>listlist or delete.
<name>NoneThe backup’s name, from the list. Required for delete.
--fields=<fields>AllComma-separated fields to show: name, created, size, path. Only for list.
--format=<format>tabletable, csv, json, yaml or count. Only for list.
--yesOffDeletes 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]
OptionDefaultWhat it does
<name>NoneThe 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>]
OptionDefaultWhat it does
--format=<format>tabletable 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]
OptionDefaultWhat it does
--resetOffGenerates 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>]
OptionDefaultWhat it does
<action>Nonelist, add, rename, rekey or remove.
<name>NoneThe connection’s name. Required for every action except list.
<remote-url>NoneRequired for add and rekey. For rename, the new name instead.
<key>NoneRequired for add and rekey.
--format=<format>tabletable, 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>]
OptionDefaultWhat it does
--push=<on|off>UnchangedAllows other sites to push to this one.
--pull=<on|off>UnchangedAllows 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]
OptionDefaultWhat it does
--yesOffDoesn’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]
SubcommandOptionsWhat it does
list--format: table (default), json, csv or yamlLists every setting, its value and its source: default, saved or constant.
getNonePrints one setting’s value: true or false.
setNoneChanges one setting. Values take true/false, on/off, yes/no or 1/0. Refused if a constant locks the setting.
reset--yes skips the confirmationPuts 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_modules and .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]
OptionDefaultWhat it does
<remote>NoneThe other site’s URL, or the name of a saved connection.
<key>NoneThe other site’s connection key, when <remote> is a URL.
--themes[=<slugs>]NoneEvery theme, or a comma-separated list of them.
--plugins[=<slugs>]NoneEvery plugin, or a comma-separated list. Single-file plugins go by file name, such as hello.php.
--mu-plugins[=<names>]NoneEvery must-use plugin, or a comma-separated list. Must-use plugins aren’t included unless you ask for them.
--exclude=<patterns>NoneComma-separated glob patterns neither side touches, matched against <slug>/<path> and the file name, such as *.log,my-theme/assets/src/*.
--dry-runOffShows what would change, and stops.
--confirm-production=<domain>NoneThe destination’s domain, typed out, when it’s marked as a production site.
--yesOffDoesn’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

CommandOptionsWhat it does
files list--format: table (default), csv, json or countLists 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 jsonShows the current or last transfer, without moving it on.
files resume--confirm-production=<domain>, the destination’s domain; --yes skips the confirmationCarries on with the current transfer after an error or an interruption. A transfer that was planned but not confirmed asks again.
files cancelNoneCancels the current transfer. Nothing it staged is swapped in.
files settings list--format: table (default), json, csv or yamlLists every Pro setting, its value and its source: default, saved or constant.
files settings get<name>; --format: plain (default) or jsonPrints 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 confirmationPuts 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
CommandOptionsWhat it does
schedule status--format: table (default) or jsonShows the schedule, the backup in progress and how the last one went.
schedule setSee belowChanges the schedule.
schedule runNoneBacks up now, in the current process, without waiting for the schedule.
schedule set optionWhat 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