Table of Contents
Admin Tools integrates with Joomla's CLI application (joomla.php) which made its first appearance in Joomla 4.0. This is a full-blown command line client for Joomla and its extensions, allowing us to provide a much richer experience than what was possible using the separate command line scripts we have been offering since 2010.
Using the Joomla CLI client you can configure and query the configuration of Admin Tools, import and export settings and runs of its utility features.
Please note that the Admin Tools Command Line Interface is only available on Joomla 4.0 or later and requires having the Console - Admin Tools plugin published. The requirement for Joomla 4.0 or later is due to the fact that the Joomla CLI application was not available in previous versions of Joomla. The requirement for the plugin has to do with how Joomla itself works under the hood to detect and make available third party commands for the Joomla CLI application.\
You can access the Admin Tools CLI using the Joomla CLI
application. This is the file joomla.php in your
site's cli directory.
First of all, you need to know two things: how you can run PHP CLI
on your server and the path to your site. If unsure, ask your host or
system administrator. Assuming that you can run PHP on your server by
typing /usr/bin/php and that your site's path is
/home/mysite/public_html you can run the following
command to list all available Admin Tools CLI commands:
/usr/bin/php /home/mysite/public_html/cli/joomla.php list admintools
If you get an error reading
There are no commands defined in the "admintools" namespace.
you will need to publish the Console - Admin Tools plugin on your site first. If you get a different error you need to make sure that the PHP command you are using is correct, it is in fact the PHP CLI (not PHP CGI) binary and that the PHP version it runs is the same you are using on your web site.
Please note that most servers have multiple PHP versions installed. It's possible that the PHP version you are accessing with the command you are using is different than the one you are using on your web site. If unsure, please do ask your host. If the first level support of your host is unsure do ask them to escalate to an engineer. Server engineers can give you the correct path for PHP; it's trivial for them but may be indeed beyond the training or information available to a first level support agent.
The commands listed are in the format admintools:foo or admintools:foo:bar, i.e. two or three parts separated by semicolons. The first part is called the namespace of the command and it's always admintools for Admin Tools CLI commands. A keen observer may notice that the namespace for various Joomla CLI commands tends to be the component directory without com_ in front. We noticed that too and we're following the same convention. The next one to two parts further identify the command you need to run. For example, listing the blocked requests requires running a command like this:
/usr/bin/php /home/mysite/public_html/cli/joomla.php admintools:log:list
If you need a quick refresher on what each command does and/or what arguments and options it takes you can use the built-in help command on it:
/usr/bin/php /home/mysite/public_html/cli/joomla.php help admintools:log:list
![[Important]](/media/com_docimport/admonition/important.png) | Important |
|---|---|
|
The help page is automatically compiled by Joomla itself. We
have very little control over it. Some options may appear to have
optional values by surrounding the value part of the option in square
brackets e.g. Conversely, mandatory options do not have square brackets around
their value part, e.g. This is counter-intuitive and confusing. It's not even Joomla's choice for how the help page is rendered. This is how Symfony Console, the standard third party library for PHP command line applications, renders help pages. Joomla — like WP-CLI, Drush, Composer etc — uses Symfony Console for its CLI application. So at least there is consistency in this counter-intuitive and confusing presentation of options across the entire PHP ecosystem (yes, we are UNIX traditionalists, what gave it away?)... |
All commands set the exit status code upon completion. Commands that executed successfully return an exit status of 0 (zero). Non-zero results mean that an error occurred while executing the command. The exit status reference can be found in the following sections of this documentation.
Some Admin Tools CLI commands accept a format
parameter. This tells Admin Tools CLI which output format to use for the
information it returns. The following formats are supported (not all
format are supported by all commands; please consult the command
reference further ahead in this documentation):
- table, text
-
Human readable text. This is meant for humans to read. It's not very useful for automation.
- json
-
The output is returned as a JSON string. You can feed this through commands such as jq or consume it in automation tools such as Ansible's json_query filter.
- csv
-
The output is returned as CSV (Comma Separated Values) data. This can be fed to Excel, Apple Numbers, Google Sheets, LibreOffice Calc and other spreadsheets. It can be a very useful format for generating reports.
- yaml
-
Important You need to have installed and enabled the optional PHP YAML extension. This is not enabled by default on most servers. If the extension is not installed or installed but not enabled you will get an error.
The output is returned as YAML. This is a lightweight, structured, machine-readable data format which can be consumed by automation tools.
- var_dump
-
The output goes through PHP's built-in var_dump() function. This is mostly useful for debugging and we may ask you to use it if you request support and we suspect something odd is going on with the output data.
- var_export
-
The output goes through PHP's built-in var_export() function. It can be used as-is in a PHP script's variable assignment. This can be useful for home-grown automation scripts written in PHP.
- count
-
Returns the number of items which would be output. This is useful for automation when used with the various akeeba:*:list commands. For example, if you need to know whether there are any backups taken the last week you can use the akeeba:backup:list command using the --from and --to options to limit the search within the last week and --format=count to get the number of backups taken in that period. If it's 0 no backups were taken. If it's non-zero this many backups were taken.