UX guidelines for input, output and errors

The CLI is meant to be an interactive tool. It can prompt users for input required to complete a task, and it should produce human-friendly output to show progress, results and errors.

Text formatting

You can and should use ANSI color, and styles (bold, italic, and underline) to make text easier to understand and highlight important elements.

Unicode and non-ASCII characters

Although modern terminals support Unicode characters and emoji, the traditional terminal in Windows (Console Window Host) does not. For compatibility, it is best to use only the basic alphanumeric character set with common punctuation (ASCII printable characters). Some symbols are available as noted below — they are translated for Windows users.

Unlike on the web, avoid special punctuation like em dashes – and the ellipsis …, and instead use a regular hyphen - for an en dash, double hyphen -- for an em dash, and three periods ... instead of the ellipsis character.

Colors

There are 8 standard (ANSI) terminal colors, each with regular and "bright" shades. The 8 colors are black, white, blue, green, cyan, red, purple, and yellow. However, exact colors differ on different users’ screens, depending on their system and configuration. Users may adjust their default foreground and background to any color, and users can also modify how the standard colors appear.

Note: the default (non-bright) blue color is hard to read on dark backgrounds, and the default red color can be problematic for people with color blindness.

Contextual colors and styles

The CLI uses certain colors and styles consistently to mark different information:

• Print examples of commands in cyan
• Underline URLs
• Make headings bold (e.g. in help text)
• Highlight user-generated or user-defined output in green
• Print keyboard shortcuts in yellow

Key symbols

The symbols ✔️, ✘ and ★ are used to denote success, error, and tip respectively. There are shortcuts to output these symbols: {{v}}, {{x}} and {{*}}. (They are translated to simpler characters for Windows users.)

Formatting command arguments

Use angle brackets to show required text that the user must fill in. Use square brackets to show optional text. Use spaces around text that should be used verbatim, or no spaces if the text is placeholder.

• shopify tunnel auth <token> indicates that the user must provide a token value.
• shopify tunnel [ auth | start | stop ] indicates that the user may provide one of the subcommands, but is not required to.

How to format text in code

The text formatter has a simple syntax to adjust any output string, using a color, style or contextual formatting. For example, to format a heading bold with an example of a command option in cyan, that takes an optional count integer:

{{bold:Options:}}
  {{command:--count [integer]}}: The number of dummy items to populate. Defaults to 5.

Using a checkmark to show successful creation, with a URL:

{{v}} {{green:%s}} was created in your Partner Dashboard {{underline:%s}}