Joomla 4: A Powerful CLI Application

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.

 

 

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?

 

 

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.

 

 

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.

 

 

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:

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.

 

2. 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.

 

3. 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’.

 

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

 

5. 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.

 

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

 

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:

 

 

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.

 

 

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”.

 

 

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:

 

 

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.

 

 

 

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.

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.

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:

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.

 

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.

 

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.

 

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.

 

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.

 

 

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.

 

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