Design concepts and constraints that can help create a better Terminal like experience for GitHub.
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:
| gh | <command> |
<subcommand> |
[value] | [flags] | [value] |
|---|---|---|---|---|---|
| gh | issue | view | 234 | --web | - |
| gh | pr | create | - | --title | “Title” |
| gh | repo | fork | cli/cli | --clone | false |
| gh | pr | status | - | - | - |
| gh | issue | list | - | --state | closed |
| gh | pr | review | 234 | --approve | - |
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:
--statetakes{closed | open | merged}--cloneis a boolean flag--titletakes a string--limittakes 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.
|
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
If you want to ensure that a screen reader will read a pause, you can use a:
- period (
.) - comma (
,) - colon (
:)
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.
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.
- 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.
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.
|
Do: Don't use alerts when closing or deleting.
|
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
- No color or styling
- State is explicitly written, not implied from color
- Tabs between columns instead of table layout, since
cutuses tabs as a delimiter - No truncation
- Exact date format
- No header
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