20 minutes reading time (4058 words)

Joomla 4: A Powerful CLI Application

June-CLI

Shipping with Joomla 4 is the new and improved CLI (Command-Line Interface) that sits at the Joomla core. You can now carry out maintenance tasks without even logging into your website. Let's find out how.

‘One Joomla for all’, that’s a bold statement. But, it really is true. On one hand, Joomla’s a user friendly CMS with an intuitive admin panel for beginners and occasional users. While, on the other hand, Joomla’s a powerful CMS application that’s full of features for the advanced user. Therefore, Joomla’s perfectly suited for all web applications, from a simple 5 page business website, to a complex E-commerce solution for a busy online store.

In fact, if you look through the JED (Joomla Extension Directory) there’s an extension available for almost anything you’d ever want to produce. If there’s no extension available for your planned website, don’t worry. There are extensions available to help you build your own custom, one-off, Joomla extension.

You could even start from scratch and use Joomla’s standard, and well structured, framework to build your own extension upon. If successful, you could then add it to the JED and let others use your extension.

How cool would that be?

One way that Joomla, and in particular Joomla 4, makes this possible is the new and improved CLI (Command-Line Interface) that ships with the Joomla 4 core.

So, let’s take a look at the CLI and find out what you could use it for.

As the years go by, and technology improves, Joomla’s making it easier and easier to carry out certain tasks without even having to login to the admin dashboard. We’ve spoken about Joomla’s Task Scheduler recently, which allows you to set up Cron Jobs for repetitive tasks from within Joomla itself. There’s also the Joomla API, which can be used to control Joomla from a remote source/website. There’s also Joomla’s CLI.

Joomla’s CLI is a way to connect to your Joomla website and carry out tasks from a remote terminal, such as SSH from your website hosting control panel.

This is particularly useful and time saving if you run several websites from the same hosting account.

Let’s begin by understanding what a Command-Line interface is:

What is a Command-Line Interface?

A command-line interface (CLI) is a text-based user interface (UI) that is used for running software, managing computer files, and interacting with a computer/server. The CLI allows the user to respond to visual prompts by typing individual commands in an interface, and then receive responses in the same way. Windows Command Prompt is a Command-Line Interface you'll already be familier with.

 

what is a cli

 

Users respond to the visual prompts by typing the command in a specified row and receiving the reply from the operating system. This software provides the prompt, users respond, and then an app reacts sequentially to commands. Through this command-and-response interaction, a user can issue a set of commands that are executed by a system or an application like Joomla.

The prompts and commands available depend on your operating system and the specific command-line interface, but there can be hundreds, if not thousands, of different commands executable. Many of the commands are the same between the different platforms out there, and you may well be familiar with some of them. However, there are some commands that are particular to the specific CLI and application you use.

You may already be familiar with various apps in which you can use a command-line interface. Common applications include the ‘Terminal’ on Macs, in windows it’s known as the ‘Command Prompt’, and on your website server in the Control Panel it’s referenced as SSH.

Entering text commands to control your app may seem daunting at first, but it’s a skill well used in Linux and other unix based operating systems. It’s also a skill that’s worth learning if you want to become a website developer. Once you become familiar with the terminology of using a CLI, there are other uses that you will come across as you hone your skills.

 

For Example: 

Using Node.js to make a web app in an editing suite like Jet Brains Webstorm.

Or,

Running commands for your clients, on Amazon’s Elastic Compute Cloud (Amazon EC2) instances using a remote terminal program such as PuTTY or SSH.

 

However, there are GUI-based ‘shells’ available that are considered easier to use by beginners. Although, strictly speaking, the term shell is usually used to describe a command-line interpreter. A shell may be any program comprising the UI, including completely graphical-oriented ones.

Where is Joomla’s CLI?

Unlike many other Joomla extenstions which you can find in the admin area of your Joomla website, Joomla's Command-Line Interface is part of the core. So, there are no settings to fiddle with, it's just there and working quietly in the background of your Joomla website.

How Do I Use Joomla’s CLI?

 

let me explain

 

First things first. Before you can access the Joomla CLI, you’ll need to create a way to connect directly to your website’s host without actually logging into your Joomla, or your Host’s Cpanel.

Cpanel recommends using a desktop application called ‘PuTTY’ if you run Windows on your computer, although if you run Windows 10, or later, it has its own Windows SSH Client which you can access from the Command Prompt.

To access the Command Prompt, open the Run dialog box, by hitting the Windows key + r. Then, in the Run dialog box, type cmd and then click OK to open a command prompt window.

If you use Linux, or run a Mac, you may well already have software installed to connect directly to your website server. For the basis of this article I’ll assume you’re running Windows, as I am.

Each way of accessing your website server’s similar, but you’ll have to set up SSH access on your website hosting's Control Panel first before you can connect to Joomla’s CLI.

For this article I’ll be using ‘PuTTY’ as I’m on a Windows 8 machine, and there are several quirks I’ve had to solve along the way, so I’ll share some those with you as well to save you some time setting up SSH access to your website’s server.

So head on over to the ‘PuTTY’ download page and install ‘PuTTY’ on your machine if needed.

 

Joomla 4 CLI Installing PuTTY

 

The next step is to activate SSH on your web hosting’s Cpanel, or other web hosting control panel, Plesk, for example. We’ll stick with Cpanel as it’s the most popular.

Set Up Your Access Keys

To use SSH, you’ll need to set up and manage a pair of public/private keys in Cpanel. The instructions seem complicated at first, but they’re really quite straightforward. There's a good article on the A2 Hosting website with lots of information for different operating systems. The instructions may differ slightly from host to host, so I’d encourage you to research this for your specific use case.

 

Joomla 4 CLI SSH Private Public Keys

 

It’s also worth remembering that you’ll have to download your private key to your computer, so remember where you put it. If you use a native SSH client in Mac/Linux, or Windows 10, you should save the key file to:

Mac/Linux: /home/username/.ssh directory. (Replace username with your own username.)

Windows 10: \Users\username\.ssh directory (Replace username with your own username.)

This is so your terminal program knows where to find your key.

If you use ‘PuTTY’ then just remember where it’s downloaded as you’ll need to reference it in ‘PuTTY’s’ settings.

Set Up PuTTY TO Access Your Server

If you installed ‘PuTTY’ already, find the desktop icon and open the program. If not, install it now. The desktop icon to open PuTTY looks like this:

putty icon

Setting up PuTTY to access your server isn't difficult, there are only 3 things you need to enter. These may vary slightly depending on your website host, so you’ll have to check this for your own circumstance. In my case, I need to do the following:

 

  1. Enter the username for my hosting account along with the domain I want access to. This needs to be written in the ‘Host Name (or IP Address)’ field in the ‘Session’ category tab.

putty settings 1

 

  1. Next, in the ‘Port’ field, type in your SSH connection port number. The default is 22, but many hosts change this to boost connection security. Mine is 7822.

putty settings 2

 

  1. Now, you need to open a new tab in the category tree, scroll down to ‘SSH’, then open ‘Auth’. At the bottom of the tab, browse to the location you saved your downloaded SSH Private Key to, highlight it, and click ‘Open’.

putty settings 3

 

  1. Go back to your Session tab and in the ‘Saved Sessions’ field add a memorable name to it. Then click the ‘Save’ button.

putty settings 4

 

  1. You’re now ready to connect to your website hosting’s SSH Client with ‘PuTTY’. You can either double click on your saved memorable name, or click the open button.

putty settings 5

 

If all’s gone according to plan, you should now see PuTTY’s terminal window. It should look something like this:

putty terminal

 

The terminal window should look similar from this point onwards, regardless of the operating system or SSH client you use. The commands you issue will also be the same. So, I’ll move forward just referring to the ‘Terminal’.

The next step is to enter the password you created when you set up the public/private keys in Cpanel. If you don’t do this within a set period of time, your website server will close the connection to your terminal and you’ll receive an error message like this:

 

putty error

 

Here’s one of the quirks of using a terminal to connect to your website server. When entering your password, nothing is displayed! No stars, no dashes, nothing. I also noticed that I could not copy paste my password into the terminal window either (although this may be particular to ‘PuTTY’).

I’m an advocate of super-long strong passwords, but this could be an exception to the rules! Although I’d still advise you to follow your Cpanel’s advice as to the strength of the created password. As mentioned in previous articles, john123 is not good enough. Depending on your SSH keys, your operating system, and your Cpanel instance, you may only have to enter your password for the initial connection. But subsequent sessions will not ask for your password. Which may or may not concern you.

Using your Terminal to access Joomla’s CLI

So, go ahead and type in your password and, when finished, click ‘Enter’ on your keyboard.

 

putty logged in

 

If all’s gone well, you should see a new line of information that looks like:

 

username@123host [~] #

 

This is the root directory for your website files. Depending on your website hosting package, this will probably be in your ‘public_html’ folder.

If you’ve installed Joomla to a different directory, you’ll need to navigate to that directory next. This is also true if you run more than one instance of Joomla on the same hosting package.

 

It’s time to dust off your old DOS handbook!

 

In my example, my domain designwebs.co.uk is in a folder that’s outside on my public_html folder like so:

If you remember your DOS commands, you can simply type cd [your folder name here], so in my example cd desighwebs.co.uk where the cursor is flashing in your terminal window. CD is short-code and simply means “Change Directory”.

 

change directory in terminal

 

I’m now in the correct directory in which to operate the Joomla CLI. If you want to check you're in the same directory as Joomla, you can simply type ‘dir’ (which is short for 'directory') at the prompt and all the familier Joomla files and folders in that directory will be listed. Like so:

 

terminal joomla directory

 

Let’s use Joomla’s CLI

It seems to have taken a long time to get to this point, but it shouldn’t take too long once you’ve mastered the use of your terminal window or an SSH client like ‘PuTTY’. The whole point of the Joomla CLI is to speed up tasks, especially those that involve waiting for those tasks to complete. Backing up your website is a good example of using Joomla’s CLI. We’ll get into that later.

So, let’s make our first call to Joomla’s CLI and make sure we’re connected and everything’s working as expected.

The standard format to connect to Joomla’s CLI begins with:

php cli/joomla.php

Although if you enter the cli directory (cd my-website-folder-name/cli), rather than working from Joomla’s root directory, you can use:

php joomla.php

Instead.

The Updated Joomla CLI documentation gives more information about the tasks you can complete using the Joomla CLI.

A good task to test our connection would be to find out what version of Joomla the website is running on.

So, at the command prompt, type in:

php cli/joomla.php core:check-updates

And hit enter.

 

terminal check joomla version

 

PuTTY Note:

If you copy a Joomla CLI command with your copy/paste function, all you need to do to paste it into PuTTY’s terminal is a single right mouse click as the cursor.

 

If you’re connected, and everything’s working, you’ll be rewarded with a message detailing the version of Joomla that your website is running on.


terminal joomla cli version


Joomla Command-Line Interface (CLI) Format

When you enter commands in your terminal to access Joomla’s CLI, there is a set format.

Which may comprise 2 or more parts, depending on what you want to do, and how much information you require back.

Each Joomla component developer will be able to offer varying amounts of control and data retrieval for their software based on Joomla’s CLI. An early adopter of this Joomla functionality is Akeeba, so using Akeeba Backup as an example, you can control almost all functionality from your terminal.

The following CLI command asks for the backup data held for a specific backup:

php cli/joomla.php akeeba:backup:info 1 --format=json

So, let’s break it down, so it means something.

 

php cli/joomla.php

The URL needed to activate Joomla’s CLI

akeeba

A unique name for the command 

backup

The particular software

info

The action you’d like to complete

1

An argument for the command (if required)

--format=json

An option, or two. In this case the output of our CLI command will be in a Json format.

 

Make sure to take note of the spaces and colons in the command so that it functions properly.

akeeba backup info output

Joomla’s CLI commands follow a similar principle of arguments and options, but as they are ‘core’ commands, they are a little simpler.

Currently, Joomla’s CLI commands fall into 11 categories

Cache, Config, Core, Database, Extension, Finder, Scheduler, Session, Site, Update and User.

Each having their own functions.

For Example:

php cli/joomla.php core:check-updates Checks for Joomla updates

php cli/joomla.php site:down Put the site into offline mode

Adding options to the parameters of the CLI command can help to narrow down your results. For example, if you want to find what extensions they used to build your website, you would use the command:

php cli/joomla.php extension:list

But, if you only wanted to find specific extensions of a certain type, related to languages, for example, you would use the same command but add the option --type=language:

php cli/joomla.php extension:list --type=language

Which would return the following information:

Installed extensions.

=====================

 ----------------- -------------- --------- ---------- --------

Name Extension ID Version Type Active

 ----------------- -------------- --------- ---------- --------

English (en-GB) 222 4.1.4 language Yes

English (en-GB) 223 4.1.4 language Yes

English (en-GB) 224 4.1.4 language Yes

 ----------------- -------------- --------- ---------- --------



Tip:

If you type in php cli/joomla.php at the command prompt in your terminal, you will get a list of all Joomla CLI commands and descriptions.

Let’s Start Using Joomla’s CLI

We’re going to run 4 basic maintenance tasks that you should complete regularly on our Joomla website. All from a terminal, without logging into Joomla’s back-end admin. We’re going to use 4 simple CLI commands to accomplish these tasks.

First, we need to gather the commands we will use. You can find current Joomla CLI commands in the Cheat Sheet below. As Akeeba Backup is the most widely used Joomla Backup extension, we will use that to take a backup.

The CLI commands we need are:

php cli/joomla.php update:extensions:check

php cli/joomla.php akeeba:backup:take

php cli/joomla.php extension:discover:install

php cli/joomla.php cache:clean

If you’re not already, login to your terminal of choice and make sure that you’re in Joomla’s root directory.

Task One: Check for extension updates

Enter php cli/joomla.php update:extensions:check at your terminal command prompt.

 

terminal check for joomla extention updates

In my case, no updates were available to install. The success message is shown in green. I’d say the time taken for this command to execute was less than 3 seconds.

Task Two: Take a backup

It’s now time to take a backup with Akeeba Backup. Enter php cli/joomla.php akeeba:backup:take at your terminal command prompt.

 

terminal akeeba backup

Taking a backup obviously takes a little longer. During the backup process, the progress is detailed in the terminal window in much the same way as you see in Joomla’s admin backend.

The success of the backup is shown in green. From the timestamps, you can see that it only took 1 minute 10 seconds to complete. Which is pretty good.

Task Three: Install extension update

It’s time now to install any extension updates. Enter php cli/joomla.php extension:discover:install at the terminal command prompt.

 

terminal install extension updates

In my case, everything is up to date, so nothing to install. If this is the case, the CLI gives advice on what you could do instead. In this instance, the Joomla CLI suggested it try to run the command extension:discover. This works in the same way as running the ‘install > discover’ option from your System Dashboard.

Task Four: Clear Joomla’s Cache

Lastly, we will clean up Joomla’s cache. Enter php cli/joomla.php cache:clean at your terminal’s command prompt.

 

terminal cache clean

Once the cache’s been emptied of its junk, you’ll again see a green success message.


Error Messages

If you make a typo while entering your CLI command, or enter an unrecognised command, you will receive an error message in red. The message will contain a little useful information to help you work out what went wrong. You can see in the image below it says:

Command “cache:clea” is not defined

The command “cache:clea” does not exist

Of course, my typo referencing ‘cache:clea’ doesn’t exist in the Joomla CLI, therefore it’s not defined in an action to carry out. Thus it throws an error.

 

terminal error messages

 

Check Akeeba Backup in Admin

It’s not always going to be possible to check whether a CLI command was actually initiated, without some digging in Joomla’s files and settings. But, some extensions make it easy. Let’s look at Akeeba Backup again. If you login to your Joomla admin panel and navigate to Akeeba Backup’s Control Panel, you will see the ‘Backup Statistics’ panel on the right-hand side. Here you can see that the last backup was initiated from the Command Line. It also gives details about the backup taken and the time it was taken.

 

joomla admin akeeba backup


What Are The Benefits Of Using Joomla’s CLI?

Like many topics discussed here in the Joomla magazine, there’s a lot more going on under the hood than there’s time or space to detail here. As with many topics, the ‘surface has just been scratched’ on this updated Joomla 4 feature.

I think the single biggest benefit of getting to grips with the Joomla Command-Line Interface is how quick it is to carry out those necessary tasks. From start to finish the four tasks detailed above took around 2 minutes, and that included starting up the ‘Putty’ terminal, connecting to my server via SSH, manually typing in the login password and copy/pasting each of the four commands, in turn.

If you multiply doing those same tasks over several websites, that would be a lot of time saved.

For advanced users, the command line and terminal give you the opportunity to automate repetitive tasks over multiple websites you have full access to. You can cycle through their directories and execute the same Joomla CLI command against them, quickly and easily.

Imagine the time it would take to manually login to Joomla’s admin and run Akeeba Backup individually over 100 different websites in your portfolio?



“ That’s the whole point of a command line application. It is very conducive to infinite customisation. Combined with something like Ansible it can even be used to execute commands across a fleet of hundreds of servers running thousands of sites.

Command-line tools work together to give you superpowers. “

Quote: Nicholas @ Akeeba



Personally, now I’ve set up ‘PuTTY’ I’m going to add SSH access to all of my websites and run those updates, backups and cache cleans every time I receive one of those ‘This is sent from your website’ update emails that clog up my inbox. I think it’s worth investing the time initially to create the SSH access keys and setting up a terminal. I may even take the time to write a batch command to cycle through each website in turn!

 

Let me know in the comments how you’ll use Joomla’s CLI

 

Joomla CLI Cheat Sheet

php cli/joomla.php (+ a command)

Cache 
cache:clean Clean expired cache entries
Config 
config:get Display the current value of a configuration option
config:set Set a value for a configuration option
Core 
core:check-updates Check for Joomla updates
core:update Update Joomla
Database 
database:export database:export
database:import Import the database
Extension 
extension:discover Discover extensions
extension:discover:install Install discovered extensions
extension:discover:list List discovered extensions
extension:install Install an extension from a URL or from a path
extension:list List installed extensions
extension:remove Remove an extension
Finder 
finder:index Purges and rebuild the index
Scheduler 
scheduler:list List all scheduled tasks
scheduler:run Run one or more scheduled tasks
scheduler:state Enable, disable or trash a scheduled task
Session 
session:gc Perform session garbage collection
session:metadata:gc Perform session metadata garbage collection
Site 
site:down Put the site into offline mode
site:up Put the site into online mode
Update 
update:extensions:check Check for pending extension updates
update:joomla:remove-old-files Remove old system files
User 
user:add Add a user
user:addtogroup Add a user to a group
user:delete Delete a user
user:list List all users
user:removefromgroup Remove a user from a group
user:reset-password Change a user's password

Akeeba Backup CLI Cheat Sheet

php cli/joomla.php (+ a command)

akeeba:backup:alternate Take a backup with Akeeba Backup's frontend backup feature
akeeba:backup:alternate_check Check for failed Akeeba Backup backups with its front-end feature
akeeba:backup:check Check for failed Akeeba Backup backup attempts
akeeba:backup:delete Deletes a backup record known to Akeeba Backup, or just its files
akeeba:backup:download Returns a backup archive part for a backup record known to Akeeba Backup
akeeba:backup:fetch Download a backup from the remote storage back to the server
akeeba:backup:info Lists a backup record known to Akeeba Backup
akeeba:backup:list Lists backup records known to Akeeba Backup
akeeba:backup:modify Modifies a backup record known to Akeeba Backup
akeeba:backup:take Take a backup with Akeeba Backup
akeeba:backup:upload Retry uploading a backup to the remote storage
akeeba:filter:delete Delete a filter value known to Akeeba Backup
akeeba:filter:exclude Set an exclusion filter to Akeeba Backup
akeeba:filter:include-database Adds an additional database to be backed up by Akeeba Backup
akeeba:filter:include-directory Add an additional off-site directory to be backed up by Akeeba Backup
akeeba:filter:list Get the filter values known to Akeeba Backup
akeeba:log:get Retrieve a log file known to Akeeba Backup
akeeba:log:list Lists log files known to Akeeba Backup
akeeba:migrate Migrates the settings from Akeeba Backup 8
akeeba:option:get Gets the value of a configuration option for an Akeeba Backup profile
akeeba:option:list Lists the configuration options for an Akeeba Backup profile, including their title
akeeba:option:set Sets the value of a configuration option for an Akeeba Backup profile
akeeba:profile:copy Creates a copy of an Akeeba Backup profile
akeeba:profile:create Creates a new Akeeba Backup profile
akeeba:profile:delete Delete an Akeeba Backup profile
akeeba:profile:export Exports an Akeeba Backup profile as a JSON string
akeeba:profile:import Imports an Akeeba Backup profile from a JSON string
akeeba:profile:list Lists the Akeeba Backup backup profiles
akeeba:profile:modify Modifies an Akeeba Backup profile
akeeba:profile:reset Resets an Akeeba Backup profile
akeeba:sysconfig:get Gets the value of an Akeeba Backup component-wide option
akeeba:sysconfig:list Lists the Akeeba Backup component-wide options
akeeba:sysconfig:set Sets the value of an Akeeba Backup component-wide option

 

Further Reading

https://docs.cpanel.net/cpanel/security/ssh-access/

https://support.plesk.com/hc/en-us/articles/115000172834-How-to-connect-to-a-Plesk-server-via-SSH-with-available-server-s-credentials

https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html

https://www.a2hosting.com/kb/cpanel/cpanel-security-features/configuring-ssh-keys-with-cpanel

https://www.digitalcitizen.life/command-prompt-how-use-basic-commands/

https://docs.joomla.org/J4.x:CLI_Update

https://docs.joomla.org/J4.x:CLI_Database_Exporter_Importer

https://docs.joomla.org/J4.x:Writing_A_CLI_Application

https://symfony.com/doc/current/console/style.html

https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html

https://www.akeeba.com/documentation/akeeba-backup-joomla/akeeba-backup-cli.html

https://www.ansible.com/


Cowboy Photo by Drew Dau on Unsplash

 

2
The June Issue
Joomla TUF sprint june 2022 - Keeping the trojan h...
 

Comments 4

Already Registered? Login Here
Patrick on Saturday, 25 June 2022 02:06
Another great powerful tool for Joomla!

Task Sheduler, CLI, I like what I hear. This is powerful abilities that make the best CMS even better. Can wait to play with that stuff...

0
Task Sheduler, CLI, I like what I hear. This is powerful abilities that make the best CMS even better. Can wait to play with that stuff...
Adrian Versey on Friday, 01 July 2022 08:30
Akeeba Backup not working

Hi, Thanks for the great article. I have used the CLI interface to update Joomla core no problem, however, none of the commands relating to Akeeba Backup are working. I get the error message "Command "akeeba:backup:list: is not defined" followed by "The command "akeeba:backup:list" does not exist"

Also, if I check for extension updates it tells me I have know available updates even though when I log into the admin area of my website I can see there is a update available for Akeeba Backup.

Any help would be appreciated.
Thanks, Adrian.

0
Hi, Thanks for the great article. I have used the CLI interface to update Joomla core no problem, however, none of the commands relating to Akeeba Backup are working. I get the error message "Command "akeeba:backup:list: is not defined" followed by "The command "akeeba:backup:list" does not exist" Also, if I check for extension updates it tells me I have know available updates even though when I log into the admin area of my website I can see there is a update available for Akeeba Backup. Any help would be appreciated. Thanks, Adrian.
Brendan Hedges on Tuesday, 05 July 2022 17:56
Re: Akeeba Backup not working

Hi Adrian,

Did you get this sorted? The most likely reason you're having issues with Akeeba is that only the PRO version of Akeeba backup integrates with the Joomla CLI. You can find more info about it here.

0
Hi Adrian, Did you get this sorted? The most likely reason you're having issues with Akeeba is that only the PRO version of Akeeba backup integrates with the Joomla CLI. You can find more info about it [url=https://www.akeeba.com/documentation/akeeba-backup-joomla/akeeba-backup-cli.html]here[/url].
Adrian Versey on Wednesday, 06 July 2022 06:14
CLI

Hi Brendan. Thanks for your reply. You are correct, the CLI only works with the pro version.

0
Hi Brendan. Thanks for your reply. You are correct, the CLI only works with the pro version.

By accepting you will be accessing a service provided by a third-party external to https://magazine.joomla.org/