UX guidelines for commands

What should (and should not) be a command

A Shopify CLI command should encapsulate a single task. Under the hood, a single command may delegate to other tools, and run multiple commands, the way any script might. Or it may simply delegate to a single tool, but with specific options that would otherwise be difficult or irritating to set.

• In general, avoid creating commands that are merely simple wrappers around other tools. For example, it is not necessary to create a CLI command that runs rake db:migrate or yarn test unless there are unusual options that the project requires.

• Don't create three new commands if one will do the job. If a user will always need to perform steps in the same sequence, then design a single command that performs all of those steps.

Command structure

Shopify CLI commands have three components: the command name, a subcommand (if needed), and then options formatted as standard --flags. The command name is usually an action verb, which acts on the subcommand object noun. Options are never required to run a command, but allow the user to override defaults or provide information that the CLI would otherwise prompt for. Use the active voice, as per Shopify product content guidelines.

$ shopify node create --name=MyApp

In this example, node is the command (in this case, referring to a project type), create is the subcommand (e.g., create a Node.js app), and --name is an option (set the name of the Node.js app being created).

Subcommands are not required (unless the command is a project type), but err on the side of more general command actions with multiple subcommands rather than many similar commands.

More examples:

$ shopify node deploy heroku

$ shopify populate products

$ shopify logout

Exceptions to the verb/noun structure

When there's a strong existing convention, it's appropriate to use a noun as the command and a verb for the subcommand, e.g. starting or stopping a tunnel service, by project type.

$ shopify node tunnel start
$ shopify node tunnel stop

Prompts

CLI commands are expected to prompt the user to provide any additional information needed to complete the command or subcommand, or to confirm information before completing a destructive action.

$ shopify node create
? App Name
>

However, if a user types a command without a required subcommand, show them the standard help for the command:

$ shopify rails generate
Generate code in your Rails project. Supports generating new webhooks.
  Usage: shopify rails generate [ webhook ]

$

Options

For each prompt, provide a matching option flag. If the command asks the user to provide a name, there should be a matching --name option that they can use to set the name directly, skipping the prompt. However, options should never be required to run a command.

You may also add options to allow the user to override default settings for a command.

Option names should be plain English kebab-case. So the option to set an organization ID would be --organization-id. For example, in this command, the user sets the name and organization ID for the Node.js app:

$ shopify node create --name="My App" --organization-id=123456789

Making choices on behalf of the user

Sometimes, it may make sense to choose something for the user, rather than prompt them. For example, if there is only one valid choice or response to a prompt, don't ask the user to choose. However, you should clarify that the choice was made on their behalf, and, if the choice is difficult to take back, ask the user to confirm before proceeding.

For example, if your command requires the user to select an app, and only one app is available at that moment, choose the app for them rather than prompting, but make it clear it happened. If choosing an app will be difficult or impossible to change later, then ask the user to confirm that is correct app.