CLI is a fork of urfave/cli. We use it to simplify flag parsing.
cli is a simple, fast, and fun package for building command line apps in Go. The goal is to enable developers to write fast and distributable command line applications in an expressive way.
Usage documentation exists for each major version. Don't know what version you're on? You're probably using the version from the master branch, which is currently v2.
v2- ./docs/v2/manual.mdv1- ./docs/v1/manual.md
Make sure you have a working Go environment. Go version 1.2+ is supported. See the install instructions for Go.
To install cli, simply run:
$ go get github.com/micro/cli Make sure your PATH includes the $GOPATH/bin directory so your commands can be easily used:
export PATH=$PATH:$GOPATH/bin cli is tested against multiple versions of Go on Linux, and against the latest released version of Go on OS X and Windows. For full details, see ./.travis.yml and ./appveyor.yml.
Make sure you have a working Go environment. Go version 1.11+ is supported. See the install instructions for Go.
Go Modules are strongly recommended when using this package. See the go blog guide on using Go Modules.
$ GO111MODULE=on go get github.com/micro/cli/v2 ...import ( "github.com/micro/cli/v2"// imports as package "cli" ) ...This will pull the latest tagged v1 release (e.g. v1.18.1 at the time of writing).
One of the philosophies behind cli is that an API should be playful and full of discovery. So a cli app can be as little as one line of code in main().
package main import ( "os""github.com/micro/cli" ) funcmain(){cli.NewApp().Run(os.Args) }This app will run and show help text, but is not very useful. Let's give an action to execute and some help documentation:
package main import ( "fmt""os""github.com/micro/cli" ) funcmain(){app:=cli.NewApp() app.Name="boom"app.Usage="make an explosive entrance"app.Action=func(c*cli.Context) error{fmt.Println("boom! I say!") returnnil } app.Run(os.Args) }Running this already gives you a ton of functionality, plus support for things like subcommands and flags, which are covered below.
Being a programmer can be a lonely job. Thankfully by the power of automation that is not the case! Let's create a greeter app to fend off our demons of loneliness!
Start by creating a directory named greet, and within it, add a file, greet.go with the following code in it:
package main import ( "fmt""os""github.com/micro/cli" ) funcmain(){app:=cli.NewApp() app.Name="greet"app.Usage="fight the loneliness!"app.Action=func(c*cli.Context) error{fmt.Println("Hello friend!") returnnil } app.Run(os.Args) }Install our command to the $GOPATH/bin directory:
$ go install Finally run our new command:
$ greet Hello friend! cli also generates neat help text:
$ greet help NAME: greet - fight the loneliness! USAGE: greet [global options] command [command options] [arguments...] VERSION: 0.0.0 COMMANDS: help, h Shows a list of commands or help for one command GLOBAL OPTIONS --version Shows version information You can lookup arguments by calling the Args function on cli.Context, e.g.:
package main import ( "fmt""os""github.com/micro/cli" ) funcmain(){app:=cli.NewApp() app.Action=func(c*cli.Context) error{fmt.Printf("Hello %q", c.Args().Get(0)) returnnil } app.Run(os.Args) }Setting and querying flags is simple.
package main import ( "fmt""os""github.com/micro/cli" ) funcmain(){app:=cli.NewApp() app.Flags= []cli.Flag{cli.StringFlag{Name: "lang", Value: "english", Usage: "language for the greeting", }, } app.Action=func(c*cli.Context) error{name:="Nefertiti"ifc.NArg() >0{name=c.Args().Get(0) } ifc.String("lang") =="spanish"{fmt.Println("Hola", name) } else{fmt.Println("Hello", name) } returnnil } app.Run(os.Args) }You can also set a destination variable for a flag, to which the content will be scanned.
package main import ( "os""fmt""github.com/micro/cli" ) funcmain(){varlanguagestringapp:=cli.NewApp() app.Flags= []cli.Flag{cli.StringFlag{Name: "lang", Value: "english", Usage: "language for the greeting", Destination: &language, }, } app.Action=func(c*cli.Context) error{name:="someone"ifc.NArg() >0{name=c.Args()[0] } iflanguage=="spanish"{fmt.Println("Hola", name) } else{fmt.Println("Hello", name) } returnnil } app.Run(os.Args) }See full list of flags at http://godoc.org/github.com/micro/cli
Sometimes it's useful to specify a flag's value within the usage string itself. Such placeholders are indicated with back quotes.
For example this:
package main import ( "os""github.com/micro/cli" ) funcmain(){app:=cli.NewApp() app.Flags= []cli.Flag{cli.StringFlag{Name: "config, c", Usage: "Load configuration from `FILE`", }, } app.Run(os.Args) }Will result in help output like:
--config FILE, -c FILE Load configuration from FILE Note that only the first placeholder is used. Subsequent back-quoted words will be left as-is.
You can set alternate (or short) names for flags by providing a comma-delimited list for the Name. e.g.
package main import ( "os""github.com/micro/cli" ) funcmain(){app:=cli.NewApp() app.Flags= []cli.Flag{cli.StringFlag{Name: "lang, l", Value: "english", Usage: "language for the greeting", }, } app.Run(os.Args) }That flag can then be set with --lang spanish or -l spanish. Note that giving two different forms of the same flag in the same command invocation is an error.
Flags for the application and commands are shown in the order they are defined. However, it's possible to sort them from outside this library by using FlagsByName or CommandsByName with sort.
For example this:
package main import ( "os""sort""github.com/micro/cli" ) funcmain(){app:=cli.NewApp() app.Flags= []cli.Flag{cli.StringFlag{Name: "lang, l", Value: "english", Usage: "Language for the greeting", }, cli.StringFlag{Name: "config, c", Usage: "Load configuration from `FILE`", }, } app.Commands= []cli.Command{{Name: "complete", Aliases: []string{"c"}, Usage: "complete a task on the list", Action: func(c*cli.Context) error{returnnil }, },{Name: "add", Aliases: []string{"a"}, Usage: "add a task to the list", Action: func(c*cli.Context) error{returnnil }, }, } sort.Sort(cli.FlagsByName(app.Flags)) sort.Sort(cli.CommandsByName(app.Commands)) app.Run(os.Args) }Will result in help output like:
--config FILE, -c FILE Load configuration from FILE --lang value, -l value Language for the greeting (default: "english") You can also have the default value set from the environment via EnvVar. e.g.
package main import ( "os""github.com/micro/cli" ) funcmain(){app:=cli.NewApp() app.Flags= []cli.Flag{cli.StringFlag{Name: "lang, l", Value: "english", Usage: "language for the greeting", EnvVar: "APP_LANG", }, } app.Run(os.Args) }The EnvVar may also be given as a comma-delimited "cascade", where the first environment variable that resolves is used as the default.
package main import ( "os""github.com/micro/cli" ) funcmain(){app:=cli.NewApp() app.Flags= []cli.Flag{cli.StringFlag{Name: "lang, l", Value: "english", Usage: "language for the greeting", EnvVar: "LEGACY_COMPAT_LANG,APP_LANG,LANG", }, } app.Run(os.Args) }$ GO111MODULE=on go get github.com/micro/cli ...import ( "github.com/micro/cli" ) ...Make sure your PATH includes the $GOPATH/bin directory so your commands can be easily used:
export PATH=$PATH:$GOPATH/bin cli is tested against multiple versions of Go on Linux, and against the latest released version of Go on OS X and Windows. This project uses Github Actions for builds. For more build info, please look at the ./.github/workflows/cli.yml.