Foundations

Language

Language is the most important tool at our disposal for creating a clear, understandable product. Having clear language helps us create memorable commands that are clear in what they will do.

We generally follow this structure:

Command: The object you want to interact with

Subcommand: The action you want to take on that object. Most gh commands contain a command and subcommand. These may take arguments, such as issue/PR numbers, URLs, file names, OWNER/REPO, etc.

Flag: A way to modify the command, also may be called “options”. You can use multiple flags. Flags can take values, but don’t always. Flags always have a long version with two dashes (--state) but often also have a shortcut with one dash and one letter (-s). It’s possible to chain shorthand flags: -sfv is the same as -s -f -v

Values: Are passed to the commands or flags

• The most common command values are:
  • Issue or PR number
  • The “owner/repo” pair
  • URLs
  • Branch names
  • File names
• The possible flag values depend on the flag:
  • --state takes {closed | open | merged}
  • --clone is a boolean flag
  • --title takes a string
  • --limit takes an integer

Tip: To get a better sense of what feels right, try writing out the commands in the CLI a few different ways.

Do

Use a flag for modifiers of actions

Don’t

Avoid making modifiers their own commands

When designing your command’s language system:

• Use GitHub language
• Use unambiguous language that can’t be confused for something else
• Use shorter phrases if possible and appropriate

Do

Use language that can't be misconstrued

Don’t

Avoid language that can be interpreted in multiple ways ("open in browser" or "open a pull request" here)

Do

Use understood shorthands to save characters to type

Don’t

Avoid long words in commands if there's a reasonable alternative

Typography

Everything in a command line interface is text, so type hierarchy is important. All type is the same size and font, but you can still create type hierarchy using font weight and space.

• People customize their fonts, but you can assume it will be a monospace
• Monospace fonts inherently create visual order
• Fonts may have variable unicode support

Accessibility

If you want to ensure that a screen reader will read a pause, you can use a:

• period (.)
• comma (,)
• colon (:)

Spacing

You can use the following to create hierarchy and visual rhythm:

• Line breaks
• Tables
• Indentation

Do

Use space to create more legible output

Don’t

Not using space makes output difficult to parse

Color

Terminals reliably recognize the 8 basic ANSI colors. There are also bright versions of each of these colors that you can use, but less reliably.

Things to note

• Background color is available but we haven’t taken advantage of it yet.
• Some terminals do not reliably support 256-color escape sequences.
• Users can customize how their terminal displays the 8 basic colors, but that’s opt-in (for example, the user knows they’re making their greens not green).
• Only use color to enhance meaning, not to communicate meaning.

Iconography

Since graphical image support in terminal emulators is unreliable, we rely on Unicode for iconography. When applying iconography consider:

• People use different fonts that will have varying Unicode support
• Only use iconography to enhance meaning, not to communicate meaning

Note: In Windows, Powershell’s default font (Lucida Console) has poor Unicode support. Microsoft suggests changing it for more Unicode support.

Symbols currently used:

✓   Success
-   Neutral
✗   Failure
+   Changes requested
!   Alert

Do

Use checks for success messages

Don’t

Don't use checks for failure messages

Do

Use checks for success of closing or deleting

Don’t

Don't use alerts when closing or deleting

Scriptability

Make choices that ensure that creating automations or scripts with GitHub commands is obvious and frictionless. Practically, this means:

• Create flags for anything interactive
• Ensure flags have clear language and defaults
• Consider what should be different for terminal vs machine output

In terminal

Through pipe

Differences to note in machine output

• No color or styling
• State is explicitly written, not implied from color
• Tabs between columns instead of table layout, since cut uses tabs as a delimiter
• No truncation
• Exact date format
• No header

Customizability

Be aware that people exist in different environments and may customize their setups. Customizations include:

• Shell: shell prompt, shell aliases, PATH and other environment variables, tab-completion behavior
• Terminal: font, color scheme, and keyboard shortcuts
• Operating system: language input options, accessibility settings

The CLI tool itself is also customizable. These are all tools at your disposal when designing new commands.

• Aliasing: gh alias set
• Preferences: gh config set
• Environment variables: NO_COLOR, EDITOR, etc

Edit this page on GitHub

1 contributor

Last edited by maximedegreve on January 31, 2023