Create and manage backups with WP-CLI

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 named in The commands at a glance.

This applies to all actions

• You name a backup with its job name: date, time and an identifier of 32 characters. backup list shows the job name. In the examples it is written as <Job>.
• You name a target in --targets with its identifier, for example local-1. wp cloneworx-backup target list shows the identifiers.
• Only one job ever runs per website. If one is already running, every command that starts a job ends with an error and names the running job.
• The outputs of the commands are in English.
• backup run, backup check, backup delete and retention run first 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. --force skips the check.

Starting a backup without a plan: run

backup run starts a backup at once and drives 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.	Roots, separated by commas: db, wp-config, wp-content, wp-core, wp-mu-plugins, wp-plugins, wp-themes, wp-uploads, wp-root
--targets	Where the backup goes. Without the parameter it goes to every usable target.	Identifiers of usable targets, separated by commas
--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 drives it on itself.	without a value
--max-per-step	Ends every step after this many entries or rows. The parameter serves 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 every usable target
wp cloneworx-backup backup run

# Back up only database and uploads to one target
wp cloneworx-backup backup run --roots=db,wp-uploads --targets=local-1

# Start the backup and leave it to the website
wp cloneworx-backup backup run --background

While the backup is running, 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. At the end it names the number of steps and warnings. Below it comes the summary: roots, targets, stored size, the space per location, the database, the files, the parts and per target the result of the transfer.

After a good backup the same process drives 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 names the last messages of the job, per 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.

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 names 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 says how many backups the output shows 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.

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. 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 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 a remote 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 drives the job on itself.	without a value
--max-per-step	Ends every step after this many blocks. The parameter serves 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 names parts, entries and bytes read.
damaged or incomplete	The backup is damaged or incomplete there. The line names 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 a target fails, the backup 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 file the command writes. Required. The file must not exist yet, and its folder must be writable.	Path of a file

# Write the backup as a tar file
wp cloneworx-backup backup download <Job> --to=/tmp/backup.tar

The command names the file, 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. A backup that is stored only at remote targets you fetch 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
--targets	Deletes only at these targets. The copies at the other targets stay. As long as there is still a copy, the backup stays in the list.	Identifiers, separated by commas
--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> --targets=local-1 --yes

• The command refuses a locked backup. Unlock it first.
• The command refuses a running backup. Abort it first: wp cloneworx-backup job abort.
• 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 names how many backups were deleted and how many attempts failed. More about this: Delete a backup.

Showing and deleting outdated backups: retention

Per backup plan and per target the plugin keeps as many good backups as Max. backups in the plan says. Older ones are dropped. Locked backups are not counted and are never dropped automatically. The newest good backup is never dropped. This happens on its own after every good 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 drives 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 names per line one backup, 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 names at the end how many backups were deleted.

See also

• The “Backup” page
• Create a backup right now
• Define how many backups are kept
• Manage backup plans with WP-CLI
• State, logs and support with WP-CLI