Commando configuration

Inside tree.go file, we need to import commando module and configure it to add the above commands, arguments, and flags. The example below is a minimal setup of Commando for our command-line application. Let’s talk about each line of code and what it does.

Application Information

First, we need to provide some information about our CLI application. The following piece of code exactly does that.

// configure commando

commando.

SetExecutableName("tree").

SetVersion("1.0.0").

SetDescription("This tool lists the contents ...")

The commando.SetExecutableName function sets the name of the executable file that the user is going to use. This is the same as your module name. In our case, this will be tree since the name of our module is tree or since the user is going to use tree command ( tree executable file).

The SetVersion function sets a version with the CLI application. This version is displayed when the user uses --version flag or version command. Similarly, SetDescription adds some information about our CLI tool.

Root command and sub-commands

A sub-command is a command that is used with the root command. In our application, tree is the top command, hence it is the root command. Since the info command is used with tree like tree info , it is a sub-command.

In order to configure the root command or a sub-command, we need to register them first with Commando. However, Commando comes with the root command to provide tree --version or tree --help functionality.

We register a command using commando.Register function.

The argument of this function is the name of the sub-command. If the sub-command is already registered, it returns the *Command object of that command so that we can re-configure it.

If the nil argument is passed, it returns the *Command object of the root command since it is already registered by the Commando.

💡 Commando adds --help flag with a sub-command. It also adds version and help sub-commands to display version and usage information.

Configure arguments

The AddArgument function adds an argument to the command (root or sub).

The name argument is the name of the command argument, for example, dir in our case. The desc argument is the description of the argument. This description is used while displaying the usage of the CLI application.

The defaultValue argument is the default value of the argument in case if the user doesn’t provide the value for it. If the default value is provided, then the argument becomes optional. All optional arguments should be registered first.

Configure flags

The AddFlag function adds a flag to the command (root or sub).

The flagNames argument contains the long-name and short-name of the flag. These should be separated by a comma. For example, “level,l” is the flag names for the --level and -l flags. You can omit short-name if you want.

The desc argument is the description of the flag. This description is used while displaying the usage of the CLI application. The dataType is the expected data type of the flag value.

If commando.Bool is used for the dataType argument, the flag doesn’t take any user input, like --version . The default value of a boolean flag is false hence defaultValue should be nil .

If commando.Int is used for the dataType argument, then the expected value to be provided by the user is an integer. The defaultValue could be set to nil in which case the flag value becomes required to be provided by the user.

If commando.String is used for the dataType argument, then the expected value to be provided by the user is a string. The defaultValue could be set to nil in which case the flag value becomes required to be provided by the user.

Set an action function

An action function is a callback function registered with a command (root or sub) that will be executed when the user provides command-line arguments to execute the root command or a sub-command.

This callback function is added to a command using SetAction function. This function receives the argument values as the first argument and flag values as the second argument. Each of these arguments is a map whose keys represent the argument and flag names (long-names).

The ArgValue struct has Value field which contains the argument value provided by the user. If the argument is optional and the user did not provide a value, then it contains the default value.



Arg

Value

} type ArgValue struct {Value string

The FlagValue struct has Value field which contains the flag value provided by the user. If the flag is optional and the user did not provide a value, then it contains the default value.



Flag

Value interface{}

} type FlagValue struct {Value interface{}

Since the flag value can be a bool , an int or a string value, its data type is an empty interface{} . Using type-assertion, you can extract the concrete value of the interface. However, you can use GetBool , GetInt and GetString methods to extract the concrete value.

Parse command-line arguments

After registration and configuration of command, arguments and flags are done, Commando has the knowledge of what to look for in the command-line arguments provided by the user.

The commando.Parse function parses the command-line arguments passed to it using the osArgs argument. If the osArgs argument is nil , the Commando parses the command-line arguments from the terminal (STDIN). Normally, you should pass nil as an argument.

Commando after parsing the command-line arguments executes an action function with the provided argument and flag values. If there is an error while parsing these command-line arguments, an error message is displayed to the user and action function is never executed.