Support

Documentation

Options
Prev Chapter 2. Using Remote CLI Next

Options

Under any circumstances you can append -m or --machine-readable to the end of the command line to instruct Remote CLI to use a machine-readable output format. If you omit it, a human-readable format will be used instead (default).

Using the option --nocolor will skip the generation of color escape sequences. The default behaviour of Remote CLI is to color-code its output for easier reading. However, some terminal emulators, like Windows' command prompt application, do not support them and display them as verbatim text. This can be confusing, therefore the use of --nocolor is strongly recommended.

Moreover, you can specify the --license parameter to display the text of the GNU General Public License version 3, under which the software is distributed. In this case, the action and all options will be silently ignored. This has the same effect as specifying the license command.

If you have a host with a self-signed certificate, or a certificate signed by a non-public certificate authority, you can use the --certificate=/path/to/certificate.pem option, where /path/to/certificate.pem is the full filesystem path to a PEM-formatted certificate. This certificate will be considered a valid certification authority for the purposes of Akeeba Remote CLI. The practical use case for that is intranets, local servers and testing environments, typically using self-signed certificates.

If something is not working, use the --debug option. This will include much more detailed output, including what Akeeba Remote CLI sends to and receives from your server. This information will also be stored in the file remotecli_log.txt in the current working directory. Please include this file when requesting support with Akeeba Remote CLI.

Each action can be used with one or several options. Some of them are mandatory for the correct operation of Remote CLI. The following sections detail the parameters which can be used with each option. All actions require the following mandatory options:

host

The URL to the Akeeba Backup / Akeeba Solo JSON API Endpoint URL which can be read off the Schedule Automatic Backups page of our backup software.

Alternatively, you can use the URL to your site's root, without a trailing slash, e.g. http://www.example.com.

secret

The secret key, as defined in Akeeba Backup or Akeeba Solo.

You can see the Secret Key in our backup software's Schedule Automatic Backups.

[Important]Important

We strongly advise you to use only lower and upper case Latin letters and numbers (a-z, A-Z, 0-9) in your secret word, as many servers will refuse to work with secret words containing special characters.

Below you can find the options required by each command:

help

No extra options are used.

license

No extra options are used.

php

No extra options are used.

test

No extra options are used.

[Note]Note

Akeeba Backup for Joomla versions older than 3.6.0 will only report their version, but not whether they are the Core or Professional version. This feature is missing from the Remote JSON API of these legacy versions released well over a decade ago.

backup

profile

The numeric profile ID you want take a backup with. If it is not specified, a backup with the default profile (#1) will be taken. Please see the profiles command for an easy way to list profile names and IDs.

description

An optional description of your backup. Put it in double quotes, i.e. --description="My backup description". If not specified, the default backup description (the one with the date and time of the backup) will be used by Akeeba Backup automatically.

comment

An optional backup comment. Put it in double quotes, i.e. --comment="My backup comment". If not specified, no comment will be stored with your backup.

download

If you specify --download or -d, the produced backup archive will be downloaded to your computer. In this case, please refer to the next section for its required parameters. You can also specify --delete or -D together with --download / -d in order to delete the backup archive after it has been downloaded to your PC.

When using the --download option you will need to provide the same options as when using the download command, except for --id.

download

id

The numeric backup ID to download (see listbackups). Note: when you use the --download or -d switch with the backup action you must not use this option. In all other cases, this option is mandatory.

dlmode

Can be one of http, chunk or curl

http

instructs Remote CLI to download the backup archive through HTTP, similar to what you get by clicking the download links in the "Manage Backups" (formerly "Administer Backup Files") page of Akeeba Backup. Even though it is the simplest method, it may cause corrupted downloads of backup archives over 10-20MB on some shared hosts.

Files are transferred unencrypted with this method. You are advised to only use this if your server is using HTTPS or with JPS (encrypted) archives only.

chunk

works similarly to http, but is designed to work with larger backup archives. It tries to download 1Mb at a time, in order to work around server restrictions on HTTP download. However, on a few shared hosts this will cause the download to fail with a timeout error, memory outage error or an Internal Server Error (HTTP 500 error).

curl

is the recommended method and can be used to download the backup archive over FTP, FTPS or SFTP. The only downside is that it needs some configuration (see the dlurl option below).

If you are using plain old FTP (not FTPS or SFTP) the files and login credentials are transferred unencrypted. You are advised to never use this method with plain old FTP (not FTPS or SFTP) for security reasons.

dlpath

Specify the path to save the downloaded file. For example, --dlpath="c:\User\Myuser\Downloads" on Windows, or --dlpath="/home/myuser/Downloads" on Linux, Mac OS X and other UNIX-based operating systems.

dlurl

This option is only required if you are using the curl download method. In this case, it tells Remote CLI how to connect to your site in order to download the backup archives.

If you are using FTP, you have to specify something like --dlurl="ftp://username:password@hostname:port/path/to/output/directory"

Username and Password are your FTP username and password. Hostname is the FTP server's host name. Port is the numeric TCP/IP port (normally it's 21, ask your host). The /path/to/output/directory is the FTP path to your output directory. In order to figure out the latter, please use FileZilla to connect to your site and navigate to the backup output directory (for example, on Joomla 4 and later this is administrator/components/com_akeebabackup/backup). Copy the path shown above the right-hand folders pane. That's the one you want.

Example:

--dlurl="ftp://myuser: [email protected]:21/public_html/administrator/components/com_akeebabackup/backup"

[Important]Important

FTP is an unencrypted protocol. It is trivial for a third party to snoop into your connection and find the username and password you are using to connect to your server. We very strongly recommend using SFTP which is a file transfer protocol implemented over the very secure SSH remote server connection protocol. As a second best, you can use FTPS which is an encrypted version of FTP (exactly the same way HTTPS is an encrypted version of HTTP).

delete

id

The backup record's ID that you want deleted. Please see listbackups below.

deletefiles

id

The backup record's ID that you want deleted. Please see listbackups below.

profiles

This command has no options. It will simply return a list of profile IDs and descriptions.

profileexport

If you want to export the profile to the standard output (STDOUT), e.g. to pipe it through a different programme, please use the command line options -m --silent -- and do NOT use the --debug or --file options. The -m option tells Remote CLI to use machine readable output. The --silent option tells it to skip the copyright header output. The -- (two dashes) option tells it to output the exported profile to the standard output.

id

Required. The numeric ID of the profile you want to export.

file

The absolute filesystem path of the file where the exported profile will be written to. This only applies if you have not used the -- option. If omitted the profile will be exported to the file profile.json in the current working directory.

[Note]Note

This feature is not available on Akeeba Backup for Joomla versions older than 3.6.0 and will result in an error about a missing API method.

profileimport

If you want to import the profile from the standard output (STDIN), e.g. to pipe it in froma different programme, please use the command line options -m --silent -- and do NOT use the --debug or --file options. The -m option tells Remote CLI to use machine readable output. The --silent option tells it to skip the copyright header output. The -- (two dashes) option tells it to get the exported profile data from the standard input.

file

The absolute filesystem path of the file where the exported profile will be read from. This only applies if you have not used the -- option.

[Note]Note

This feature is not available on Akeeba Backup for Joomla versions older than 3.6.0 and will result in an error about a missing API method.

listbackups

from

(Optional) From which record you want to start the listing. If not specified, 0 is assumed, showing the top results (latest backup records).

to

(Optional) Up to which record you want the listing to go to. If not specified, 50 is assumed, therefore showing the latest 50 backup records.

backupinfo

id

The backup record's ID whose info you want displayed. Please see listbackups above.

update

There are no options. Calling this action will check if an update is available and, if there is, will install it automatically on your site.

[Important]Important

This feature IS NOT available on Joomla! 4 and later versions. Extension updates are handled by Joomla! itself, not Akeeba Backup. Please refer to Joomla!'s documentation for information on updating extensions.

When you use this feature against a WordPress site the update will use Akeeba Backup's built-in updater instead of WordPress' plugin updater. To use WordPress' plugin updater please use WP-CLI instead.

Prev Up Next
Chapter 2. Using Remote CLI Home Configuration files