Support

Documentation

Chapter 2. Using Remote CLI
Prev   Next

Chapter 2. Using Remote CLI

Table of Contents

Usage
Options
Configuration files
Endpoints and API versions per backup software version
Walkthrough

Usage

Using the PHAR file

The traditional way to use Remote CLI is as a command line script running on your machine.

Remote CLI requires a command line version of PHP (a.k.a. PHP-CLI) to be installed on your machine. In the command line below, please substitute php with the full path to your PHP CLI executable file. On most Linux and macOS systems, you don't need to specify a path, just php will do as the executable file is already in the path. On Windows, however, you most likely need to specify a full path.

[Tip]Tip

The PHP project provides an installer of PHP for Windows which can install PHP for you and place the php.exe binary in your path. For sanity's sake, we recommend you to install PHP in c:\PHP and put remote.phar in there as well. This is the easiest way to be perfectly sure where everything is installed!

[Important]Important

Remote CLI requires PHP 8.0 with the optional phar and curl extensions installed and activated. This is the default setup of PHP in most cases.

After downloading remote.phar (the Remote CLI executable PHP archive) from our site you can use Remote CLI from the command line of your operating system with a command like this:

php remote.phar actionName --host=hostName --secret=secretKey [options]

php is the path to your PHP CLI executable. If this is not in your path or you are not sure, please ask your host or your system administrator.

Using the Dockerized version

If you are using Docker you can make use of the Dockerized version of Remote CLI:

docker run --rm akeebaltd/remotecli actionName --host=hostName --secret=secretKey [options]

The Dockerized version is self-contained, using the latest version of PHP at the time we built the container image. It's much simpler to use since it does not require installing or configuring anything on your host machine. Moreover, it's self-updating. The command line above always tries to use the latest version of Remote CLI we have published in Docker Hub.

[Warning]Warning

There's a caveat. You can not use the Dockerized version with local servers i.e. anything which resolves to an IP address only routable by the host machine. If you want to try our Remote CLI locally you have to use the PHAR file.

What are all these options?

hostName is 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.

secretKey is the Secret Key you have defined in the component Options (Akeeba Backup for Joomla!) or the System Configuration (Akeeba Backup for WordPress, Akeeba Solo) page of the backup application.

The options which are required for each action are described in the Options chapter of this documentation.

For practical examples, or if you want to find out how to automate backing up and downloading the backups of your site, please consult the Walkthrough chapter.

actionName can be one of:

help

Prints an overview of the commands and available options.

license

Displays the license of the software and quits.

php

Prints information about the execution environment of Akeeba Remote CLI (NOT your site!). Use this when submitting support requests so we know what is going on with your execution environment.

test

Tests whether Remote CLI can connect to your site. If it can not, it will tell you why.

backup

Performs a backup. It can (optionally) download the backup archive and delete it from the server afterwards.

download

Downloads a backup archive and can optionally delete it from the server afterwards

deletefiles

Delete backup archives from the server

delete

Deletes backup archives and the associated backup record from the server

listbackups

Lists the latest backup records

profiles

Lists the profile IDs and descriptions

profileexport

Exports a backup profile as a JSON file, or a JSON string to the standard output. The generated JSON is the same you get as when exporting a backup profile from Akeeba Backup and Akeeba Solo.

profileimport

Imports a backup profile from a JSON string in the standard input, a JSON string given as a parameter, or a JSON file (exported by Akeeba Backup, Akeeba Solo, or Akeeba Remote CLI).

backupinfo

Shows detailed information about a backup record

update

Upgrades Akeeba Backup on the server, if there is an update available

[Warning]Warning

Before you can use Remote CLI with your site, you will need to enable the remote API in Akeeba Backup / Akeeba Solo. In order to do that, go to Akeeba Backup / Akeeba Solo and click on either the Options button in the toolbar (Akeeba Backup for Joomla!) or the System Configuration button towards the bottom of the page (Akeeba Backup for WordPress, Akeeba Solo).

You will have to set Enable front-end and remote backup to Yes. You will also need to supply a Secret Key of your liking. This is the password to connect to your site over Akeeba Backup's Remote API. Due to several issues which have to do with server configuration, we strongly recommend using only alphanumeric characters (a-z, A-Z, 0-9), dash and underscore in your Secret Key. Other characters may lead to inability to connect to your site. Use something long and complex.

Prev   Next
Chapter 1. Welcome Home Options