Command Line

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

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:

bin/magento

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?
    indexer:info
    indexer:reindex
    indexer:reset
    indexer:set-dimensions-mode
    indexer:set-mode
    indexer:show-dimensions-mode
    indexer:show-mode
    indexer:status

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

Returns:

Description:
  Unlock Admin Account

Usage:
  admin:user:unlock <username>

Arguments:
  username              The admin username to unlock

Options:
  -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

There's no need for a structured tutorial on the CLI, but it is worth familiarizing yourself with bin/magento so here's a list of areas to acquaint yourself with before moving on:

Displaying all commands
Searching for commands by entering part of the command name only
Practising writing shorthand command names
Use the help flag to see what options (arguments) a given command has

You made it through! Now prepare to be tested in the Trial

Trial Overview

Trials test your knowledge of the current topic via a multiple choice quiz.
You'll receive a score upon completion and feedback on the answers you got right or wrong along with further guidance.
Ensure to read up on the concepts within the 'Story' and complete the 'Walkthru' (where present) before attempting!

1

What framework is bin/magento built upon?

Select 1 answer.

None (it is not built using any framework)Symfony ConsoleLaravel Artisan

2

...

Tested yourself enough? Head over to the next quest using the footer nav below or find more resources on this topic in the Journal

DevDocs Command Line Interface Overview

List of bin/magento commands

Symfony: The Console Component

Quests

Realms

Pages