Table of Contents
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.
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]](/media/com_docimport/admonition/important.png)
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.