MageQuest Logo
MageQuest Logo

Command Line

February 24, 2020

CLI already?

It might seem strange for one of the first tutorials to focus on Magento 2's Command Line Interface (CLI). However, it's integral to the development workflow as well as key management processes, such as deployments, plus we'll be referencing it many quests going forward.

Therefore, it is vital to have a good understanding of how it works and how to interact with it. Plus, if you followed the previous Install & Setup quest, then you'll likely have already interacted with it when either installing Magento itself or the sample data.


bin/magento is the common name used to refer to Magento 2's CLI tool given it exists within the bin directory relative to the Magento 2 application root directory and has a filename of magento.

i.e. bin/magento is the file path from the application root directory and is therefore generally typed into the terminal to interact with it. You could also navigate to the bin directory and type solely magento or access it using the full path to it, e.g. /var/www/html/bin/magento (assuming your Magento 2 instance was installed within /var/www/html).

However, we'll always assume you're running the CLI tool from the Magento 2 application root and therefore refer to it as bin/magento.

Built on solid foundations

bin/magento is built using Symfony's Console component, so if you're familiar with this you'll be right at home, but even if you're not, it's a very intuitive tool with lots of great features. Much of what is covered below are in fact Symfony console features, and not specific to Magento.

So what can it do?

bin/magento has around 100 commands split into various areas, but some of the key uses include:

  • Setting the Magento 2 application mode (including putting the site into maintenance)
  • Installing and upgrading modules (including any persistent data or schema changes they make)
  • Managing Magento's cached and indexed data
  • Deploying (compiling) code and assets ready for deployment (e.g. to a production server)
  • Enabling/disabling tools that aid the development workflow

Listing all commands

If you want to see a full list of the commands currently available to you (these can differ based on your Magento edition and currently installed and enabled modules) then you can run:

bin/magento list

Or simply:


Anatomy of a command

All commands start with bin/magento (again, assuming you're running from the Magento application root directory).

Next, you have the command itself, which in many cases Magento have grouped into sections by splitting the command name with : and in most cases these span 2-3 levels:

bin/magento parent-group:child-group:command-name

An example is the below command:

bin/magento info:currency:list

Which as it's names suggests lists out all the currencies within Magento 2.

Finding commands

Sometimes you know a command you're looking for but can't quite remember the correct name and don't want to look through the entire list of available commands. Luckily you can do this by running bin/magento followed by the part of the command you do know. For example, if I want to refresh Magento's indexes, but can't remember the exact command I can run:

bin/magento index

And it will help me find what I'm looking for:

Command "index" is not defined.

Did you mean one of these?

The main consideration that has to made here is that the string you're searching for won't match a unique command as otherwise it will be run, which leads into the next handy feature...

Shorthand commands

Because, let's face it, all developers are lazy by nature - we'll automate anything if it means not having to repeat the same task - and typing out long commands is such hard work, someone (at Symfony, not Magento) thought it useful to allow commands to run by just typing as few of the letters within the commands name as possible, so long as the string is not ambiguous (i.e. matching more than one command name). For example, if we want to run:

bin/magento indexer:reindex

To clear all of Magento's cache then we could, in theory, reduce the command to the following:

bin/magento i:r
Note that we reduce the letters typed within each group and keep the : separator.

However, this won't work as it's ambiguous and will instead return:

Command "i:r" is ambiguous.
  Did you mean one of these?
      indexer:reindex                            Reindexes Data
      indexer:reset                              Resets indexer status to invalid

Both commands above under the indexer group start with re and therefore the CLI doesn't know which one we are referring to. If we update our command to the below, we'll no longer have any ambiguity and can successfully run the command using the shorthand.

bin/magento i:rei
Don't use shorthand for automation

If you're writing some form of automated script that will be running bin/magento commands unattended, then it is highly recommended not to use shorthand. Given that commands can be added/removed by upgrading to newer versions or different editions of Magento 2 or added via new modules then you can't guarantee the ambiguity of your shorthand command and this could lead to your script not running the desired command, or worse, running a different command entirely.

Therefore, it is much safer to use the full command name within these scripts and utilise shorthand just when hand typing commands into the terminal on your local/development environment.

Command arguments and options

Now we've seen how to find and run commands, it's time to look at how we modify certain commands using arguments and options.

What's the difference between an argument and an option?

In short, arguments are required, options are not. However, in certain cases options are required, but, they either have default values or you are prompted to enter a value interactively within the terminal after running the initial command.

In order to find out what options a given command has we can add the --help flag (or shorthand as -h) when running any command. For example:

bin/magento admin:user:unlock --help


  Unlock Admin Account

  admin:user:unlock <username>

  username              The admin username to unlock

  -h, --help            Display this help message

So we can see username is a required argument, which makes sense given the purpose of the command is to unlock a specific admin user.

That's the end of this tale! Follow the Walkthru to put what you've learnt into practice