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.
Passwords and keys stay reserved for the Targets page
The command line never accepts a password and never a key: every value would appear there in the list of processes and in the history of the shell. That is why you can only create a local folder here. You set up targets with credentials on the Targets page. The same applies to a target of the type Google Drive or Dropbox: you give your consent at the provider in the browser. The other actions then work with these targets too.
Specifying a target
You specify a target by its identifier or by 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 contains 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. The entry stays until you delete it permanently with remove. |
no |
Two notes can follow the state. CATALOG CONFLICT is a fingerprint conflict: the catalog at the target belongs to another installation, the output shows its address. catalog stale means: the catalog at the target is not up to date with the list. It could not be written last time, or a backup was only taken out of the list with --entry-only. The backups are valid nevertheless, and the next backup to this target 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 shows 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 works that is not yet in use, 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 shows its identifier. It is not yet tested at that point: 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 specify.
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 a value is not valid, the command saves nothing. It shows 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, 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) |
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. |
max_request |
Largest request (bytes) | webdav | 1048576 to 268435456, only with the method whole. Empty means: what a backup learned. |
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. |
Secret values are not accepted: password, private_key and secret_key. The settings tls_pin and host_key contain 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 specify 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 shows the details of the test as lines of name and value, for example the free space in the line free_space. The last line shows 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 shows a warning: 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 contains 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 valid 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 the cleanup never touches what is in the list.
| 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. |
For each target, the output shows 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 add such backups to the list with rebuild. The cleanup also runs on its own after every valid 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 shows the address the catalog contained 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 with it. 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 specified target. Without --yes the command changes nothing: it shows 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>. If the plugin removed all settings when it was deleted, or if WordPress is running with a new database, the plugin starts with a new code and does not know the folder of the previous installation. The whole procedure is described in Find backups again after a reinstallation.
Unlike the Targets page, the command line does not add backups that are missing from the list on its own, not even after add or test: start rebuild yourself.
# 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 the plugin’s own folder to the list wp cloneworx-backup target rebuild sftp-1 # The website moved: confirm with --moved wp cloneworx-backup target rebuild sftp-1 --moved
sites
The output begins with the plugin’s own folder: whether its catalog is readable, how many backups are stored in the folder, how many backups the list records at this target and how many backups of the folder are missing from the list. What the catalog lists counts as a backup in the folder, and so does every further folder with an info file. 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 shows whether a folder can be taken over 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. |
--accept-unknown |
Confirms the backups in the folder that this website does not know as correct. Without the parameter the command only reads the folder, names the numbers and takes over nothing. | |
--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 with it, empty folders with the previous code are removed at local targets, and the backups from the folder are added to the list. If you take over the folder, you confirm at the same time that the website has moved.
Take over only the folder of your own website, only with an empty list of backups
Take over only the folder of your own website. As long as the list of this installation contains backups or a job is running, the command refuses to take over. After taking over, the next backups are stored in the folder that was taken over.
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 and the list of folders there: a folder with an info file counts as a backup, even if the catalog does not list it. For every backup it fetches the info file and checks whether every file is stored at the target with its expected size. With --background the website continues the job.
The last line shows the result: how many backups were found, how many were newly added to the list, for how many an existing entry got this target added, how many the list already knew at this target, how many are incomplete and how many were skipped.
-
rebuildadds backups that this website does not know only with--accept-unknown. Without the parameter they stay untouched at the target, and the output names their number. Only confirm them as correct if you trust the storage target. - A backup that is newly added to the list has the plan
rediscovered; on the Backup page, the Plan column shows the word reclaimed for it. The plugin never deletes such backups automatically. - An entry that is already in the list and only gets the target added keeps its plan.
- At the end, the job rewrites the catalog at the target. If the catalog at the target belongs to another website,
rebuildrefuses and shows its address; nothing is added or written. If this website has moved there, repeat the command with--moved: then the job rewrites the catalog with the fingerprint of this installation, and a recorded fingerprint conflict at this target is resolved. Never use--movedfor a copy.
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
The command does not ask
Unlike the Targets page, remove shows no confirmation prompt. With --with-backups the backups at this target are deleted afterwards. A target that is already removed is deleted permanently by remove without asking: backups that were stored only at this target disappear from the list in the process.
| 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. If a backup cannot be deleted there, if the folder at the target belongs to another installation or if a backup has been locked in the meantime, the target stays set up; the command warns with Target … was not removed: … and shows the reason. |
--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 shows the number of entries that still refer to it.
- If no backup refers to it any more, the command deletes the entry entirely.
- A second
removeon a target that is already removed deletes its entry permanently, even if backups in the list still refer to it. These backups lose the reference; backups that were stored only at this target disappear from the list. The command deletes nothing at the target. The output shows both numbers. - If locked backups refer to the removed target, the command refuses and shows their number. Unlock them first, with
backup unlock, and then run the command once more. - A removed target is removed from every backup plan. A plan without a target is paused. It can only be switched on again once you assign a target to it.
- For a target of the type Dropbox the plugin revokes at Dropbox the access the target had 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 had stays valid at Google, and the consent stays in your Google account until you remove it there.