# README
CLI 
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
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
Installation
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
Supported platforms
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.
Using the v2 branch
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.
Using v2 releases
$ 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).
Getting Started
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"
)
func main() {
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"
)
func main() {
app := cli.NewApp()
app.Name = "boom"
app.Usage = "make an explosive entrance"
app.Action = func(c *cli.Context) error {
fmt.Println("boom! I say!")
return nil
}
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.
Examples
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"
)
func main() {
app := cli.NewApp()
app.Name = "greet"
app.Usage = "fight the loneliness!"
app.Action = func(c *cli.Context) error {
fmt.Println("Hello friend!")
return nil
}
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
Arguments
You can lookup arguments by calling the Args function on cli.Context, e.g.:
package main
import (
"fmt"
"os"
"github.com/micro/cli"
)
func main() {
app := cli.NewApp()
app.Action = func(c *cli.Context) error {
fmt.Printf("Hello %q", c.Args().Get(0))
return nil
}
app.Run(os.Args)
}
Flags
Setting and querying flags is simple.
package main
import (
"fmt"
"os"
"github.com/micro/cli"
)
func main() {
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"
if c.NArg() > 0 {
name = c.Args().Get(0)
}
if c.String("lang") == "spanish" {
fmt.Println("Hola", name)
} else {
fmt.Println("Hello", name)
}
return nil
}
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"
)
func main() {
var language string
app := 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"
if c.NArg() > 0 {
name = c.Args()[0]
}
if language == "spanish" {
fmt.Println("Hola", name)
} else {
fmt.Println("Hello", name)
}
return nil
}
app.Run(os.Args)
}
See full list of flags at http://godoc.org/github.com/micro/cli
Placeholder Values
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"
)
func main() {
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.
Alternate Names
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"
)
func main() {
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.
Ordering
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"
)
func main() {
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 {
return nil
},
},
{
Name: "add",
Aliases: []string{"a"},
Usage: "add a task to the list",
Action: func(c *cli.Context) error {
return nil
},
},
}
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")
Values from the Environment
You can also have the default value set from the environment via EnvVar. e.g.
package main
import (
"os"
"github.com/micro/cli"
)
func main() {
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"
)
func main() {
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)
}
Values from alternate input sources (YAML, TOML, and others)
Using v1 releases
$ GO111MODULE=on go get github.com/micro/cli
...
import (
"github.com/micro/cli"
)
...
GOPATH
Make sure your PATH includes the $GOPATH/bin directory so your commands can
be easily used:
export PATH=$PATH:$GOPATH/bin
Supported platforms
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.