Below we will see how to get Remote CLI interface your site, make sure Akeeba Backup is up to date, run a backup and automatically download the backup archive to your PC.
In this fictional example, the following assumptions are made:
Your site can be found at http://www.example.com and the
secret word is 0Lsp-MjOSLvUL8VuM1h9T2zWfM4EGqMA. The
backup archives are stored in the default output directory for Joomla 4
and later sites
(administrator/components/com_akeebabackup/backup).
The site's FTP host is ftp.example.com and its username and
password are example and test
respectively. The site is under the public_html
directory. We also assume that the PHP CLI executable is already in your
path.
Connection test
We begin by making sure that Remote CLI can access our site:
php remote.phar --action=test --host=http://www.example.com --secret=0Lsp-MjOSLvUL8VuM1h9T2zWfM4EGqMA
You should see something like this:
Akeeba Remote Control CLI 3.0.0-dev202303140829-reva1cbd8e (2023-03-14) Copyright ©2006-2023 Nicholas K. Dionysopoulos / Akeeba Ltd. -------------------------------------------------------------------------------- This program comes with ABSOLUTELY NO WARRANTY. This is Free Software and you are welcome to redistribute it under certain conditions. Use command license for details. -------------------------------------------------------------------------------- Successful connection to site
The last line tells you that the connection worked. However, if something goes wrong, you might get one of these error messages:
Error #42 - Authentication error (invalid Secret Word). Please check the secret word, make sure it doesn't have any whitespace you missed. Clear any site or external caches, making sure Akeeba Backup's URL isn't cached. : Your secret word appears to be wrong, or the Remote JSON API is disabled. Go to Akeeba Backup's / Akeeba Solo's Options (Joomla) or System Configuration (WordPress, Akeeba Solo) page, make sure Enable JSON API is set to Yes, and enter a secret key of your liking. We strongly recommend using only a-z, A-Z and 0-9 to work around limitations with some hosts. The click on Save & Close.
![[Important]](/media/com_docimport/admonition/important.png) | Important |
|---|---|
|
Applicable to Joomla sites only. If you did not enable the remote JSON API and/or enter a secret word yourself, through the component's Options page, please note that the third party software which did that for you may have done so in a way which is not compatible with your current version of Joomla, or Akeeba Backup. If this happens, kindly note that it's not a bug in our software and we are objectively unable to do anything about it except give you the following instructions to do thing in the only way we have a modicum of control and can help you with, i.e. the only supported way. Go to Components, Akeeba Backup, Options, Front-end Backup and make sure that:
Then click on Save & Close. This is a VERY important step! It clears Joomla's internal component options cache. If this didn't work for you go to System, Maintenance, Clear Cache and click on the Delete All button in the toolbar. |
Error #36 - We cannot find a way to connect to your
server. It seems that your server is incompatible with Akeeba Remote
Control CLI. : Check that you are using the correct endpoint
URL with the --host option, including the http/https
schema prefix.
Also note that some SEF and security plugins may be blocking the Remote JSON API calls to your site. In this case, you won't be able to use Remote CLI.
| Important |
|---|---|
|
If your host name, secret key or any other option contains non-alphanumeric characters (anything except 0-9, a-z, A-Z, slash, backslash, dash, dot and underscore) you MUST enclose the option value in double quotes. For example, --secret=ab=gt%6 will not work, but --secret="ab=gt%6" will do. If you get connection errors despite having set the correct host name and secret key, try using double quotes around all of your option values. |
Error #102 - You need to install a newer version of Akeeba Backup / Akeeba Solo on your site: Make sure that you are using an Akeeba Backup / Akeeba Solo version which is not too old. Keeping in mind that Remote CLI supports versions released as far back as mid-2011, a version that's “too old” is very likely to be installed on a site with critical vulnerabilities which should no longer be online.
Taking a backup
The following command will take a backup (without downloading it to your local PC), using backup profile #1:
php remote.phar --action=backup --host=http://www.example.com --secret=0Lsp-MjOSLvUL8VuM1h9T2zWfM4EGqMA --profile=1
You should see a long list of output coming through, detailing the backup progress. In the end it should read:
Backup finished successfully
And that's it! You now have a backup. Since it's useless without downloading, let's try downloading it.
Taking and downloading a backup
There are many ways to download a backup archive. We'll explore only two, using HTTP (not recommended on most sites) and FTP.
First, let's try HTTP. The command line to achieve that is the same as the backup command line, with the --download, --dlmethod and --dlpath added:
php remote.phar --action=backup --host=http://www.example.com \
--secret=0Lsp-MjOSLvUL8VuM1h9T2zWfM4EGqMA --profile=1 \
--download --dlmode=http --dlpath="c:\Downloads"
![[Warning]](/media/com_docimport/admonition/warning.png) | Warning |
|---|---|
|
The command line above should be entered ON A SINGLE LINE. We
have added the Linux / nacOS line continuation characters
( |
This will take a backup and then download it to C:\Downloads (or anything else you specify with --dlpath) using the HTTP download method. After the "Backup finished successfully" messages you will also see many download lines and a "Archive downloaded successfully". If that fails, you'll have to use the FTP mode.
First, you need to know the following information about your site:
-
FTP hostname. We'll assume it's
ftp.example.comfor this example -
FTP username and password. We'll assume it's
fooandbar, respectively -
The FTP path to your backup output directory. We'll assume it's
/public_html/administrator/components/com_akeeba/backup.![[Tip]](/media/com_docimport/admonition/tip.png)
Tip In order to find this directory, connect to your site using FileZilla. Navigate inside the folder Joomla! is installed in. Usually it's a directory named
public_html,htdocs,wwwor something similar. If unsure don't ask us, ask your host. Then navigate to your backup output directory. The default isadministrators/components/com_akeeba/backup. If unsure, check your Akeeba Backup Configuration page. Now, on the right-hand pane you will find the FTP path, right above the folders list. Copy this; it's the path we need.
Then, modify the command line to read:
php remote.phar --action=backup --host=http://www.example.com --secret=0Lsp-MjOSLvUL8VuM1h9T2zWfM4EGqMA --profile=1 --download --dlmode=curl --dlpath="c:\Downloads" --dlurl="ftp://foo:bar@ftp.example.com/public_html/administrator/components/com_akeebabackup/backup"
| Warning |
|---|---|
|
The command line above should be entered ON A SINGLE LINE. We
have added the Linux / nacOS line continuation characters
( |
One final note. After you download the backup archive, it's a good idea to delete the copy on the server for security reasons. Just append --delete to the command line to achieve that. For example, the command line above will become:
php remote.phar --action=backup --host=http://www.example.com --secret=0Lsp-MjOSLvUL8VuM1h9T2zWfM4EGqMA --profile=1 --download --dlmode=curl --dlpath="c:\Downloads" --delete --dlurl="ftp://foo:bar@ftp.example.com/public_html/administrator/components/com_akeebabackup/backup"
| Warning |
|---|---|
|
The command line above should be entered ON A SINGLE LINE. We
have added the Linux / nacOS line continuation characters
( |
That's it!
Automating the whole lot
If you want to automate updating Akeeba Backup, taking and downloading backups, you can simply create a batch/script file and use your Operating System's scheduling features to run it at predefined intervals. We suggest taking a look at the following tutorials:
As for the batch/script file, all you have to do is to include the commands above in a .BAT (Windows) or .sh (Linux, Mac OS X) file. For example, a Windows batch file (backup.bat) looks like that:
REM IMPORTANT! Before running Remote CLI, you have to change the current REM directory to wherever remote.phar is located in. In this example, we REM will assume that you followed our advice and put it in c:\PHP C: CD c:\PHP REM The following line takes and downloads a backup - REMOVE THE LINE REM BREAKS WHEN COPYING THIS SCRIPT TO YOUR SYSTEM, OTHERWISE IT WILL REN NOT WORK!!! php-cli.exe remote.phar --action=backup --host=http://www.example.com --secret=0Lsp-MjOSLvUL8VuM1h9T2zWfM4EGqMA --profile=1 --download --dlmode=curl --dlpath="c:\Downloads" --dlurl="ftp://foo:[email protected]/public_html/administrator/components/com_akeebabackup/backup" --delete
Note that we assume that the path to PHP is c:\PHP\php-cli.exe and you followed our advice and also copied Remote CLI (remote.phar) into C:\PHP. That's it! You can now use the Scheduled Tasks feature of Windows to make this file run whenever you want, essentially having an always up-to-date copy of Akeeba Backup installed on your site, take automated backups of your site, download them to your PC and remove them from the server. All you need to do once you set this up is to remember to leave your PC turned on for the scheduled task to run. Easy peasy!