flâneur

Rita Zerrizuela

0 followers · 282 views

on the atlas — 6

highlights — 68

  • Sometimes printing tables can grow to be too long to reasonably fit in the CLI. Using the --json flag allows plugin developers to provide users with much more data but still give them the ability to parse.
    CLI Style Guide
  • Human-readable output should be grep-parseable, but not necessarily awk-parseable.
    CLI Style Guide
  • Terse, machine-readable output formats can also be useful but shouldn’t get in the way of making beautiful CLI output. When needed, commands should offer a --json and/or a --terse flag when valuable to allow users to easily parse and script the CLI.
    CLI Style Guide
  • Color can be disabled by the user by adding --no-color, setting COLOR=false, or when the output is not a tty.
    CLI Style Guide
  • Be mindful with color. Too many contrasting colors in the same place can quickly begin to compete for the user’s attention. Using just a couple of colors and maybe dim/bolding existing ones can often provide enough contrast.
    CLI Style Guide
  • Using color is encouraged in commands to help the user quickly read command output. Some nouns in the CLI such as apps and config vars have standard colors that should be used when possible
    CLI Style Guide
  • Action commands are those that perform some remote task.
    CLI Style Guide
  • Output commands are simply commands that display data to the user. They take many forms, but the simplest is just printing to stdout
    CLI Style Guide
  • In general the CLI offers 2 types of commands, output commands that show data, as well as action commands that perform an action.
    CLI Style Guide
  • Arguments are the basic way to provide input for a command. While flags are generally preferred, they are sometimes unnecessary in cases where there is only 1 argument, or the arguments are obvious and in an obvious order.
    CLI Style Guide
  • Ensure that descriptions are provided for all flags
    CLI Style Guide
  • Flags are preferred to args. They involve a bit more typing, but make the use of the CLI clearer.
    CLI Style Guide
  • Input to commands is typically provided by flags and args. Stdin can also be used in cases where it is useful to stream files or information in
    CLI Style Guide
  • Input and output should be consistent across commands to allow the user to easily learn how to interact with new commands.
    CLI Style Guide
  • The Heroku CLI is for humans before machines. The primary goal of anyone developing CLI plugins should always be usability.
    CLI Style Guide
  • For cache files though, use ~/.cache/myapp on Unix but on MacOS it’s better to default to ~/Library/Caches/myapp. On Windows you can use %LOCALAPPDATA%\myapp.
    12 Factor CLI Apps
  • XDG-spec is a great standard that should be used to find out where to put files. Unless environment variables like XDG_CONFIG_HOME say otherwise, use ~/.config/myapp for config files, and ~/.local/share/myapp for data files.
    12 Factor CLI Apps
  • Single-command CLIs are basic UNIX-style CLIs like cp or grep. Multi-commands are more like git or npm which accept a subcommand as the first argument.
    12 Factor CLI Apps
  • 11. Be clear about subcommands
    12 Factor CLI Apps
  • This allows users to poke around and diagnose problems themselves.
    12 Factor CLI Apps
  • 10. Encourage contributions
    12 Factor CLI Apps
  • 100ms–500ms: fast enough, aim here
    12 Factor CLI Apps
  • <100ms: very fast (sadly, not feasible for scripting languages)
    12 Factor CLI Apps
  • Allow output in csv or json.
    12 Factor CLI Apps
  • Allow sorting by column with --sort. Allow inverse and multi-column sort as well.
    12 Factor CLI Apps
  • Allow users to pass --filter to filter specific columns. (grep can usually do this, but a flag can filter on specific cell values)
    12 Factor CLI Apps
  • Show column headers by default but allow them to be hidden with --no-headers.
    12 Factor CLI Apps
  • Truncate rows that are going to spill over the current screen width unless --no-truncate is set.
    12 Factor CLI Apps
  • Be mindful of the screen width. Only show a few columns by default but allow the user to pass --columns with a comma-separated list of column names to add less common types.
    12 Factor CLI Apps
  • By keeping each row to a single entry, you can do things like pipe to wc to get the count of lines, or grep to filter each line
    12 Factor CLI Apps
  • Never output table borders. It’s noisy and a huge pain for parsing.
    12 Factor CLI Apps
  • For accepting input, if stdin is a tty then prompt rather than forcing the user to specify a flag. Never require a prompt though. The user needs to be able to automate your CLI in a script so allow them to override prompts always.
    12 Factor CLI Apps
  • I would also suggest adding in an app-specific MYAPP_NOCOLOR=1 environment variable as well in case they want to disable color on just your CLI.
    12 Factor CLI Apps
  • 7. Prompt if you can
    12 Factor CLI Apps
  • Use colors/dimming to highlight important information. Use spinners and progress bars to show long-running tasks to tell the user you’re still working. Leverage OS notifications when a very long-running task is done.
    12 Factor CLI Apps
  • Error logs can also be useful for post-mortem debugging but ensure they have timestamps, truncate them occasionally so they don’t eat up space on disk, and make sure they don’t contain ansi color codes.
    12 Factor CLI Apps
  • Sometimes though you will have unhandled errors you didn’t expect the user to run into. For that, have a way to view full traceback information as well as full debug output with environment variables.
    12 Factor CLI Apps
  • Things go wrong in CLIs much more often than in web apps. Without a UI to guide the user, the only thing we can do is display an error to the user. This is expected behavior and part of using any CLI.
    12 Factor CLI Apps
  • First and foremost, make your errors informative. A great error message should contain the following: Error code Error title Error description (Optional) How to fix the error URL for more information
    12 Factor CLI Apps
  • 5. Handle things going wrong
    12 Factor CLI Apps
  • stdout is for output, stderr is for messaging.
    12 Factor CLI Apps
  • I also suggest sending the version string as the User-Agent so you can debug server-side issues. (Assuming your CLI uses an API of some sort)
    12 Factor CLI Apps
  • The version command is a main place you’ll ask users for debugging information so it’s a good place to add any helpful extra information aside from just the version number that might help you diagnose issues.
    12 Factor CLI Apps
  • 3. What version am I on?
    12 Factor CLI Apps
  • For CLIs that pass flags off to some other process (such as heroku run), the flag parser should accept a -- argument to denote that it should stop parsing and simply pass everything down as an argument.
    12 Factor CLI Apps
  • For variable length arguments, it’s fine to have multiple arguments. (For example, $ rm file1 file2 file3). It’s just when they’re different types that it becomes confusing to the user.
    12 Factor CLI Apps
  • Sometimes args are just fine though when the argument is obvious such as $ rm file_to_remove. A good rule of thumb is 1 type of argument is fine, 2 types are very suspect, and 3 are never good.
    12 Factor CLI Apps
  • 2. Prefer flags to args
    12 Factor CLI Apps
  • provide examples of common usage of the CLI. Even if the usage is obvious to you, it’s by far the most common referenced bit of documentation users will find.
    12 Factor CLI Apps
  • A CLI should provide in-CLI help and help on the web (READMEs are a great place). That provides the immediate-ness of not needing to leave the terminal
    12 Factor CLI Apps