Command line interface framework
Go framework for rapid command line application development.
Example
package main
import "gopkg.in/ukautz/clif.v1"
func main() {
clif.New("My App", "1.0.0", "An example application").
New("hello", "The obligatory hello world", func(out clif.Output) {
out.Printf("Hello World\n")
}).
Run()
}
Install
$ go get gopkg.in/ukautz/clif.v1
Getting started
On the one side, CLIF's builder-like API can be easily used for rapid development of small, single purpose tools. On the other side, CLIF is designed with complex console applications in mind.
Commands
Commands must have a unique name and can have additional arguments and options.
cmd1 := clif.NewCommand("name", "A description", callBackFunction)
cmd2 := clif.NewCommand("other", "Another description", callBackFunction2)
The name
is used from the command line to call the command:
$ ./app name
$ ./app other
Callback functions
Callback functions can have arbitrary parameters. CLIF uses a small, built-in (signatur) injection container which allows you to register any kind of object (struct
or interface
) beforehand.
So you can register any object (interface{}, struct{} .. and anything else, see below) in your bootstrap and then "require" those instances by simply putting them in the command callback signature:
type MyFoo struct {
X int
}
func main() {
cli := clif.New("My App", "1.0.0", "An example application")
foo := &MyFoo{X: 123}
cli.Register(foo)
cli.NewCommand("foo", "Call foo", func (foo *MyFoo) {
})
cli.Run()
}
Using interfaces is possible as well, but a bit less elegant:
type MyBar interface {
Bar() string
}
type MyFoo struct {
}
func (m *MyFoo) Bar() string {
return "bar"
}
func main() {
cli := clif.New("My App", "1.0.0", "An example application")
foo := &MyFoo{}
t := reflect.TypeOf((*MyBar)(nil)).Elem()
cli.RegisterAs(t.String(), foo)
cli.NewCommand("bar", "Call bar", func (bar MyBar) {
})
cli.Run()
}
Named
Everything works great if you only have a single instance of any object of a specific type.
However, if you need more than one instance (which might often be the case for primitive
types, such as int
or string
) you can use named registering:
cli.RegisterNamed("foo", new(MyFoo)).
RegisterNamed("bar", 123).
RegisterNamed("baz", "bla")
cli.NewCommand("bar", "Call bar", func (named clif.NamedParameters) {
asMap := map[string]interface{}(named)
fmt.Println(asMap["baz"].(string))
})
Note: If you want to use the named feature, you cannot Register()
any NamedParameters
instance yourself, since "normally" registered objects are evaluated before named.
Default objects
CLIF pre-populates the dependency container with a couple of built-in objects:
- The
Output
(formatted output helper, see below), eg func (out clif.Output) { .. }
- The
Input
(input helper, see below), eg func (in clif.Input) { .. }
- The
*Cli
instance itself, eg func (c *clif.Cli) { .. }
- The current
*Command
instance, eg func (o *clif.Command) { .. }
Arguments and Options
CLIF can deal with arguments and options. The difference being:
- Arguments come after the command name. They are identified by their position.
- Options have no fixed position. They are identified by their
--opt-name
(or alias, eg -O
)
Of course you can use arguments and options at the same time..
Arguments
Arguments are additional command line parameters which come after the command name itself.
cmd := clif.NewCommand("hello", "A description", callBackFunction)
.NewArgument("name", "Name for greeting", "", true, false)
arg := cmd.NewAgument("other", "Something ..", "default", false, true)
cmd.AddArgument(arg)
Arguments consist of a name, a description, an optional default value a required flag and a multiple flag.
$ ./my-app hello the-name other1 other2 other3
Position of arguments matters. Make sure you add them in the right order. And: required arguments must come before optional arguments (makes sense, right?). There can be only one multiple argument at all and, of course, it must be the last (think: variadic).
You can access the arguments by injecting the command instance *clif.Command
into the callback and calling the Argument()
method. You can choose to interpret the argument as String()
, Int()
, Float()
, Bool()
, Time()
or Json()
. Multiple arguments can be accessed with Strings()
, Ints()
.. and so on. Count()
gives the amount of (provided) multiple arguments and Provided()
returns bool for optional arguments. Please see parameter.go for more.
func callbackFunctionI(c *clif.Command) {
name := c.Argument("name").String()
others := c.Argument("other").Strings()
}
Options
Options have no fixed position, meaning ./app --foo --bar
and ./app --bar --foo
are equivalent. Options are referenced by their name (eg --name
) or alias (eg -n
). Unless the option is a flag (see below) it must have a value. The value must immediately follow the option. Valid forms are: --name value
, --name=value
, -n value
and -n=value
.
Options must come before the command, unless they use the =
separator. For example: ./app command --opt value
is valid, ./app --opt=value command
is valid but ./app --opt value command
is not valid (since it becomes impossible to distinguish between command and value).
cmd := clif.NewCommand("hello", "A description", callBackFunction)
.NewOption("name", "n", "Name for greeting", "", true, false)
arg := cmd.NewOption("other", "O", "Something ..", "default", false, true)
cmd.AddOption(arg)
Now:
$ ./my-app hello --other bar -n Me -O foo
You can access options the same way as arguments, just use Option()
instead.
func callbackFunctionI(c *clif.Command) {
name := c.Option("name").String()
others := c.Option("other").Strings()
}
Flags
There is a special kind of option, which does not expect a parameter: the flag. As options, their position is arbitrary.
flag := clif.NewFlag("my-flag", "f", "Something ..", false)
flag = clif.NewOption("my-flag", "f", "Something ..", "", false, false).IsFlag()
cmd := clif.NewCommand("hello", "A description", callBackFunction).AddOption(flag)
When using the option, you dont need to (nor can you) provide an argument:
$ ./my-app hello --my-flag
You want to use Bool()
to check if a flag is provided:
func callbackFunctionI(c *clif.Command) {
if c.Option("my-flag").Bool() {
}
}
Validation & (Parsing | Transformation)
You can validate/parse/transform the input using the Parse
attribute of options or arguments. It can be (later on)
set using the SetParse()
method:
arg := clif.NewArgument("my-int", "An integer", "", true, false).
SetParse(func(name, value string) (string, error) {
if _, err := strconv.Atoi(value); err != nil {
return "", fmt.Errorf("Oops: %s is not an integer: %s", name, err)
} else {
return value, nil
}
})
opt := clif.NewOption("client-id", "c", "The client ID", "", true, false).
SetParse(func(name, value string) (string, error) {
if strings.Index(value, "#") != 0 {
return fmt.Sprintf("#%s", value), nil
} else {
return value, nil
}
})
There are a few built-in validators you can use out of the box:
clif.IsInt
- Checks for integer, eg clif.NewOption(..).SetParse(clif.IsInt)
clif.IsFloat
- Checks for float, eg clif.NewOption(..).SetParse(clif.IsFloat)
See validators.go.
Environment variables & default
The argument and option constructors (NewArgument
, NewOption
) already allow you to set a default. In addition you can set
the name of an environment variable, which will be used, if the parameter is not provided.
opt := clif.NewOption("client-id", "c", "The client ID", "", true, false).SetEnv("CLIENT_ID")
The order is:
- Provided, eg
--config /path/to/config
- Environment variable, eg
CONFIG_FILE
- Default value, as provided in constructor or set via
SetDefault()
Note: A required parameter must have a value, but it does not care whether it came from input, via environment variable or as a default value.
Default options
Often you need one or multiple options on every or most commands. The usual --verbose
or --config /path..
are common examples.
CLIF provides two ways to deal with those.
- Modifying/extending
clif.DefaultOptions
(it's pre-filled with the --help
option, which is clif.DefaultHelpOption
) - Calling
AddDefaultOptions()
or NewDefaultOption()
on an instance of clif.Cli
The former is global (for any instance of clif.Cli
) and assigned to any new command (created by the NewCommand
constructor). The latter is applied when Run()
is called and is in the scope of a single clif.Cli
instance.
Note: A helpful patterns is combining default options and the injection container/registry. Following an example parsing a config file, which can be set on any command with --config /path..
or as an environment variable and has a default path.
type Conf struct {
Foo string
Bar string
}
func() main {
cli := clif.New("my-app", "1.2.3", "My app that does something")
configOpt := clif.NewOption("config", "c", "Path to config file", "/default/config/path.json", true, false).
SetEnv("MY_APP_CONFIG").
SetParse(function(name, value string) (string, error) {
conf := new(Conf)
if raw, err := ioutil.ReadFile(value); err != nil {
return "", fmt.Errorf("Could not read config file %s: %s", value, err)
} else if err = json.Unmarshal(raw, conf); err != nil {
return "", fmt.Errorf("Could not unmarshal config file %s: %s", value, err)
} else if conf.Foo == "" {
return "", fmt.Errorf("Config %s is missing \"foo\"", value)
} else {
cli.Register(conf)
return value, nil
}
})
cli.AddDefaultOptions(configOpt)
cli.New("anything", "Does anything", func(conf *Conf) {
})
cli.Run()
}
Input & Output
Of course, you can just use fmt
and os.Stdin
, but for convenience (and fancy output) there are clif.Output
and clif.Input
.
Input
You can inject an instance of the clif.Input
interface into your command callback. It provides small set of often used tools.
Ask & AskRegex
Just ask the user a question then read & check the input. The question will be asked until the check/requirement is satisfied (or the user exits out with ctrl+c
):
func callbackFunctionI(in clif.Input) {
foo := in.Ask("What is a foo", nil)
name := in.Ask("Who are you? ", func(v string) error {
if len(v) > 0 {
return nil
} else {
return fmt.Errorf("Didn't catch that")
}
})
count := in.AskRegex("How many? ", regexp.MustCompile(`^[0-9]+$`))
}
See clif.RenderAskQuestion
for customization.
Confirm
Confirm()
ask the user a question until it is answered with yes
(or y
) or no
(or n
) and returns the response as bool
.
func callbackFunctionI(in clif.Input) {
if in.Confirm("Let's do it?") {
}
}
See clif.ConfirmRejection
, clif.ConfirmYesRegex
and clif.ConfirmNoRegex
for customization.
Choose
Choose()
is like a select in HTML and provides a list of options with descriptions to the user. The user then must choose (type in) one of the options. The choices will be presented to the user until a valid choice (one of the options) is provided.
func callbackFunctionI(in clif.Input) {
father := in.Choose("Who is your father?", map[string]string{
"yoda": "The small, green guy",
"darth": "The one with the smoker voice and the dark cape!",
"obi": "The old man with the light thingy",
})
if father == "darth" {
}
}
See clif.RenderChooseQuestion
, clif.RenderChooseOption
and clif.RenderChooseQuery
for customization.
Output & formatting
The clif.Output
interface can be injected into any callback. It relies on a clif.Formatter
, which does the actual formatting (eg colorizing) of the text.
Output themes
Per default, the clif.DefaultInput
via clif.NewColorOutput()
is used. It uses clif.DefaultStyles
, which look like the screenshots you are seeing in this readme.
You can change the output like so:
cli := clif.New(..)
cli.SetOutput(clif.NewColorOutput().
SetFormatter(clif.NewDefaultFormatter(clif.SunburnStyles))
Styles
Styles are applied by parsing (replacing) tokens like <error>
, which would be substitude with \033[31;1m
(using the default styles) resulting in a red coloring. Another example is <reset>
, which is replaced with \033[0m
leading to reset all colorings & styles.
There three built-in color styles (of course, you can extend them or add your own):
DefaultStyles
- as you can see on this pageSunburnStyles
- more yellow'ishWinterStyles
- more blue'ish
Table
Table rendering is a neat tool for CLIs. CLIF supports tables out of the box using the Output
interface.
Features:
- Multi-line columns
- Column auto fit
- Formatting (color) within columns
- Automatic stretch to max size (unless specifcied otherwise)
Example:
var (
headers := []string{"Name", "Age", "Force"}
rows = [][]string{
{
"<important>Yoda<reset>",
"Very, very old",
"Like the uber guy",
},
{
"<important>Luke Skywalker<reset>",
"Not that old",
"A bit, but not that much",
},
{
"<important>Anakin Skywalker<reset>",
"Old dude",
"He is Lukes father! Was kind of stronger in 1-3, but still failed to" +
" kill Jar Jar Binks. Not even tried, though. What's with that?",
},
}
)
func callbackFunction(out clif.Output) {
table := out.Table(headers)
table.AddRows(rows)
fmt.Println(table.Render())
}
Would print the following:
There are currently to styles available: ClosedTableStyle
(above), ClosedTableStyleLight
, OpenTableStyle
(below) and OpenTableStyleLight
:
func callbackFunction(out clif.Output) {
table := out.Table(headers, clif.OpenTableStyle)
table.AddRows(rows)
fmt.Println(table.Render())
}
Would print the following:
Progress bar
Another often required tool is the progress bar. Hence CLIF provides one out of the box:
func cmdProgress(out clif.Output) error {
pbs := out.ProgressBars()
pb, _ := pbs.Init("default", 200)
pbs.Start()
var wg sync.WaitGroup
wg.Add(1)
go func(b clif.ProgressBar) {
defer wg.Done()
for i := 0; i < 200; i++ {
b.Increment()
<-time.After(time.Millisecond * 100)
}
}(pb)
wg.Wait()
<-pbs.Finish()
}
Would output this:
Multiple bars are also possible, thanks to Greg Osuri's library:
func cmdProgress(out clif.Output) error {
pbs := out.ProgressBars()
pbs.Start()
var wg sync.WaitGroup
for i := 0; i < 3; i++ {
wg.Add(1)
pb, _ := pbs.Init(fmt.Sprintf("bar-%d", i+1), 200)
go func(b clif.ProgressBar, ii int) {
defer wg.Done()
for i := 0; i < 200; i++ {
b.Increment()
<-time.After(time.Millisecond * time.Duration(100 * ii))
}
}(pb, i)
}
wg.Wait()
<-pbs.Finish()
}
Would output this:
You prefer those ASCII arrows? Just set pbs.SetStyle(clif.ProgressBarStyleAscii)
and:
Real-life example
To provide you a usful'ish example, I've written a small CLI application called repos.
See also
There are a lot of other approaches you should have a look at.