Akeeba Backup CLI offers a relatively large number of commands which allow you to do almost everything you can do through the graphical user interface. For simplicity's sake we have grouped them under different categories, depending on what is the target of the command.
These commands allow you to manage backup records. A backup record is any backup attempt be it fully successful, partially successful (the backup ran but it didn't upload to remote storage), failed or pending. They are equivalent to the Backup Now and Manage Backups pages of the component.
![[Note]](/media/com_docimport/admonition/note.png) | Note |
|---|---|
|
Only works with Akeeba Backup Professional. |
What it does: Takes a backup with Akeeba Backup.
Syntax: akeeba:backup:take [--profile=PROFILE_ID] [--description=DESCRIPTION] [--comment=COMMENT] [--overrides=OVERRIDES]
Arguments
This command takes no arguments.
Options
- --profile=PROFILE_ID
-
Optional. Which backup profile to use when taking a backup. Uses the default backup profile (1) when omitted.
You need to specify the numeric backup profile. For example, to take a backup with profile #2 you need to specify
--profile=2. - --description=DESCRIPTION
-
Optional. Short description for the backup record, accepts backup naming variables. Uses the default description when omitted.
The description is displayed in the Manage Backups page and when listing backup records. It's meant to offer you a quick refresher of what the backup is for. For example:
--description="Taking a backup before updating Joomla" - --comment=COMMENT
-
Optional. A longer, plain text comment describing the backup.
This is displayed as a tooltip in the Manage Backups page and returned when listing backup records. It's meant for more in-depth information. Typically you'd set a shell variable and pass it to this option. For example
--comment="$MY_VARIABLE"for the Bash (default Linux) shell. - --overrides=OVERRIDES
-
Optional. Override configuration parameters while taking the backup.
Please consult the Native CRON Script documentation for more information on how to use this option.
Exit codes
One of the following exit codes will be set when the command finishes running:
- 0
-
All good. The backup is successful and emitted no warnings.
- 1
-
The backup failed to complete. An error occurred while taking the backup.
- 2
-
The backup is successful but warnings were emitted.
What it does: Lists backup records known to Akeeba Backup.
This lists all backup attempts regardless of whether they are successful, ended in an error, are locally stored, remotely stored or their files no longer exist. It's the equivalent to the Manage Backups page.
Syntax: akeeba:backup:list [--from=FROM] [--limit=LIMIT] [--format=FORMAT] [--description=DESCRIPTION] [--after=AFTER] [--before=BEFORE] [--origin=ORIGIN] [--profile=PROFILE] [--sort-by=SORT-BY] [--sort-order=SORT-ORDER]
Arguments
This command takes no arguments.
Options
- --from=FROM
-
Optional.How many backup records to skip before starting the output.
This is typically used in conjunction with
--limit. For example--limit=20 --from=40to display up to 20 backup records starting with the 40th record. - --limit=LIMIT
-
Optional. Maximum number of backup records to display.
Up to this many backup records will be returned at a time. It is possible that less or no records are returned. However, no more than this many records will be returned at a time.
- --format=FORMAT
-
Optional. The output format, as described above.
Possible values:
table,json,yaml,csv,count - --description=DESCRIPTION
-
Optional. Listed backup records must match this (partial) description.
Note that this is a partial, case-insensitive match. --description="day" will match backup records with the descriptions "Before daylight savings", "Day-to-day backup" and "Added Dayton to the site"
- --after=AFTER
-
Optional. List backup records taken after this date.
The date and time must be specified in MySQL format, e.g. "2020-12-01 13:45:23" for December 1st, 2020 at 23 seconds past 1:43pm. The date and time are always expressed in the GMT (UTC) timezone.
- --before=BEFORE
-
Optional. List backup records taken before this date.
The date and time must be specified in MySQL format, e.g. "2020-12-01 13:45:23" for December 1st, 2020 at 23 seconds past 1:43pm. The date and time are always expressed in the GMT (UTC) timezone.
- --origin=ORIGIN
-
Optional. List backups taken from this origin only. The possible origins are:
-
backend. Backups taken from the backend of the site.
-
frontend. Backups taken with the legacy frontend backup or the akeeba-altbackup.php script.
-
json. Backups taken with the Akeeba Backup JSON API or the Joomla JSON API.
-
cli. Backups taken with the akeeba-backup.php CLI script or the Akeeba Backup CLI.
-
- --profile=PROFILE
-
Optional. List backups taken with this profile.
Give the numeric profile ID. For example,
--profile=2 - --sort-by=SORT-BY
-
Optional. Sort the backups by this column. Possible columns:
-
id. The backup identity number. This is a positive integer that increases monotonically, i.e. each new backup attempt gets an ID that is 1 higher than the previous backup attempt.
-
description. The short description of the backup.
-
profile_id. The profile number.
-
backupstart. The date and time (UTC) the backup started on.
-
- --sort-order=SORT-ORDER
-
Optional. Sorting order.
Use
ascfor ascending order,descfor descending order.
Exit codes
One of the following exit codes will be set when the command finishes running:
- 0
-
The command completed without an error.
Note that a zero exit code is returned even if the command returns no records. If you want to test whether records matching your criteria exist use --format=count and check whether the output of the command is a non-zero integer.
What it does: Lists a backup record known to Akeeba Backup given its backup identity (ID) number.
Syntax: akeeba:backup:info ID [--format=FORMAT]
Arguments
This command takes one mandatory argument.
- ID
-
The numeric ID of the backup.
Options
- --format=FORMAT
-
Optional. The output format, as described above.
Possible values:
table,json,yaml,csv,count
Example
php joomla.php akeeba:backup:info 123 --format=json
Returns the information for backup number 123 encoded as JSON.
Exit codes
One of the following exit codes will be set when the command finishes running:
- 0
-
The command completed without an error.
No error is returned if you give it an invalid backup ID.
What it does: Modifies a backup record known to Akeeba Backup. This is used to change the description and / or comment of a backup record.
Syntax: akeeba:backup:modify ID [--description=DESCRIPTION] [--comment=COMMENT]
Arguments
This command takes one mandatory argument.
- ID
-
The numeric ID of the backup.
Options
- --description=DESCRIPTION
-
Optional. Change the short description to this value.
- --comment=COMMENT
-
Optional. Change the backup comment to this value.
Exit codes
One of the following exit codes will be set when the command finishes running:
- 0
-
The command completed without an error.
- 1
-
The backup ID you provided does not exist.
- 2
-
You gave neither --description nor --comment. You need to provide one or both for the command to do anything at all.
- 3
-
Cannot modify backup record. Further information is provided in the error message. This usually happens when there's a database issue preventing you from saving the modified backup record back to the database.
What it does: Deletes a backup record known to Akeeba Backup, or just its files.
![[Important]](/media/com_docimport/admonition/important.png) | Important |
|---|---|
|
This command only deletes locally stored files, i.e. backup archives stored on the same server Akeeba Backup is installed. It will NOT delete any backup archives stored remotely e.g. on Amazon S3, Dropbox and so on. |
Syntax: akeeba:backup:delete ID [--only-files]
Arguments
This command one mandatory argument.
- ID
-
The numeric ID of the backup.
Options
- --only-files
-
Optional. Only delete the backup files stored on the site's server, not the record itself.
If you do not give this option both the locally stored backup archives and the backup record itself are deleted.
When you give this option only the locally stored backup archives will be deleted. The backup record remains in the database and is now marked as Obsolete.
Exit codes
One of the following exit codes will be set when the command finishes running:
- 0
-
The command completed without an error.
- 1
-
Cannot delete. Further information is provided in the error message.
| Note |
|---|---|
|
Only works with Akeeba Backup Professional. |
What it does: Retry uploading a backup to the remote storage.
When a backup fails to upload to the remote storage engine you can rectify the problem that caused the upload failure – usually a server configuration issue or just a dropped network connection – and use this command to upload the remaining parts from your server to the remote storage. It can also be used to re-upload a previously remotely stored backup you have retrieved locally using the akeeba:backup:fetch command.
Syntax: akeeba:backup:upload ID
Arguments
This command takes one mandatory argument.
- ID
-
The numeric ID of the backup to retry uploading.
Options
This command does not take any options.
Exit codes
One of the following exit codes will be set when the command finishes running:
- 0
-
The command completed without an error.
- 1
-
You have supplied an invalid backup record ID.
- 2
-
Retrying the upload failed. Further information is provided in the returned error message.
| Note |
|---|---|
|
Only works with Akeeba Backup Professional. |
What it does: Download a backup from the remote storage back to your server.
Please note that not all remote storage engines may implement this feature. It is also possible that the credentials you use to connect to the remote storage server / service do not give you permissions to download backup archives, for example if you're using Amazon S3 with an IAM user which only allows writing to but not reading from files. Do keep in mind that it's always possible that the remotely stored file has been deleted outside Akeeba Backup, therefore trying to retrieve it will result in a reasonably self-understood error.
Please also keep in mind that this is only meant to work with Post-processing engines, NOT archiver engines. Akeeba Backup Professional includes archiver engines which let you upload the raw site files instead of a backup archive to a remote FTP or SFTP server. These backups CAN NOT be retrieved back to the server. They are immediately considered "Obsolete" since no backup archive was generated during the backup process.
Syntax: akeeba:backup:fetch ID
Arguments
This command takes one mandatory argument.
- ID
-
The numeric ID of the backup to retrieve from the remote storage back to the server.
Options
This command does not take any options.
Exit codes
One of the following exit codes will be set when the command finishes running:
- 0
-
The command completed without an error.
- 1
-
You have supplied an invalid backup record ID.
- 2
-
Trying to retrieve the remotely stored file failed. Further information is provided in the returned error message.
What it does: Returns a backup archive part for a backup record known to Akeeba Backup.
The command name is a bit of a misnomer. It doesn't really "download" anything rather than read a backup archive file which is already on the server and return its contents or write them to a file.
This can be used for automating restorations together with Akeeba UNiTE. Use akeeba:backup:list to find the ID of the backup archive you want to restore. Use akeeba:backup:download to store it with a predictable name in a directory whose name you already know. Use that information in an Akeeba UNiTE XML file and run Akeeba UNiTE against it to restore the site.
Syntax: akeeba:backup:download ID [PART] [--file=FILE]
Arguments
This command takes one mandatory and one optional argument. Please remember that arguments are positional, i.e. they need to appear in the order described below.
- ID
-
The numeric backup record ID you want to retrieve files for. Please remember that the backup archive files MUST be present on your server. If you have a remotely stored backup archive remember to use akeeba:backup:fetch beforehand.
- PART
-
The part number to download. Default: 1. This is useful when your backup archive consists of more than one files, called parts. You need all the parts to be present to extract the backup archive and restore it.
Options
- --file=FILE
-
Optional. The absolute path to the file where the backup archive's contents will be written to.
If omitted, akeeba:backup:download returns the backup archive's contents as its output (in STDOUT). This behaviour can be useful for using shell pipes to transfer the file between hosts.
Exit codes
One of the following exit codes will be set when the command finishes running:
- 0
-
The command completed without an error.
- 1
-
You have supplied an invalid backup record ID.
- 2
-
There are no locally stored backup archive files for this backup record.
- 3
-
The part number you supplied is less than 1 or greater than the total number of parts in the backup archive.
- 4
-
The part number you supplied exists but its corresponding file cannot be found on the server. This typically means that you have accidentally deleted part files (.j01, .j02, ... or .z01, .z02, ...). Another possibility is that your backup archive failed to completely upload to remote storage or failed to be completely retrieved from remote storage.
- 5
-
The part number you supplied exists, its file is found on the server but Akeeba Backup CLI cannot open it for reading. This typically means that the user CLI is running under does not have read permissions on the backup archive. Most likely you took your backup using the backend, frontend or remote JSON API i.e. through a web server and the web server runs under a different user than your command line.
- 6
-
The output file you specified with --file=FILE cannot be written to. Please check that the path is correct and that the user you are currently logged in as has write permissions to that folder.