Home Explore Blog CI



nix

7th chunk of `doc/manual/source/development/cli-guideline.md`
4d601382183864da5cbb5233affe9d609154e665185d396600000001000008df
While colors are nice, when command line is used by machines (in automation
scripts) you want to remove the colors. There should be a global `--no-colors`
option that would remove the colors.

## Special (Unicode) characters

Most of the terminal have good support for Unicode characters and you should
use them in your output by default. But always have a backup solution that is
implemented only with ASCII characters and will be used when `--ascii` option
is going to be passed in. Please make sure that you test your output also
without Unicode characters

More they showing all the different Unicode characters it is important to
**establish common set of characters** that we use for certain situations.

## Emojis

Emojis help channel emotions even better than text, colors and special
characters.

We recommend **keeping the set of emojis to a minimum**. This will enable each
emoji to stand out more.

As not everybody is happy about emojis we should provide an `--no-emojis`
option to disable them. Please make sure that you test your output also without
emojis.

## Tables

All commands that are listing certain data can be implemented in some sort of a
table. It’s important that each row of your output is a single ‘entry’ of data.
Never output table borders. It’s noisy and a huge pain for parsing using other
tools such as `grep`.

Be mindful of the screen width. Only show a few columns by default with the
table header, for more the table can be manipulated by the following options:

- `--no-headers`: Show column headers by default but allow to hide them.
- `--columns`: Comma-separated list of column names to add.
- `--sort`: Allow sorting by column. Allow inverse and multi-column sort as well.

## Interactive output

Interactive output was selected to be able to strike the balance between
beginners and advance users. While the default output will target beginners it
can, with a few key strokes, be changed into and advance introspection tool.

### Progress

For longer running commands we should provide and overview the progress.
This is shown best in `nix build` example:

```shell
$ nix build
    Started building my-project 1.2.3
 Downloaded python3.8-poetry 1.2.3 in 5.3 seconds
 Downloaded python3.8-requests 1.2.3 in 5.3 seconds

Title: CLI Output: Colors, Characters, Emojis, Tables, and Interactive Elements
Summary
This section focuses on designing effective CLI output by considering various elements. It discusses removing colors for machine readability using `--no-colors`, providing ASCII alternatives for Unicode characters with `--ascii`, and minimizing emoji usage, controllable with `--no-emojis`. It outlines table formatting guidelines, including omitting borders and offering options like `--no-headers`, `--columns`, and `--sort` for customization. Finally, it highlights the importance of interactive output, including progress indicators for long-running commands to cater to both beginners and advanced users.