Foundations

Design concepts and constraints that can help create a better Terminal like experience for GitHub.

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.

</td>
<td>
  Don't: Avoid making modifiers their own commands.
  
</td>

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

</td>
<td>
  Don't: Avoid language that can be interpreted in multiple ways ("open in browser"  or "open a pull request" here).
  
</td>

</td>
<td>
  Don't: Avoid long words in commands if there's a reasonable alternative.
  
</td>

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

</td>
<td>
  Don't: Don't use checks for failure messages.
  
</td>

</td>
<td>
  Do: Don't use alerts when closing or deleting.
  
</td>

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