---
title: 'Plugin Command'
url: 'https://learn.getgrav.org/2/cli-console/grav-cli-plugin'
markdown: 'https://learn.getgrav.org/2/cli-console/grav-cli-plugin.md'
date: '2025-12-24'
description: "Plugin Command Plugins can integrate to Grav's CLI bin/plugin and enhance the plugin functionalities via Terminal by executing specific tasks. As explained in the Grav CLI section, you need to use a terminal in order to be able to execute commands. When running the command bin/plugin, all the plugi…"
taxonomy:
category:
- docs
---
# Plugin Command
Plugins can integrate to Grav's CLI `bin/plugin` and enhance the plugin functionalities via Terminal by executing specific tasks.
As explained in the [Grav CLI](https://learn.getgrav.org/2/cli-console/grav-cli) section, you need to use a **terminal** in order to be able to execute commands.
When running the command `bin/plugin`, all the plugins who provide CLI integration will be listed.
The first option passed in to `bin/plugin` is always the plugin slug (ie, *error*, *login*, etc). The second option is the actual *command* that the plugin provides.
Based on the plugin implementation there could be other following options and you can learn more about each of them by running the `bin/plugin [slug] list` command.
## Reserved Commands and Options
There are some reserved *commands* and *options* that are always available from any plugin. These are also particularly important to keep in mind if you are a developer and want to implement your own tasks, because you won't be able to use any of the reserved commands and options.
| **Commands** | |
|---|---|
| `help` | Displays help for a command |
| `list` | Lists commands |
| **Options** | |
|---|---|
| `-h`, `--help` | Display help message |
| `-q`, `--quiet` | Do not output any message |
| `-v`, `--version` | Display application version |
| `--ansi` | Force ANSI output |
| `--no-ansi` | Disable ANSI output |
| `-n`, `--no-interaction` | Do not ask any interactive question |
| `-v\|vv\|vvv`, `--verbose` | Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug |
## How to Use the CLI for Plugins
The **list** and **help** commands are very useful when you don't know yet how to use a certain plugin CLI.
With **list** you can access all the available commands and view a quick description of what each of them do.
Here is an example with the **login** plugin when we run the command `bin/plugin login list`.
Warning
Not specifying any command after the plugin slug defaults automatically to `list`. This means that both `bin/plugin [slug] list` and `bin/plugin [slug]` are equivalents.
As you can see, most of the options and commands correspond to the [reserved list](#reserved-commands-and-options). The actual commands offered by the login plugin are `add-user`, `new-user` and `newuser`.
As you can notice the help description of all 3 commands is identical. This is because, by choice, the 3 commands are exactly the same. **add-user** and **newuser** are in fact aliases for **new-user**, which allows to easily guess the command without knowing or remembering it.
Now that we know the login plugin comes with a `new-user` command, we only need to learn how to use it. This is where the reserved **help** command comes in place. Let's run `bin/plugin login help new-user`.
Now we have a complete understanding of the `new-user` command and we know how to use it. Let's try creating a new user. Because all the options are optional by definition, we will omit the password on purpose (we will be asked about it in a prompt later).
BASH
```
bin/plugin login newuser -u joeuser -e joeuser@grav.org -P b -N "Joe User" -t "Site Administrator"
Creating new user
Enter a password: *********
Repeat the password: *********
Success! User joeuser created.
```
## Developers: Integrate the CLI in Plugin
As a Developer, you might want to create CLI commands for admins or users to run. It is extremely easy to add such functionality in a Plugin.
The first thing you want to do is to create a subfolder `cli/` at the root of your plugin. This folder will be processed by `bin/plugin` and scanned for commands classes.
Grav's CLI is based on the great [Symfony Console Component](http://symfony.com/doc/current/components/console/introduction.html) and you can pretty much follow their documentation for a complete reference, there are just a few important things you should consider.
1. The name of the class file is standard. It should start with a capital letter and end with **Command.php**.
- `Hello.php`: WRONG
- `helloworldCommand.php`: WRONG
- `HelloworldCommand.php`: CORRECT
- `HelloWorldCommand.php`: CORRECT
2. You should always extend `ConsoleCommand`, this will offer you some Grav extras such as formatted colors, direct access to the Grav instance and other utilities ([more details](https://github.com/getgrav/grav/blob/develop/system/src/Grav/Console/ConsoleTrait.php)).
3. Symfony Console requires an `execute` method. When extending **ConsoleCommand** this becomes `serve`.
Below is a simple example to get you started. You can test it, as is, by saving it as `HelloCommand.php` and by placing it under your plugin's root `cli/` folder (**user/plugins/my\_plugin/cli/HelloCommand.php**).
PHP
```
1<?php
2namespace Grav\Plugin\Console;
3
4use Grav\Console\ConsoleCommand;
5use Symfony\Component\Console\Input\InputArgument;
6use Symfony\Component\Console\Input\InputOption;
7
8/**
9 * Class HelloCommand
10 *
11 * @package Grav\Plugin\Console
12 */
13class HelloCommand extends ConsoleCommand
14{
15 /**
16 * @var array
17 */
18 protected $options = [];
19
20 /**
21 * Greets a person with or without yelling
22 */
23 protected function configure()
24 {
25 $this
26 ->setName("hello")
27 ->setDescription("Greets a person.")
28 ->addArgument(
29 'name',
30 InputArgument::REQUIRED,
31 'The name of the person that should be greeted'
32 )
33 ->addOption(
34 'yell',
35 'y',
36 InputOption::VALUE_NONE,
37 'Wheter the greetings should be yelled or quieter'
38 )
39 ->setHelp('The hello greets someone.')
40 ;
41 }
42
43 /**
44 * @return int|null|void
45 */
46 protected function serve()
47 {
48 // Collects the arguments and options as defined
49 $this->options = [
50 'name' => $this->input->getArgument('name'),
51 'yell' => $this->input->getOption('yell')
52 ];
53
54 // Prepare the strings we want to output and wraps the name into a cyan color
55 // More colors available at:
56 // https://github.com/getgrav/grav/blob/develop/system/src/Grav/Console/ConsoleTrait.php
57 $greetings = 'Greetings, dear ' . $this->options['name'] . '!';
58
59 // If the optional `--yell` or `-y` parameter are passed in, let's convert everything to uppercase
60 if ($this->options['yell']) {
61 $greetings = strtoupper($greetings);
62 }
63
64 // finally we write to the output the greetings
65 $this->output->writeln($greetings);
66 }
67}
```
Warning
Another good simple example can be found in the [Error Plugin (LogCommand.php)](https://github.com/getgrav/grav-plugin-error/blob/develop/cli/LogCommand.php), If you are looking for a more complex example, you should have a look at the [Login Plugin (NewUserCommand.php)](https://github.com/getgrav/grav-plugin-login/blob/develop/cli/NewUserCommand.php)
[ Edit this page on Github ](https://github.com/getgrav/grav-learn/edit/develop/pages/2/07.cli-console/03.grav-cli-plugin/doc.md)
© 2026 Grav Documentation. All rights reserved.
---
## Navigation
- Parent: [CLI Console](https://learn.getgrav.org/2/cli-console.md)
- Previous: [Grav command](https://learn.getgrav.org/2/cli-console/grav-cli.md)
- Next: [GPM Command](https://learn.getgrav.org/2/cli-console/grav-cli-gpm.md)