Comandante

Simple command line interfaces.

Example App

API Documentation

What is Comandante

Many command line tools are structured to accept subcommands. Like the go tool. When you run the go command you are presented with help text listing the available subcommands. Each subcommand has its own command line flags and documentation. Comandante makes creating binaries with subcommands easy.

So what does Comandante look like? Let's say that you are creating a program called "coolbinary" with two subcommands: "sayhi" and "demo". If you were to run coolbinary without a subcommand

$ coolbinary

you would get this output:

Do cool things from the commandline

Usage:
	coolbinary command [arguments]

Available commands:
demo   run a demo
help   get more information about a command
sayhi  say hello

Use "coolbinary help [command]" for more information about a command.

And the (over)simplified code that handles the subcommands:

bin := comandante.New("coolbinary", "Do cool things from the commandline")
bin.IncludeHelp() // comandante can create a "help" command for you

greetCmd := comandante.NewCommand("sayhi", "say hello", helloFunction)
greetCmd.Documentation = "This is longer form documentation for the sayhi command"
bin.RegisterCommand(greetCmd)

demoCmd := comandante.NewCommand("demo", "Run a demo", DemoFunction)
demoCmd.Documentation = "longer form documentation of the demo command"
bin.RegisterCommand(demoCmd)

// run the command
if err := bin.Run(); err != nil {
	fmt.Fprintln(os.Stderr, err)
}

If you were to invoke the sayhi subcommand

$ coolbinary sayhi

helloFunction would be called

Installation

Install to your GOPATH with

$ go get github.com/robmerrell/comandante

Usage

First step is to generate a new comandante with the name of your program and a short description:

bin := comandante.New("coolbinary", "Do cool things from the commandline")

We also want to include the autogenerated help command:

bin.IncludeHelp()

Now we add subcommands to that comandante instance. Creating a new subcommand takes a name and a short description.

greetCmd := comandante.NewCommand("sayhi", "say hello", helloFunction)
bin.RegisterCommand(greetCmd)

We also should give that subcommand a longer description for the autogenerated help:

greetCmd.Documentation = `
This is longer form documentation that describes this command in much greater detail.
`

Now register the subcommand with comandante:

bin.RegisterCommand(greetCmd)

Command line options

Subcommands can also handle their own command line options via FlagInit. These command line options are automatically displayed in the command's help text.

var testFlag string
greeterCmd.FlagInit = func(fs *flag.FlagSet) {
	fs.StringVar(&testFlag, "testing", "", "This is the usage")
}

License

The MIT License (MIT)

Copyright (c) 2013 Rob Merrell

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.