With wp cloneworx-backup backup you start a backup without a plan and manage the backups of the list: show, lock, check, download, delete. wp cloneworx-backup retention shows which old backups are dropped and deletes them at once if you want.
WP-CLI still missing? The guide is in Install WP-CLI. All commands of the plugin are listed in The commands at a glance.
This applies to all actions
- You specify a backup by its job name: date, time and an identifier of 32 characters.
backup listshows the job name. In the examples it is written as<Job>. - You specify a target in
--targetby its identifier, for examplelocal-1.wp cloneworx-backup target listshows the identifiers. - Only one job runs per website at a time. If one is already running, every command that starts a job ends with an error and shows the running job.
- The outputs of the commands are in English.
-
backup run,backup check,backup deleteandretention runfirst check the user: the command must run as the user who owns the folders of the plugin. The website could not change or delete files that another user creates later on.--forceskips the check.
Starting a backup without a plan: run
backup run starts a backup at once and runs it in this process to its end. The backup belongs to no plan. You run a backup plan with wp cloneworx-backup plan run; more about this in Manage backup plans with WP-CLI.
| Parameter | Meaning | Allowed values |
|---|---|---|
--roots |
What is backed up. Without the parameter the plugin backs up everything. The file wp-config.php is never part of a backup; with wp-config the command stops. |
Roots, separated by commas: db, wp-content, wp-core, wp-mu-plugins, wp-plugins, wp-themes, wp-uploads, wp-root
|
--target |
Where the backup goes. Required: a backup never goes to every target by itself. | The identifier of a usable target. Exactly one target; wp pro-backup run takes several targets with --targets. |
--no-snapshot |
Reads the database without a snapshot. The default is the snapshot. | without a value |
--background |
The command only starts the backup. The website continues it by itself. | without a value |
--max-per-step |
Ends every step after this many entries or rows. The parameter is meant for diagnosis. | whole number |
--force |
Also runs as another user. | without a value |
A root is a named part of the website: the database or a folder. What is in which root is explained in Settings and scope with WP-CLI.
# Back up everything to the target local-1 wp cloneworx-backup backup run --target=local-1 # Back up only database and uploads to one target wp cloneworx-backup backup run --roots=db,wp-uploads --target=local-1 # Start the backup and leave it to the website wp cloneworx-backup backup run --target=local-1 --background
While the backup runs, the command writes one line per step: the phase, the entries and bytes done and the remaining time as soon as the plugin knows it. During the transfer the phase shows the target and, if there are several targets, its position, for example transfer to "SFTP 1" (2/3). At the end it shows the number of steps and warnings. Below is the summary: roots, targets, stored size, the space per location, the database, the files, the parts and per target the result of the transfer. If the backup left out another WordPress installation inside the website, the line not backed up shows its folder.
After a valid backup the same process runs the follow-up: the plugin deletes outdated backups and cleans up leftovers of aborted jobs at the targets.
If the backup ends with an error, the command shows the last messages of the job and, for each target, the state and the reason. For an error at a target, the message from the target is shown unchanged below it, in the line target:.
With --background the command returns at once. wp cloneworx-backup job status then shows the progress.
Without a plan means: its own count
A backup from backup run counts towards the group manual. How many of them stay is set by the setting Max. backups without a plan, default 7.
Listing the backups: list
backup list shows the backups of the list, the newest first. Without an action wp cloneworx-backup backup does the same.
| Parameter | Meaning | Allowed values |
|---|---|---|
--limit |
How many backups the output shows. | 1 to 100, default 20 |
# Show the last 20 backups wp cloneworx-backup backup list # Show only the last 5 wp cloneworx-backup backup list --limit=5
Every line shows one backup: job name, status, plan, end, size and per target the state of the backup there. At the end of the line locked is shown if the backup is locked. The last line shows how many backups the output contains and how many there are.
| Status in the output | In the status filter of the Backup page |
|---|---|
running |
Running |
success |
Complete |
warnings |
With warnings |
error |
Failed |
aborted |
Aborted |
The column for the plan shows the identifier of the plan, for example plan-1. manual stands for a backup without a plan, import for an imported backup and rediscovered for a backup that was found again at a target. On the Backup page, the Plan column shows the words manual, imported and reclaimed for these.
Locking a backup and unlocking it: lock, unlock
backup lock locks a backup. A locked backup is never deleted automatically and is not counted for Max. backups. It can only be deleted by hand after backup unlock. Both actions have no parameters.
# Lock a backup wp cloneworx-backup backup lock <Job> # Unlock the backup wp cloneworx-backup backup unlock <Job>
The command confirms the lock or its end in one sentence. If the plugin is currently deleting the backup at a target, backup lock refuses. More about the lock: Protect a backup from deletion.
Checking a backup: check
backup check reads a backup at every target at which it is complete or recorded as damaged: a new check can change the result. Nothing is written back in the process. The plugin checks whether every file is there with its expected size, whether the info file is valid, whether every part matches its checksum and whether every block can be read. It reads a local folder in place. From an external target it fetches one part after the other into the work folder.
| Parameter | Meaning | Allowed values |
|---|---|---|
--targets |
Checks only at these targets. Without the parameter: at every target at which the backup is complete or recorded as damaged. | Identifiers, separated by commas |
--background |
The command only starts the check. The website continues the job by itself. | without a value |
--max-per-step |
Ends every step after this many blocks. The parameter is meant for diagnosis. | whole number |
--force |
Also runs as another user. | without a value |
# Check a backup at all its targets wp cloneworx-backup backup check <Job> # Check at one target only wp cloneworx-backup backup check <Job> --targets=local-1
The output has one line per target with the result:
| Result | Meaning |
|---|---|
ok |
The backup is readable and complete there. The line shows parts, entries and bytes read. |
damaged or incomplete |
The backup is damaged or incomplete there. The line lists the findings. |
not checked |
The target did not answer. This is a warning, not damage. |
not complete at this target |
The backup is not complete at this target. |
The last line adds everything up. If the backup fails the check at a target, it counts as damaged there: it is no longer counted for Max. backups and is never deleted automatically. More about this: Check a backup.
Writing a backup as a file: download
backup download writes a backup as a tar file on the server. The file contains a folder with the job name, inside it the info file, the index and the parts. The plugin reads at the first local target at which the backup is complete.
| Parameter | Meaning | Allowed values |
|---|---|---|
--to |
The name of the file the command writes, without a path. The file is created in the folder cloneworx-backup-exports-… in the uploads folder and must not exist yet. Without the parameter it is called backup-<Job>.tar. |
File name of letters, digits, dot, underscore and hyphen |
# Write the backup as a tar file wp cloneworx-backup backup download <Job> --to=backup.tar
The command shows the file with its full path, its size, the number of files in it and the target at which it read. If the backup is complete at no local target, it ends with an error. You fetch a backup that is stored only at external targets from there with your own program, for example with your FTP program. More about this: Download a backup.
wp cloneworx-backup import accepts the same file again; see Restore and import with WP-CLI.
Deleting a backup: delete
backup delete deletes a backup at every target at which it is stored. With its last copy the backup disappears from the list. Before deleting, the command asks for confirmation.
| Parameter | Meaning | Allowed values |
|---|---|---|
--target |
Deletes only at this target. The copies at the other targets stay. As long as there is still a copy, the backup stays in the list. | The identifier of one target |
--entry-only |
Removes only the entry from the list. The command deletes nothing at the targets, and no job runs. This works only as long as at least one target no longer has the backup, does not answer or was removed. The command checks this after the confirmation prompt: if every target still has the backup, it ends with an error. You delete an entry that has no copy, for example a failed backup, without this parameter. | without a value |
--yes |
Deletes without a confirmation prompt. | without a value |
--force |
Also runs as another user. | without a value |
# Delete a backup everywhere, with confirmation wp cloneworx-backup backup delete <Job> # Delete only the copy at one target, without confirmation prompt wp cloneworx-backup backup delete <Job> --target=local-1 --yes # Remove only the entry, delete nothing at the targets wp cloneworx-backup backup delete <Job> --entry-only
- The command refuses a locked backup. Unlock it first.
- The command refuses a running backup. Abort it first:
wp cloneworx-backup job abort. - The command does not touch a target that was removed: the backup only loses the reference to this target, nothing is deleted there. The numbers at the end count this neither as deleted nor as failed.
- An entry without a copy, for example a failed or aborted backup, disappears from the list at once, without a confirmation prompt and without a job.
Deleting runs as a job in this process. At the end the command shows how many copies it deleted and for how many the deletion failed. A target whose folder belongs to another installation counts as failed and is shown in brackets. The line also shows a backup that has been locked in the meantime. More about this: Delete a backup.
The last valid backup at a target
If the backup is the last valid one at a target, the command warns and shows the target. Deleting stays allowed. With --yes no confirmation prompt follows the warning.
Showing and deleting outdated backups: retention
Per backup plan and per target the plugin keeps as many valid backups as Max. backups in the plan specifies. Older ones are dropped. Locked backups are not counted and are never dropped automatically. The newest valid backup is never dropped. This happens on its own after every valid backup. With wp cloneworx-backup retention you see it beforehand or trigger it by hand.
| Action | Purpose |
|---|---|
retention list |
Shows which backups would be dropped now. Deletes nothing. Without an action the command does the same. |
retention run |
Deletes these backups now and runs the job in this process. |
| Parameter | Meaning | Allowed values |
|---|---|---|
--plan |
Only this group. Without the parameter: every plan and the backups without a plan. | Identifier of a plan, for example plan-1, or manual
|
--force |
Only run: also runs as another user. |
without a value |
# Show what would be dropped wp cloneworx-backup retention list # Delete now, for one backup plan only wp cloneworx-backup retention run --plan=plan-1 # Delete now, only backups without a plan wp cloneworx-backup retention run --plan=manual
retention list shows one backup per line, with the target and the group: the name of the plan or manual. The last line counts the deletions. If nothing is dropped, the command says so in one sentence. retention run shows at the end how many backups were deleted.