Manage targets with WP-CLI

With the command target you manage your targets on the command line: show, create, change, test, check, clean up and remove. In addition there are the actions for a fingerprint conflict and for finding backups.

WP-CLI is not set up yet? Then start with Install WP-CLI. What applies to every command, for example the user and the parameter --background, is described in The commands at a glance.

Naming a target

You name a target with its identifier or with its name. The identifier consists of the target type and a sequential number, for example local-1 or sftp-1. The identifier never changes, even if you rename the target. In names, upper and lower case do not matter; a name with spaces is put in quotation marks.

Every action except list checks whether you are working as the user who owns the folders of the plugin. --force skips this check.

Showing targets: list

# Show all targets with ID and state
wp cloneworx-backup target list

The output names one line per target: identifier, target type, name, state and location. The last line begins with Types: and lists the target types that exist: local, ftp, sftp, webdav, amazon-s3, s3, google-drive and dropbox. If the server lacks something for a target type, it is shown in brackets after it.

State in the output	Meaning	Usable
connected (tested …)	The last connection test succeeded; its time is shown after it.	yes
not tested yet	Saved, but without a successful test since the last change of the settings.	no
test failed (…)	The last connection test failed; the code of the reason is in the brackets.	no
disconnected (…)	The stored credentials are no longer usable; the code of the reason is in the brackets, for example secrets_unreadable (no longer readable) or auth_failed (rejected by the target). Enter them again on the Targets page: Renew the credentials of a target. For a target of the type Google Drive or Dropbox the code is grant_invalid when the provider no longer accepts the consent; you connect it again there.	no
type not available	The server lacks something for this target type.	no
removed	Removed; backups in the list still refer to the target.	no

Two notes can follow the state. CATALOG CONFLICT is a fingerprint conflict: the catalog at the target belongs to another installation, the output names its address. catalog stale means: the catalog at the target could not be written last time; the backup is good nevertheless, and the next backup writes the catalog anew.

Creating a target: add

# Create a local folder as a target
wp cloneworx-backup target add local --name="Archiv" --set-path=/var/backups

# Test the new target
wp cloneworx-backup target test local-1

Entry	Meaning	Allowed values
Target type	Directly after add.	local. The other target types require a password or a key and therefore cannot be created here. The command refuses google-drive and dropbox and names the way in the browser: Targets page, Add target.
--name=<name>	Your name for the target. Without the parameter the plugin assigns its suggestion.	At most 100 characters. Any name that is not in use yet works, not even by a removed target.
--set-path=<folder>	The folder on the server, in the form the field Folder on the server. Required.	An absolute path to a folder that already exists and that may be written to. It must not lie inside the plugin directory, which WordPress deletes on every update.
--force	Skips the check of the user.

The command saves the target and names its identifier. It is not tested yet with that: a target becomes usable only through a successful connection test. You do not have to create the plugin’s own folder; it is created inside the folder you name.

With your first target the plugin creates the plan “Daily backup”. It is paused until you switch it on. More about this: Manage backup plans with WP-CLI.

If an entry does not fit, the command saves nothing. It names the field with a code and ends with Settings are not valid.

Code	Meaning
required	A required field is empty.
base_invalid	The path is not absolute, or the folder does not exist.
base_in_plugin	The folder lies inside the plugin directory.
base_not_writable	The folder may not be written to.
taken, too_long	The name is already in use or longer than 100 characters.
invalid, out_of_range	The value is not allowed or lies outside its limits.

Changing a target: edit

# Rename a target
wp cloneworx-backup target edit local-1 --name="Archiv 2"

# Change a setting, then test again
wp cloneworx-backup target edit sftp-1 --set-port=2222
wp cloneworx-backup target test sftp-1

edit needs at least --name or a setting. You set a setting with --set-, followed by the name of the setting and its value, for example --set-port=2222. Stored passwords and keys are kept. After a changed setting the target counts as not tested again: test it anew, otherwise plans and backups skip it. A new name does not change that.

Setting	Field in the form	Target types	Allowed values
path	Folder on the server, Folder on the FTP server, Folder on the SFTP server, Folder in the bucket, Folder in Google Drive	local, ftp, sftp, amazon-s3, s3, google-drive	Required for local. Otherwise the value may be empty.
host	Server	ftp, sftp	Host name or IP address
user	User name	ftp, sftp, webdav
port	Port	ftp, sftp	1 to 65535. Empty means 21 for ftp, 990 for implicit FTPS, 22 for sftp.
timeout	Connection timeout (seconds)	ftp, sftp, webdav, amazon-s3, s3, google-drive, dropbox	3 to 60, default 10
security	Encryption	ftp	explicit (FTPS with TLS), none (none), implicit (FTPS, implicit)
mode	Transfer mode	ftp	passive, active
auth	Login	sftp	password, key
url	Address of the folder	webdav	The full address
method	Upload method	webdav	range, chunks, whole. Empty means: what the connection test determined.
upload_rate	Upload rate (bytes per second)	webdav, amazon-s3, s3, google-drive, dropbox	1024 to 1073741824. Empty means: what the connection test measured.
bucket	Bucket	amazon-s3, s3
access_key	Access key	amazon-s3, s3
region	Region	amazon-s3, s3
endpoint	Address of the service	s3	The address without the bucket
style	Form of the address	s3	path, virtual. Empty means: what the connection test determined.

What is secret cannot be accepted: password, private_key and secret_key. The settings tls_pin and host_key carry an accepted certificate or the confirmed key of a server. Both are set by the Targets page when you accept a certificate or a server key there. If you name a setting that the target type does not know, the command lists the settings of the target type.

Testing the connection: test

# Test the connection of a target
wp cloneworx-backup target test sftp-1

The test writes a small file to the target, reads it back, compares it and deletes it again. The result is stored at the target: after a successful test the target is usable.

The output names the details of the test as lines of name and value, for example the free space in the line free_space. The last line says whether the target works (works) or for which reason the test failed (failed). If new files belong to a different user than the folder of the target, the command warns: the website may not be able to change or delete such files.

Checking the backups at a target: check

# Check every backup at this target
wp cloneworx-backup target check sftp-1

# Only start the check; the website continues it
wp cloneworx-backup target check sftp-1 --background

The check reads every backup that is stored at this target, the newest first: every file, the info file, every part against its checksum and every block. Nothing is restored in the process. The result is afterwards also shown in the list of backups.

The output names one line per backup with the result and the total at the end:

Result in the output	Meaning
ok	The backup is readable and complete. After it follow the number of parts, the number of entries and the amount read.
damaged or incomplete	The backup is damaged or incomplete at this target. After it you see what is wrong.
not checked	The target did not answer. This is a warning, not damage to the backup.
not complete at this target	The backup is not complete at this target.

Every good backup that is complete at the target or is recorded there as damaged is checked. If there is none, the check does not start and says so.

Cleaning up leftovers: cleanup

# Only show what would be removed
wp cloneworx-backup target cleanup local-1 --dry-run

# Remove the leftovers
wp cloneworx-backup target cleanup local-1

A leftover is a folder that an aborted job left behind at the target and that never becomes a backup: it has no info file, does not belong to the running job, and the list of backups does not record it at this target. An unfinished upload also counts as a leftover. The same run removes old files from the work folder of the plugin on the server. A folder with an info file always stays, and what is in the list is never touched by the cleanup.

Parameter	Meaning
--dry-run	Shows the number of files and the size per folder and removes nothing. No job runs.
--background	Starts the job; the website continues it.
--force	Skips the check of the user.

The output names per target the number of removed folders and files and their size, plus the number of backup folders that stay although the list does not know them. You bring such backups into the list with rebuild. The cleanup also runs on its own after every good backup, at the targets at which this backup arrived.

Answering a fingerprint conflict: moved and copy

Before the plugin writes to a target, it compares the fingerprint in the catalog at the target with its own. If the two do not match, it writes and deletes nothing there until you decide. Which answer is right when is explained in The website has moved or is a copy.

# Same website, new address or new path: moved
wp cloneworx-backup target moved sftp-1

# This installation is a copy of the original
wp cloneworx-backup target copy sftp-1 --yes

Action	What happens
moved	The catalog at the target is written anew with the fingerprint of this installation, the recorded conflict is resolved, and the target is used again. The output names the address the catalog carried before. Never use moved for a copy.
copy --yes	This installation gets a new folder code and with it its own folder at every target. The log folder and the work folder move along. The backups in the list of this installation belong to the original and disappear from the list; nothing is deleted at the targets. All recorded conflicts are resolved. The next backup writes into the new folder.

copy applies to the whole installation, not only to the named target. Without --yes the command changes nothing: it names the consequences and the number of entries that would disappear from the list.

Finding backups: sites, adopt and rebuild

Every installation of the plugin has its own folder code, and its backups are stored at every target in the folder cloneworx-backup-<code>. After a total loss the fresh installation does not know the folder of the previous one. The whole way is described in Find backups again after a total loss.

# Show what is stored at the target's location
wp cloneworx-backup target sites sftp-1

# Take over the folder of a previous installation
wp cloneworx-backup target adopt sftp-1 --folder=cloneworx-backup-0123456789abcdef0123456789abcdef

# Add backups from your own folder to the list
wp cloneworx-backup target rebuild sftp-1

sites

The output begins with the plugin’s own folder: whether its catalog is readable, how many backups the catalog names, how many backups the list records at this target and how many backups of the folder are missing from the list. Below it follow the folders of other installations, per folder with the address of the website from its catalog, the number of backups, the date of the last one and the version of the plugin. The last line says whether taking over is possible right now.

adopt

Parameter	Meaning	Allowed values
--folder=<name>	The folder of the previous installation at the target. Required.	The name of the folder, cloneworx-backup- and 32 characters, or the 32 characters alone.
--background	Starts adding to the list; the website continues it.
--force	Skips the check of the user.

Afterwards this installation continues with the folder code of the previous one. The log folder and the work folder move along, empty folders with the previous code are removed at local targets, and the backups from the folder are added to the list. Taking over at the same time confirms that the website has moved.

rebuild

rebuild adds backups from the plugin’s own folder at the target to the list that are missing there, for example after a target was removed and set up again. The job reads the catalog at the target, without a readable catalog the list of folders. For every backup it fetches the info file and checks whether every file is stored at the target in its size. With --background the website continues the job.

The last line names the result: how many backups were found, how many were newly added to the list, how many were already in it and how many are incomplete. The plugin never deletes backups it found again automatically.

Removing a target: remove

# Remove the target; its backups are kept
wp cloneworx-backup target remove local-1

# First delete all backups at the target, then remove the target
wp cloneworx-backup target remove local-1 --with-backups

Parameter	Meaning
without a parameter	The target is removed. The backups stay at the target where they are.
--with-backups	The plugin first deletes every backup at this target and then removes the target. The command runs the job itself to its end. If locked backups are stored at the target, it refuses: unlock them first, or remove the target without its backups.
--force	Skips the check of the user.

• If backups in the list still refer to the target, its entry stays as removed, without settings and without credentials. The output names the number of entries that still refer to it.
• If no backup refers to it any more, the command deletes the entry entirely. That also applies to a target that is already removed.
• A removed target leaves every backup plan. A plan without a target is paused. It can only be switched on again once you give it a target.
• For a target of the type Dropbox the plugin revokes at Dropbox the access the target held after removing it. The backups stay in your Dropbox. The revocation is not sent if the stored credentials are no longer readable, if the target was already removed or if cURL is missing. It fails if Dropbox or the sign-in service cannot be reached at that moment. The target is removed nevertheless. The access then stays valid at Dropbox until you disconnect the app in your Dropbox account.
• For a target of the type Google Drive the plugin revokes nothing: the access the target held stays valid at Google, and the consent stays in your Google account until you remove it there.

See also

• The “Targets” page
• Store backups in a local folder
• Check backups at a target and clean up leftovers
• Remove a target
• Manage backup plans with WP-CLI