Command Line Console Plugins in Joomla

1. The Basics

1.1 What is the Joomla CLI?

The CLI is a way to run Joomla from a terminal instead of a browser. You type a command, Joomla runs it, prints the result as text, and exits. There is no page, no template, and no visitor.

The single entry point is one file in your site:

cli/joomla.php

You run it with PHP on the server, like this:

php cli/joomla.php list

That command boots the entire Joomla application in the background, then prints a list of every command it knows. The web site and the CLI share the same code, the same database, and the same configuration. The only difference is how you reach them.

1.2 Why a Command Line at All?

Some jobs are simply easier, faster, or safer without a browser:

• Automation. A scheduled job (cron) can run a command every night with no human present.
• Maintenance. Clear the cache, run database fixes, or take the site offline in one line.
• Bulk work. Add many users, install extensions, or reindex search without clicking through screens.
• Recovery. When the back end is locked or broken, the CLI may still let you reset a password or bring the site back up.
• Speed. A command skips the template, the modules, and the rendering, so it starts and finishes quickly.

Think of the CLI as a service entrance to your Joomla site: the same building, the same rooms, but a door meant for staff and machines rather than the public.

1.3 The Shape of a Command

Every Joomla command follows the same readable pattern. The name uses colons to group related actions:

php cli/joomla.php  extension:install  --path=/tmp/mod_hello.zip
                    |                  |
                    |                  └─ options (start with --)
                    └─ the command name (group:action)

• The command name tells Joomla what to do, for example cache:clean or user:add.
• Arguments are values the command expects in a fixed position.
• Options start with -- and can appear in any order, for example --path=....

This naming is not decoration. The part before the colon is a namespace, so all the extension:* commands belong together and can be listed as a group.

3. A Tour of the Core Commands

Joomla 6 ships with a useful set of commands out of the box. You do not install anything; they are part of core. Here are the families you will use most.

3.1 Cache, Configuration and Site State

3.2 Users

The command user:reset-password alone is worth knowing: it is the standard way back in when you are locked out of the administrator login.

3.3 Extensions and Updates

3.4 Scheduler, Search and Sessions

You do not have to memorise this list. Run php cli/joomla.php list on your own site and the current, exact set is printed for you.

5. How Commands Are Registered

A command is a small class that Joomla knows how to find and run. There are two ways a command reaches the application, and understanding both explains how the whole system extends cleanly.

5.1 Default Commands

The CMS application lists its own built-in commands in a method called getDefaultCommands(). Each one is a class that gets created when the application starts:

protected function getDefaultCommands(): array
{
    return array_merge(parent::getDefaultCommands(), [
        new Console\CleanCacheCommand(),
        new Console\AddUserCommand($this->getDatabase()),
        // ... and more
    ]);
}

The framework's own list and help commands come from parent::getDefaultCommands(). The CMS adds the Joomla-specific ones on top.

5.2 Lazy Commands Through the DI Container

Creating dozens of command objects on every single CLI call would be wasteful, because you only ever run one of them. So most core commands are registered lazily: Joomla keeps a simple map of command name to class name, and only builds the object when you actually call that command.

// Simplified: a name -> class map handed to a command loader
$mapping = [
    'cache:clean'        => CleanCacheCommand::class,
    'extension:install'  => ExtensionInstallCommand::class,
    'scheduler:run'      => TasksRunCommand::class,
    // ...
];

$app->setCommandLoader(new WritableContainerLoader($container, $mapping));

The command loader asks the DI container for the class only when its name is requested. This keeps the CLI fast: nothing heavy is built until it is needed.

5.3 The Two Paths in One Picture

Console Application
   ├─ getDefaultCommands()      → created eagerly (list, help, a few core)
   ├─ command loader (DI map)   → created lazily, only when called
   └─ console plugins           → add commands at runtime (see next section)

The third path, console plugins, is how your extension joins the list without touching any core file.

7. Building Your Own Command

A command is a single class that extends AbstractCommand. It needs a name, an optional configuration of arguments and options, and the code to run.

7.1 The Minimum Command

use Joomla\Console\Command\AbstractCommand;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Style\SymfonyStyle;

final class HelloCommand extends AbstractCommand
{
    // The command name, as typed in the terminal:
    protected static $defaultName = 'hello:world';

    protected function doExecute(InputInterface $input, OutputInterface $output): int
    {
        $io = new SymfonyStyle($input, $output);
        $io->title('Hello from the Joomla CLI');
        $io->success('It works.');

        return Command::SUCCESS;   // exit code 0
    }
}

Run it with php cli/joomla.php hello:world once the plugin that adds it is enabled.

7.2 Configuring Arguments and Options

Override configure() to declare what your command accepts and to write its help text:

use Symfony\Component\Console\Input\InputArgument;
use Symfony\Component\Console\Input\InputOption;

protected function configure(): void
{
    $this->setDescription('Greet someone from the command line');
    $this->addArgument('name', InputArgument::OPTIONAL, 'Who to greet', 'world');
    $this->addOption('shout', null, InputOption::VALUE_NONE, 'Use capital letters');
    $this->setHelp('This command prints a friendly greeting.');
}

7.3 Reading Input and Returning a Result

protected function doExecute(InputInterface $input, OutputInterface $output): int
{
    $io   = new SymfonyStyle($input, $output);
    $name = $input->getArgument('name');

    if ($input->getOption('shout')) {
        $name = strtoupper($name);
    }

    $io->writeln('Hello, ' . $name . '!');

    return Command::SUCCESS;
}

Always return one of the named exit codes - Command::SUCCESS, Command::FAILURE, or Command::INVALID - so scripts and cron jobs can react to the outcome.

7.4 Talking to the CMS

Because the CMS is fully booted, your command can use the same modern APIs as a controller or model. To work with a component, boot it and ask its factory for a model:

$model = $this->getApplication()
    ->bootComponent('com_content')
    ->getMVCFactory()
    ->createModel('Articles', 'Administrator', ['ignore_request' => true]);

$count = \count($model->getItems());
$io->info($count . ' articles found.');

This is exactly how core commands such as cache:clean work: they boot a component and call its model, then report the result to the terminal.

7.5 Injecting Services Through the Constructor

Reaching for global state inside a command works, but the cleaner way is to let the DI container hand you the services you need. Give your command a constructor and ask for them by type:

use Joomla\Database\DatabaseInterface;

final class CountUsersCommand extends AbstractCommand
{
    protected static $defaultName = 'users:count';

    public function __construct(private DatabaseInterface $db)
    {
        parent::__construct();   // always call the parent constructor
    }

    protected function doExecute(InputInterface $input, OutputInterface $output): int
    {
        $query = $this->db->getQuery(true)
            ->select('COUNT(*)')
            ->from($this->db->quoteName('#__users'));

        $total = (int) $this->db->setQuery($query)->loadResult();

        (new SymfonyStyle($input, $output))->info($total . ' users.');

        return Command::SUCCESS;
    }
}

Core commands do this too: user:add receives the database through its constructor rather than fetching it itself. Your console plugin then creates the command with its dependency when it registers it - $this->getApplication()->addCommand(new CountUsersCommand($db)). The result is code that is loosely coupled and easy to test, because you can pass a fake database in a unit test.

9. Input, Output, and Interaction

A good command is pleasant to use by hand and reliable inside a script. Joomla's CLI gives you the tools for both.

9.1 SymfonyStyle: Clean Output

The SymfonyStyle helper wraps the raw output in tidy, consistent formatting. Core commands use it everywhere:

$io = new SymfonyStyle($input, $output);

$io->title('Cleaning System Cache');   // a heading
$io->success('Cache cleaned');         // green success block
$io->error('Cache not cleaned');       // red error block
$io->warning('Nothing to do');         // yellow warning
$io->table(['Id', 'Name'], $rows);     // a formatted table

9.2 Asking the User Questions

When run by a person, a command can prompt for missing details. The user:add command does exactly this when you do not pass every option:

$username = $io->ask('Username');
$password = $io->askHidden('Password');     // input is not shown on screen
$confirm  = $io->confirm('Create this user?', true);

This is friendly for humans, but remember automation. In a cron job there is nobody to answer, so either pass every value as an option or add --no-interaction and make sure your command can run with its defaults.

9.3 Verbosity Levels

Let the user choose how much detail they want by checking the verbosity, instead of printing everything always:

if ($output->isVerbose()) {        // shown with -v
    $io->writeln('Extra detail for the curious.');
}

Normal output stays clean, and -v, -vv, or -vvv reveal progressively more for debugging.

9.4 Logging What a Command Does

Output on screen disappears the moment a cron job finishes. For anything that runs unattended, write a permanent record with Joomla's logging framework instead of, or alongside, the screen output:

use Joomla\CMS\Log\Log;

Log::add('Nightly import started', Log::INFO, 'cli');
// ... do the work ...
Log::add('Nightly import finished: ' . $count . ' items', Log::INFO, 'cli');

The third argument is a category. Giving your command its own category (here cli) lets you send those entries to their own log file and read them later under System → Maintenance → Manage Logs, separate from the rest of the site. By default the files live in the configured log path, usually administrator/logs/.

Log the start, the end, and any error. When a scheduled job fails at three in the morning, the log is the only witness you will have.

9.5 Debugging a Command That Will Not Run

When a command misbehaves or refuses to appear, work through this short checklist in order:

• Is the plugin enabled? Check the Plugins list, or run the #__extensions query from section 8.4.
• Does it appear at all? Run php cli/joomla.php list. If it is missing, the plugin is not loading or not calling addCommand().
• Is the namespace correct? The manifest <namespace> and the folders under src/ must match exactly, or autoloading fails silently.
• Run it verbosely. Add -vvv to see the full stack trace instead of a short message: php cli/joomla.php mycli:hello -vvv.
• Read its help. php cli/joomla.php help mycli:hello confirms the name, arguments, and options Joomla actually registered.

Most "nothing happens" reports come down to one of these five: disabled plugin, missing addCommand(), or a namespace typo that breaks autoloading.

11. CLI versus Web versus Web Services

Joomla can be reached in three ways. They share the same code and data, but they suit different jobs.

A REST call to the Web Services API carries its token in a header, like this:

curl -H "X-Joomla-Token: <token>" \
     https://example.test/api/index.php/v1/content/articles

Rule of thumb: use the CLI for jobs you run on the server, the web for people, and the Web Services API for other programs talking to your site.

13. CLI and SEO: Keep It Invisible to Search

The CLI has no place in search results, and getting that right is mostly about not doing the wrong thing.

• CLI commands produce no web pages, no URLs, and no metadata. There is nothing for a search engine to index, which is exactly right.
• Do not turn a command into a public web endpoint just to trigger it from a browser. That would expose powerful actions to anyone who finds the URL.
• Keep the cli/ directory out of the public document root where your host's layout allows it, so the scripts are never reachable over HTTP.
• Use the CLI to improve SEO indirectly: finder:index keeps Smart Search fresh, and scheduled tasks run via scheduler:run can rebuild sitemaps or clean up redirects on time.

In short, the CLI works behind the scenes. It helps your public pages stay fast and current, while staying completely invisible to crawlers itself.

15. Best Practices

If you only remember a few things from this article, remember these:

• Start with php cli/joomla.php list and help - they document any site for you.
• Run commands from the Joomla root, as the web user, with the PHP version that matches the website.
• For automation, use full paths and add --no-interaction so nothing waits for a human.
• Trigger scheduled tasks with a real cron job calling scheduler:run, not the web trigger.
• Build new commands as a console plugin that adds them on BEFORE_EXECUTE - never edit core.
• Keep the handler thin, use SymfonyStyle for output, and return a clear exit code.
• Keep the cli/ scripts off the public web.

17. Summary

The Joomla CLI is the same site you know, reached through a different door. One entry point, cli/joomla.php, boots the full CMS and hands control to a command, which prints text and returns an exit code. There is no template, no visitor, and no HTTP - just Joomla doing one job, quickly.

The key ideas are short:

• Run php cli/joomla.php list to see every command on a site, and help to learn one.
• Core ships dozens of commands for cache, config, users, extensions, updates, search, and the scheduler.
• The application is built on Symfony Console and registers commands eagerly, lazily through the DI container, and at runtime through console plugins.
• A console plugin lives in the console group and adds commands on the BEFORE_EXECUTE event, so you extend the CLI without touching core.
• A command is a small class: a name, a configure() for its arguments and options, and a doExecute() that returns an exit code.

Once you are comfortable here, a lot of Joomla maintenance becomes a single reliable line: clear the cache, reindex search, run the nightly tasks, or recover a locked-out site.

If you want help automating your Joomla maintenance, setting up a dependable cron-driven scheduler, or building custom CLI commands and console plugins for your own workflows, that is exactly the kind of advanced Joomla work I do every day.