CLI verbosity levels

About

When working with a CLI users from different backgrounds who operate different tasks might want to see information with different verbosity levels. We have done a preliminary UX research on how general tasks can motivate users to want to view different verbosity levels as auxiliary information.

Standard verbosity modes in Canonical CLIs

The current standard verbosity levels can be segmented into 4 modes. The table below describes the interpretation of each mode. It is up to the CLI developer to make a decision for how they want to emit these output messages for their commands in different verbosity levels.

Which method from the Emitter should I use to present the information?

When a CLI developer is designing how they want to show output messages of the command, they need to understand the purpose of each verbosity level, what each level implies based on the details, and make a decision for which information they would like to show in the output. We will not constrain what constitutes an error or generic output. However, we will provide the general mindset behind each mode.

Caveat: Not all commands need to have all verbosity modes. For example, “snap info hello” might not need to have quiet mode.

The standard way to use the verbosity flag is

>$ --verbosity={ quiet | brief | verbose | debug | trace}

This flag should always be available when a CLI is created and it is a standard way to use the verbosity flag. However, some modes such as quiet or verbose can have a shorthand flag to accommodate the efficiency of CLI.

The description of each mode is described in the table below.

Mode Shorthand Flag Analogy Detail
Quiet - - quiet / -q No message needed. Users care about this mode when they don’t need to know the response. Therefore, it is not necessary to disclose any message in the output unless there is an error.
Brief [default] usually printf() In a normal or brief mode, the output serves as a user interface message. For instance, things that you want to log from the console. Not all apps have the machine output that is human readable. (Including progress information). “Printf” is an analogy for what you show to a user/client in a way that is easily understandable or human readable. For instance, Snap (client) has a very specific CLI. For instance, snap install, gets user interface messages for CLI tools.
Verbose - -verbose / -v logf In verbose mode, you want to talk to the audiences in a more descriptive and thorough description about what happens in transactions or a series of events. This could be a conversation log between a user/client and the machine. A user would want to see this mode when they want to audit events or transactions between the client and the machine so they know where the possible struggle points are. “Logf” is used as an analogy to show that the mental model of when a user logs something, they expect to see a thorough explanation of the transactions between client and machine.
Errorf (optional) In verbose mode, it is optional to define what can be construed as errors as a separate message. Errorf is an analogy to describe how a CLI developer would classify a log as a failure of the application. Certain events can be the cause for the app to struggle, such as when it runs out of memory. If the distinction between verbose mode and debug mode is well defined, specifying what constitutes an error that causes the application to struggle is not necessary.
Debug none debugf In debug mode, the mental model is to think of 2 developers talking to one another trying to understand where things go wrong. These are not messages that you would want to represent for normal people to read. It can be described as a message that shows your internal execution steps. The essence here is that an audience would want to understand why things are failing or performing forensics on the produced logs.
Trace none tracing Tracing in this context is more of an action of asking an automated system. It can be construed as a special mode for debug messages, but not on its own. You can see it as a way the developer is asking a system to tell you where the execution is in the code structure.

How do I show progress bar information?

Using Craft-CLI to work with verbosity

If you are developing a software or CLI application in python, the Craft-CLI is a standard CLI library designed to help you create a command line following the Canonical CLI guidelines.

If the command that you are designing involves showing the progress bar in normal mode and above, you can either design a progress bar to override the previous one or show multiple progress bars running in parallel. When you use the Craft-CLI library to show progress bars, it will not show in the log files, but progress bars will be present in all modes.

If a progress bar comes with messages attached to it, the message will be in the log file but not the progress bar. For instance, when a user downloads or uploads a file, there may be values such as download: 20% out of 100%, time elapse, or download speed information that comes with the progress bar. This information will be present in the log file, but not the progress bar.

For more examples, visit Craft-CLI repo.

Example of the information in normal mode from the craft library emitter.

|691.2680617619926x224.20652886012977

Example of verbose mode and the extra information that the emitter shows.

|691.2680617619926x223.98615557474093

1 Like