Support

Documentation

Chapter 4. Akeeba Backup Command Line Interface (CLI)

[Note]Note

This feature is only available when using Akeeba Backup on Joomla 4.0 and later.

[Important]Important

This feature is currently in BETA.

Akeeba Backup integrates with Joomla's CLI application (joomla.php) which made its first appearance in Joomla 4.0. This is a full-blown command line client for Joomla and its extensions, allowing us to provide a much richer experience than what was possible using the separate command line scripts we have been offering since 2010 and documented under backup automation.

Using the Joomla CLI client you can of course take backups but you can also manage all aspects of Akeeba Backup itself. You can import, export and configure backup profiles. You can get information about backups, access their log files, retry uploading them to remote storage if that failed during the backup itself, delete backup files or backup records and even configure all of the component options. Most commands allow some form of machine-readable content for their output and provide exit status codes, making it ideal for automation e.g. with an Ansible playbook.

Please note that restoring backups is not possible with the command line client. You need to use our standalone CLI tool called Akeeba UNiTE. Restoring a backup requires overwriting the current site. Due to Joomla loading some of its PHP files on-demand ("lazy-loading"), even when running under CLI, we can't offer a consistent backup restoration experience without running into the very real possibility that the restoration would fail because of Joomla lazy-loading a PHP file of the wrong version or the wrong path because the site has changed while running the restoration command. Akeeba UNiTE sidesteps this problem by being self-contained and running parallel to but outside of Joomla itself.

Also note that the Akeeba Backup Command Line Interface is only available on Joomla 4.0 or later and requires having the Console - Akeeba Backup plugin published. The requirement for Joomla 4.0 or later is due to the fact that the Joomla CLI application was not available in previous versions of Joomla. The requirement for the plugin has to do with how Joomla itself works under the hood to detect and make available third party commands for the Joomla CLI application.

Common conventions

You can access the Akeeba Backup CLI using the Joomla CLI application. This is the file joomla.php in your site's cli directory.

First of all, you need to know two things: how you can run PHP CLI on your server and the path to your site. If unsure, ask your host or system administrator. Assuming that you can run PHP on your server by typing /usr/bin/php and that your site's path is /home/mysite/public_html you can run the following command to list all available Akeeba Backup CLI commands:

/usr/bin/php /home/mysite/public_html/cli/joomla.php list akeeba

If you get an error reading

There are no commands defined in the "akeeba" namespace.

you will need to publish the Console - Akeeba Backup plugin on your site first. If you get a different error you need to make sure that the PHP command you are using is correct, it is in fact the PHP CLI (not PHP CGI) binary and that the PHP version it runs is the same you are using on your web site.

Please note that most servers have multiple PHP versions installed. It's possible that the PHP version you are accessing with the command you are using is different than the one you are using on your web site. If unsure, please do ask your host. If the first level support of your host is unsure do ask them to escalate to an engineer. Server engineers can give you the correct path for PHP; it's trivial for them but may be indeed beyond the training or information available to a first level support agent.

The commands listed are in the format akeeba:foo:bar, i.e. three parts separated by semicolons. The first part is called the namespace of the command and it's always akeeba for Akeeba Backup CLI commands. A keen observer may notice that the namespace for various Joomla CLI commands tends to be the component directory without com_ in front. We noticed that too and we're following the same convention. The other two parts further identify the command you need to run. For example, listing the latest backups taken with Akeeba Backup requires running a command like this:

/usr/bin/php /home/mysite/public_html/cli/joomla.php akeeba:backup:list

If you need a quick refresher on what each command does and/or what arguments and options it takes you can use the built-in help command on it:

/usr/bin/php /home/mysite/public_html/cli/joomla.php help akeeba:backup:list

All commands set the exit status code upon completion. Commands that executed successfully return an exit status of 0 (zero). Non-zero results mean that an error occurred while executing the command. The exit status reference can be found in the following sections of this documentation.

Some Akeeba Backup CLI commands accept a format parameter. This tells Akeeba Backup CLI which output format to use for the information it returns. The following formats are supported (not all format are supported by all commands; please consult the command reference further ahead in this documentation):

table, text

Human readable text. This is meant for humans to read. It's not very useful for automation.

json

The output is returned as a JSON string. You can feed this through commands such as jq or consume it in automation tools such as Ansible's json_query filter.

csv

The output is returned as CSV (Comma Separated Values) data. This can be fed to Excel, Apple Numbers, Google Sheets, LibreOffice Calc and other spreadsheets. It can be a very useful format for generating reports.

yaml
[Important]Important

You need to have installed and enabled the optional PHP YAML extension. This is not enabled by default on most servers. If the extension is not installed or installed but not enabled you will get an error.

The output is returned as YAML. This is a lightweight, structured, machine-readable data format which can be consumed by automation tools.

var_dump

The output goes through PHP's built-in var_dump() function. This is mostly useful for debugging and we may ask you to use it if you request support and we suspect something odd is going on with the output data.

var_export

The output goes through PHP's built-in var_export() function. It can be used as-is in a PHP script's variable assignment. This can be useful for home-grown automation scripts written in PHP.

count

Returns the number of items which would be output. This is useful for automation when used with the various akeeba:*:list commands. For example, if you need to know whether there are any backups taken the last week you can use the akeeba:backup:list command using the --from and --to options to limit the search within the last week and --format=count to get the number of backups taken in that period. If it's 0 no backups were taken. If it's non-zero this many backups were taken.