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 application installation handy, enter the following to display the current list of commands:
Copied to your clipboardbin/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,
modulefor actions with modules,infofor commands that provide some information) - Workflow area (for example,
adminfor commands that can be used by an administrator,devfor 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// general commands: just a group and an actionbin/magento setup:installbin/magento module:status// set of commands with a subjectbin/magento setup:config:setbin/magento setup:config:deletebin/magento setup:db-schema:upgradebin/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 clipboardbin/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 clipboardbin/magento dev:theme:create --parent=Magento/luma frontend arg1 arg2
Copied to your clipboardbin/magento dev:theme:create -p=Magento/luma frontend vendor themename
Copied to your clipboardbin/magento dev:theme:create --extend-from=Magento/luma frontend vendor themename
Copied to your clipboardbin/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// correctbin/magento dev:theme:create --extend-from=Magento/luma frontend Foo barbin/magento module:disable --force Magento_Catalogbin/magento module:disable -f Magento_Catalog//incorrectbin/magento module:disable --force=1 Magento_Catalogbin/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:createis 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 clipboarddev:myname:theme:createdev:myname:theme:delete
