Commando helps you create beautiful CLI applications with ease. It parses "getopt(3)" style command-line arguments, supports sub-command architecture, allows a short-name alias for flags and captures required & optional arguments. The motivation behind creating this library is to provide easy-to-use APIs to create simple command-line tools.
This library uses
clapperpackage to parse command-line arguments. Visit the documentation of this package to understand supported arguments and flag patterns.
$ go get -u "github.com/thatisuday/commando"
Let's imagine we are building a CLI tool reactor to generate and manage React front-end projects.
$ reactor --version
$ reactor -v
$ reactor --help
$ reactor -h
In the example above, the reactor alone is the root-command. Here, the --version and -v are flags. The --version is a long flag name and -v is a short flag name. The -v is an alias for --version. Similarly --help and -h are flags.
Commando adds
--versionand--helpflags (along with their aliases) automatically for the root-command.
$ reactor build --dir ./out/dir
In the above example, build is a sub-command. This sub-command has --dir flag, and unlike --help flag, this flag takes a user-input value like ./out/dir we have provided above.
Commando adds
--helpflag automatically for a sub-command. Also, it registershelpandversionsub-commands automatically to display CLI usage and version number respectively.
$ reactor create <name> --dir <dir>
In the above example, create is a sub-command. The <name> placeholder is for the name argument value that the user is supposed to provide. For example, $ reactor create form --dir ./components/form. Here, form is the value for the name argument.
The root-command can also be configured to take arguments. For example,
$ reactor <category>command is valid. If thecategoryargument value doesn't match with any registered sub-command, then the root-command is executed, else the sub-command is executed.
First, we need to specify the name of the executable file using commando.SetExecutableName function. This value is same as your root-command name. You can use os.Executable function to get the name of the executable. Normally, you just specify the name of your package because when the user install your module using go get command, Go creates an executable file with the name same as your package name.
Then we need to set the version and the description of our CLI application using CommandRegistry.SetVersion and CommandRegistry.SetDescription function respectively. This version will be displayed with the --version flag (or version sub-command) and description will be displayed with --help flag (or help sub-command).
import "github.com/thatisuday/commando"
func main() {
commando.
SetExecutableName("reactor").
SetVersion("v1.0.0").
SetDescription("This CLI tool helps you create and manage React projects.")
}A sub-command is registered using commando.Register("<sub-command>") function. This function returns the *commando.Command object. If the sub-command is already registered, it returns the registered *commando.Command object.
If nil is passed as an argument, then the root-command is registered. However, Commando automatically registers the root-command and commando.Register(nil) returns the *commando.Command object of the root-command.
Commando automatically registers the root-command to provide built-in support for
--helpand--versionflags, hence you do not need to manually register the root-command unless you want to configure it.
The *commando.Command object is a struct and it provides SetDescription, AddArgument, AddFlag, and SetAction methods.
- The
SetDescriptionmethod sets the description of the command. - The
AddArgumentmethod registers an argument with the command. - The
AddFlagmethod registers a flag with the command. - The
SetActionmethod registers a function that will be executed with argument values and flag values provided by the user when the root-command or a sub-command is executed by the user.
commando.
Register("<sub-command>").
SetDescription("<sub-command-description>")
SetShortDescription("<sub-command-short-description>")The SetDescription and SetShortDescription method takes a string argument tp set the long and a short description of the sub-command and returns the *commando.Command object of the same command. These descriptions are printed when user executes the $ reactor <sub-command> --help command.
You can set a description of the root-command by passing
nilas an argument to theRegister()function.
commando.
Register("<sub-command>").
AddArgument("<name>", "<description>", "<default-value>")The AddArgument method registers an argument with the command. The first argument is the name of the argument and the second argument is the description of that argument.
The third argument is a string value which is the default-value of the argument. If user doesn't provide the value of this argument, this argument will get the value from the default-value. If the default-value is an empty string (""), then it becomes a required argument. If the value of a required argument is not provided by the user, an error message is displayed.
Ideally, you should register all required arguments before the optional arguments. Since these are positional values, it is mandatory to do so, else you would get inappropriate results.
If the argument name ends with ... suffix, then it is considered as a variadic argument. A variadic argument stores all the leftover argument values and concatenate them using command comma (,). Hence a command should only contain one variadic argument and it should be registered after all arguments are registered.
If the argument is already registered, then registration of the argument is skipped without returning an error. You can configure arguments of the root-command by passing
nilas an argument to theRegister()function.
commando.
Register("<sub-command>").
AddFlag("<long-name>,<short-name>", "<description>", <dataType>, <defaultValue>).The AddFlag method registers a flag with the command. The first argument is string value containing the long-name and the short-name of the flag separated by a comma. For example, dir,d is a valid argument value for --dir and -d flags. You can skip the short-name registration if you do not need one by providing only long-name value, like dir.
The second argument sets the description of the flag. This will be displayed with the usage of the command (--help flag).
The third argument is the data-type of the value that will be provided by the user for this flag. The value of this argument could be either commando.Bool, commando.Int or commando.String. If the data-type is commando.Bool, then the flag does not take any user input (like --version flag).
The last argument is the default-value of the flag. The value of this argument must be of the data-type provided in the previous argument. If nil value is provided, then the flag doesn't have any default-value and it becomes required to be provided by the user, except if the data-type is commando.Bool in which case the default-value is false automatically.
If the flag name starts with no- prefix, for example no-clean, then it is considered as an inverted flag. Default value of an inverted flag is true. When --no-clean flag is provided, value of this flag becomes false. This flag is stored without no- prefix, like clean here, however, --clean is not a valid flag.
If the flag is already registered, then registration of the flag is skipped without returning an error. You should avoid using the same short-name for multiple flags. You can configure flags of the root-command by passing
nilas an argument to theRegister()function.
commando.
Register("<sub-command>").
SetAction(func(args map[string]commando.ArgValue, flags map[string]commando.FlagValue) {
})The SetAction function registers a callback function that will be executed when the root-command or the sub-command is executed by the user. This function is called with the argument values and the flag values provided by the user. If the required argument or a required flag is not provided by the user, this function won't be executed and an error message is shown to the user.
The first argument is a map that contains the argument values. The keys of this map are names of the arguments and values are the values of the arguments provided by the user. The values of this map are structs of type commando.ArgValue that contains the argument value and other meta-data provided by you during the registration of the argument.
The second argument is a map that contains the flag values. The keys of this map are long-names of the flags and values are the values of the flags provided by the user (or the default-values). The values of this map are structs of type commando.FlagValue that contains the flag value and other meta-data provided by you during the registration of the flag.
The data-type of the Value field of the commando.ArgValue type is string. However, the data-type of the commando.FlagValue type is an empty interface interface{}. The concrete value of this field can be a bool, an int or a string based on the data-type specified in the flag registration. You should manually extract the concrete value using type-assertion. The commando.FlagValue also provides GetBool, GetInt and GetString methods to return the flag-value in the correct format.
commando.Parse(nil)The Parse function parses the command-line arguments provided by the user. Commando executes a sub-command or the root-command based on these values. If the sub-command is not registered or arguments/flags values provided by the user are invalid, then an error message is shown to the user. Else, the action function registered with the command is executed.
commando.Parse([]string{})You can also pass a custom list of command-line arguments. In this case, Commando won't read command-line arguments from the standard-input (terminal).
package main
import (
"fmt"
"github.com/thatisuday/commando"
)
func main() {
// set CLI executable, version and description
commando.
SetExecutableName("reactor").
SetVersion("v1.0.0").
SetDescription("Reactor is a command-line tool to generate React projects.\nIt helps you create components, write test cases, start a development server and much more.").
SetEventListener(func(eventName string) {
//fmt.Println("event-name: ", eventName)
})
// configure the root-command
// $ reactor <category> --verbose|-V --version|-v --help|-h
commando.
Register(nil).
AddArgument("category", "category of the information to look for", ""). // required
AddFlag("verbose,V", "display log information ", commando.Bool, nil). // optional
SetAction(func(args map[string]commando.ArgValue, flags map[string]commando.FlagValue) {
// print arguments
for k, v := range args {
fmt.Printf("arg -> %v: %v(%T)\n", k, v.Value, v.Value)
}
// print flags
for k, v := range flags {
fmt.Printf("flag -> %v: %v(%T)\n", k, v.Value, v.Value)
}
})
// register `create` sub-command
// $ reactor create <name> [version] [files] --dir|-d <dir> --type|-t [type] --timeout [timeout] --verbose|-v --help|-h --no-clean
commando.
Register("create").
SetDescription("This command creates a component of a given type and outputs component files in the project directory.").
SetShortDescription("creates a component").
AddArgument("name", "name of the component to create", ""). // required
AddArgument("version", "version of the component", "1.0.0"). // optional
AddArgument("files...", "files to remove once component is created", ""). // variadic, optional
AddFlag("dir, d", "output directory for the component files", commando.String, nil). // required
AddFlag("type, t", "type of the component to create", commando.String, "simple_type"). // optional
AddFlag("timeout", "operation timeout in seconds", commando.Int, 60). // optional
AddFlag("verbose,v", "display logs while creating the component files", commando.Bool, nil). // optional
AddFlag("no-clean", "avoid cleanup of the component directory", commando.Bool, nil). // optional, inverted flag
SetAction(func(args map[string]commando.ArgValue, flags map[string]commando.FlagValue) {
// print arguments
for k, v := range args {
fmt.Printf("arg -> %v: %v(%T)\n", k, v.Value, v.Value)
}
// print flags
for k, v := range flags {
fmt.Printf("flag -> %v: %v(%T)\n", k, v.Value, v.Value)
}
})
// register `serve` sub-command
// $ reactor serve --verbose|-v --help|-h
commando.
Register("serve").
SetDescription("This command starts the Webpack dev-server on an available port.").
SetShortDescription("starts a development server").
AddFlag("verbose,v", "display logs while serving the project", commando.Bool, nil). // optional
SetAction(func(args map[string]commando.ArgValue, flags map[string]commando.FlagValue) {
// print arguments
for k, v := range args {
fmt.Printf("arg -> %v: %v(%T)\n", k, v.Value, v.Value)
}
// print flags
for k, v := range flags {
fmt.Printf("flag -> %v: %v(%T)\n", k, v.Value, v.Value)
}
})
// register `build` sub-command
// $ reactor build --dir|-d <dir> --verbose|-v --help|-h
commando.
Register("build").
SetDescription("This command builds the project with Webpack and outputs the build files in the given directory.").
SetShortDescription("creates build artifacts").
AddFlag("dir,d", "output directory of the build files", commando.String, nil). // required
AddFlag("verbose,v", "display logs while serving the project", commando.Bool, nil). // optional
SetAction(func(args map[string]commando.ArgValue, flags map[string]commando.FlagValue) {
// print arguments
for k, v := range args {
fmt.Printf("arg -> %v: %v(%T)\n", k, v.Value, v.Value)
}
// print flags
for k, v := range flags {
fmt.Printf("flag -> %v: %v(%T)\n", k, v.Value, v.Value)
}
})
// parse command-line arguments from the STDIN
commando.Parse(nil)
}$ reactor --help
$ reactor -h
$ reactor help
Reactor is a command-line tool to generate React projects.
It helps you create components, write test cases, start a development server and much more.
Usage:
reactor <category> {flags}
reactor <command> {flags}
Commands:
build creates build artifacts
create creates a component
help displays usage informationn
serve starts a development server
version displays version number
Arguments:
category category of the information to look for
Flags:
-h, --help displays usage information of the application or a command (default: false)
-V, --verbose display log information (default: false)
-v, --version displays version number (default: false)
You can use
CommandRegistry.SetEventListenerfunction to add a callback function when usage information is displayed.
$ reactor version
$ reactor --version
$ reactor -v
Version: v1.0.0
You can use
CommandRegistry.SetEventListenerfunction to add a callback function when version information is displayed.
$ reactor create --help
$ reactor create -h
This command creates a component of a given type and outputs component files in the project directory.
Usage:
reactor <name> [version] [files] {flags}
Arguments:
name name of the component to create
version version of the component (default: 1.0.0)
files files to remove once component is created {variadic}
Flags:
--no-clean avoid cleanup of the component directory (default: true)
-d, --dir output directory for the component files
-h, --help displays usage information of the application or a command (default: false)
--timeout operation timeout in seconds (default: 60)
-t, --type type of the component to create (default: simple_type)
-v, --verbose display logs while creating the component files (default: false)
$ reactor --verbose
Error: value of the category argument can not be empty.
Oops! A user needs to provide the value of the category argument since it is a required argument.
$ reactor service --verbose
$ reactor service -V
arg -> category: service(string)
flag -> version: false(bool)
flag -> help: false(bool)
flag -> verbose: true(bool)
$ reactor create
Error: value of the name argument can not be empty.
Oops! A user needs to provide the value of the name argument since it is a required argument.
$ reactor create my-service
Error: value of the --dir flag can not be empty.
Oops! A user needs to provide the value of the dir flag since it is a required argument (no default-value).
$ reactor create my-service -t service --dir ./service/my-service --timeout 10sec
Error: value of the --timeout flag must be an integer.
Oops! Since we have specified that the value of the --timeout flag must be an integer, a user needs to provide an integer value.
$ reactor create my-service -t service --dir ./service/my-service --timeout 10
arg -> name: my-service(string)
arg -> version: 1.0.0(string)
arg -> files: (string)
flag -> dir: ./service/my-service(string)
flag -> type: service(string)
flag -> timeout: 10(int)
flag -> verbose: false(bool)
flag -> clean: true(bool)
flag -> help: false(bool)
Here, the value of the version argument the default value we provided earlier since the user did not provide any value for it. Also, since it is an optional argument, Commando did not print any errors.
$ reactor create my-service 2.0.5 file1.txt file2.txt file3.txt -t service --dir=./service/my-service --timeout 10 -v --no-clean
arg -> name: my-service(string)
arg -> version: 2.0.5(string)
arg -> files: file1.txt,file2.txt,file3.txt(string)
flag -> help: false(bool)
flag -> dir: ./service/my-service(string)
flag -> type: service(string)
flag -> timeout: 10(int)
flag -> verbose: true(bool)
flag -> clean: false(bool)
The example above is a clear demonstration of how a CLI application can be created, however, you can follow this tutorial on Medium. Here are a few things you should be concerned about.
- Keep your argument names and flag names as simple as possible.
- Try not to override the
--helpor--versionflags and their short-names. - Do not configure the root-command unless necessary. You do not need to set an action function for the root-command. If the action function is missing for the root-command, it won't generate any output or an error.
- Register all optional arguments of a command before the required arguments.
- Do not modify commands after
commando.Parse()is called.
Your code must be part of the main package like we have seen in the previous example. It's better if your work with the [Go modules] so that a user can install your application from anywhere on the system.
A user can install the CLI application using GO111MODULE=on go get "github.com/<username>/<module-name>" command. Since your code is part of the main package, Go creates <module-name> binary executable file inside GOBIN directory that is supposed to be in the PATH of the system.