UX guidelines for commands

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 create node --name=MyApp

In this example, create is the command (create a thing), node is the subcommand (create a Node.js app), and --name is an option (set the name of the Node.js app being created).

Subcommands are not required, but err on the side of more general command actions with multiple subcommands rather than many similar commands. So, for example, we prefer shopify create node and shopify create rails are the same command with different subcommands, rather than shopify create_rails and shopify create_node.

More examples:

$ shopify generate page

$ shopify deploy heroku

$ 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.

$ shopify tunnel start
$ shopify 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 create node
? App Name
>

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

$ shopify generate
Generate code in your Node project. Supports generating new billing API calls, new pages, or new webhooks.
  Usage: shopify generate [ billing | page | 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 snake_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 create node --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.