cli

11 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

CLI principle: reasonable defaults, easy overrides

Optimize for what most people will need to do most of the time, but make it easy for people to adjust it to their needs. This often means considering the default behavior of each command and how it might need to be adjusted with flags.

CLI principle: make it feel like GitHub

Using the CLI tool, it should be obvious that it's GitHub and not anything else. Use details specific to GitHub, such as language or color. When designing output, reflect the GitHub.com interface as much as possible and appropriate.

CLI language: use sentence case not title case

Use sentence case for CLI output. Do not use title case.

CLI language: use GitHub.com terminology

Use language accurate to GitHub.com. Do not use language that GitHub.com doesn't use.

CLI principle: reduce cognitive load

Command line interfaces have very few affordances, rely on memory, and are often unforgiving of mistakes. Reducing cognitive load is necessary for making an accessible product.

CLI ways to reduce cognitive load

Include confirm steps, especially for riskier commands. Include headers to help set context for output. Ensure consistent command language to make memorizing easier. Ensure similar commands are visually and behaviorally parallel, for example any create command should behave the same. Anticipate what people might want to do next, for example asking if you want to delete your branch after you merge. Anticipate what mistakes people might make.

CLI principle: bias towards terminal, make it easy to get to browser

Help people stay in the terminal wherever they might want to maintain focus and reduce context switching. When it's necessary to jump to GitHub.com, make it obvious, fast, and easy. Certain actions are probably better to do in a visual interface.

CLI design considerations checklist

When designing for the command line, consider: (1) What the command does - what makes sense to do from a terminal, what might people want to automate, what is the default behavior and what flags might change that, what might people try and fail to do. (2) What the command is called - what should the command language system be, what should be a command vs a flag, how to align with existing commands. (3) What the command outputs - how to make the CLI feel like the GitHub.com version using color, language, spacing, info shown, how machine output should differ from interactive behavior. (4) How you explain your command - provide short and long descriptions for help pages. (5) How people discover your command - are there ways to integrate CLI into the feature where it exists on other platforms.

CLI prototyping with Google Docs

For simple quick illustrations of most CLI ideas, use a Google Docs template formatted with a dark background (File > Page Setup > Page Color), light text color, and monospace font. Mix up the background since people's setups change so much. Not everyone uses dark background. Make use of the document outline and headers to help communicate ideas.

CLI prototyping with Figma

If you need to show a process unfolding over time or need to show a prototype that feels more real to users, Figma or code prototypes are best. The Primer Command-Line Figma library is available at https://www.figma.com/file/zYsBk5KFoMlovE4g2f4Wkg/Primer-Command-Line (accessible to GitHub staff only).

CLI brand resource

Reference the GitHub Brand Content Guide at https://brand.github.com for guidance on using GitHub brand elements in CLI design.

Give your agent this brain