Edit in GitHubLog an issue

Command naming guidelines

As an extension developer, you can now create and distribute your own commands for Adobe Commerce and Magento Open Source applications. But as for any implementation, it's also important to follow some general conventions to keep your commands consistent with commands from other developers. Being consistent in this way reduces the user's learning curve.

This topic discusses our recommended naming conventions.

Name#

A command name is a part of the command, which defines behavior of the command on the very high level. In the command it goes right after the command's name. For example, in bin/magento setup:upgrade, bin/magento is the command's name and setup:upgrade is the name of the command.

If you have an aplication installation handy, enter the following to display the current list of commands:

Copied to your clipboard
bin/magento list

Format#

The format for command names is group:[subject:]action.

group#

group represents a group of related commands. Commands in a group display in a list, which in turn makes it easier for the user to find the desired command. To find a group name for a command, imagine an subject area where it can be used. The subject area can be any of the following:

  • Domain area (for example, module for actions with modules, info for commands that provide some information)
  • Workflow area (for example, admin for commands that can be used by an administrator, dev for a developer)

subject#

subject is a subject for the action. The subject is optional, but it can be useful for defining sets of commands that work with the same object. If a subject is represented by a compound word, use a dash or hyphen character to separate the words.

action#

action is an action the command does.

Examples#

Copied to your clipboard
1// general commands: just a group and an action
2bin/magento setup:install
3bin/magento module:status
4
5// set of commands with a subject
6bin/magento setup:config:set
7bin/magento setup:config:delete
8bin/magento setup:db-schema:upgrade
9bin/magento setup:db-data:upgrade

Options and arguments#

Options and arguments follow the command name and modify the command's behavior.

For example, in bin/magento module:disable --force Magento_Catalog, the --force option and the Magento_Catalog argument bypass the restrictions and specify a particular module to be disabled; in this case, regardless of dependencies on other modules.

Options and arguments create different user experiences. As a developer, you can choose which type of input is better for your particular case.

Arguments#

Arguments are values passed by the user in a specified order. The argument name is not visible to the user.

Format#

The format for command arguments is a single word or a compound word separated with a dash or hyphen character.

Examples#

Copied to your clipboard
bin/magento dev:theme:create frontend vendor themename

where:

frontend is a subject area argument

vendor is a vendor argument

themename is a theme name argument

Use arguments when you need required data from the user. We recommend as few arguments as possible (no more then three) so the user will not confuse their order.

To make it simpler for the user, we recommend the following:

  • Run the CLI multiple times for providing multiple similar values instead of running it once with 20 values

  • Use default values for required arguments where possible.

    You can then use options instead of arguments to minimize the amount of required data the user must enter.

  • Replace arguments with options: options are named, so the user can provide them in any order. This requires additional data validation (by default, all options are optional).

Options#

Options are name-value pairs. The sequence of entered values doesn't matter.

An option can have a value or no value. An option that does not require a value represents a flag (yes or no).

An option can also have a one-letter shortcut as an alternative to its full name. Enable shortcuts for often-used options or if it's easy to determine what the shortcut means. Usually it makes sense to enable shortcuts for options similar to the ones used in widely-used commands (for example, -f for --force, -v for --verbose, -h for --help).

Format#

The format for command options is a single word or a compound word separated with a dash or hyphen character.

Examples#

Copied to your clipboard
bin/magento dev:theme:create --parent=Magento/luma frontend arg1 arg2
Copied to your clipboard
bin/magento dev:theme:create -p=Magento/luma frontend vendor themename
Copied to your clipboard
bin/magento dev:theme:create --extend-from=Magento/luma frontend vendor themename
Copied to your clipboard
bin/magento module:disable -f Magento_Cms

Where:

--parent is an option that specifies a parent theme

-p is a shortcut for --parent

-f is a shortcut for a non-value option --force

arg1, arg2, frontend, vendor and themename are arguments (see Command options and arguments).

Use options for:

  • Optional data
  • Required data that has a default value

Example:

Copied to your clipboard
1// correct
2bin/magento dev:theme:create --extend-from=Magento/luma frontend Foo bar
3bin/magento module:disable --force Magento_Catalog
4bin/magento module:disable -f Magento_Catalog
5
6//incorrect
7bin/magento module:disable --force=1 Magento_Catalog
8bin/magento module:disable -f=yes Magento_Catalog

Recommendations#

To avoid naming your command the same as another command, we recommend:

  • Looking at other extensions in the Commerce Marketplace before you choose a name for your commands. By planning ahead, you can avoid naming collisions entirely.

  • Restricting command names to start with a unique name, such as a vendor name. The usability of the command depends on what you choose for a vendor name.

    For example, myname:dev:theme:create is not obvious and is hard to remember.

    The vendor name doesn't have to start the command name; it could be in the middle. This way, related commands are grouped together.

    Examples:

    Copied to your clipboard
    1dev:myname:theme:create
    2dev:myname:theme:delete
Was this helpful?
  • Privacy
  • Terms of Use
  • Do not sell my personal information
  • AdChoices
Copyright © 2022 Adobe. All rights reserved.