CLI verbosity levels

[amylily]

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 [DEFAULT] | 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.

---

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.

Regarding the Emitter methods to show outputs

The developer will have several methods in Emitter to show different intended outputs:

• ‘message’: Used for the final message to the user, to show the result of a command.
• 'progress’: Progress information for a multi-step command. This is normally used to present several separated text messages. If a progress message is important enough that it should not be overwritten by the next ones, the ‘permanent=True’ flag can be used.
• ‘progress_bar’: Progress information for a potentially long-running single step of a command. E.g. a download or provisioning step.
• ‘open_stream’: Used to capture all the output when running subprocesses.
• ‘verbose’: Useful to provide more information to the user that shouldn’t be exposed when in brief mode for clarity and simplicity.
• ‘debug’: To record everything that the user may not want to normally see but useful for the app developers to understand why things are failing or performing forensics on the produced logs.
• ‘trace’: A way to expose system-generated information, about the general process or particular information, which in general would be too overwhelming for debugging purposes but sometimes needed for particular analysis.

Not directly used by the developer during a command execution, but there are two other moments where text is shown: ending in error and logs from underlying libraries.

Ending in error includes several situations (the command raising CraftError, getting an unexpected exception, the user generating a keyboard interrupt, etc.), but for the purpose of this document all those situations behave in the same way, so in the table below they are just expressed as “error ending”.

Also, the Craft CLI library will hook on the logging subsystem and capture all logs produced through there. These logs will be exposed in different ways according to the indicated logging level.

How Craft CLI show texts according to the selected verbosity levels

This is how texts are exposed to the screen for the different situations according to the selected verbosity level by the user running the application.
The last column of the table though is not about the screen: it indicates if the information will be present in the log created automatically by Craft CLI.

How do I show progress bar information?

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, except quiet.

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.

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