/
Notice: This is the library formerly known as
github.com/codegangsta/cli -- Github will automatically redirect requests
to this repository, but we recommend updating your references for clarity.
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.
- Overview
- Installation
- Getting Started
- Examples
- Contribution Guidelines
Command line apps are usually so tiny that there is absolutely no reason why your code should not be self-documenting. Things like generating help text and parsing command flags/options should not hinder productivity when writing a command line app.
This is where cli comes into play. cli makes command line programming fun, organized, and expressive!
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/urfave/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.
Warning: The v2 branch is currently unreleased and considered unstable.
There is currently a long-lived branch named v2 that is intended to land as
the new master branch once development there has settled down. The current
master branch (mirrored as v1) is being manually merged into v2 on
an irregular human-based schedule, but generally if one wants to "upgrade" to
v2 now and accept the volatility (read: "awesomeness") that comes along with
that, please use whatever version pinning of your preference, such as via
gopkg.in:
$ go get gopkg.in/urfave/cli.v2
...
import (
"gopkg.in/urfave/cli.v2" // imports as package "cli"
)
...Similarly to the section above describing use of the v2 branch, if one wants
to avoid any unexpected compatibility pains once v2 becomes master, then
pinning to v1 is an acceptable option, e.g.:
$ go get gopkg.in/urfave/cli.v1
...
import (
"gopkg.in/urfave/cli.v1" // 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/urfave/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/urfave/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.
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/urfave/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
You can lookup arguments by calling the Args function on cli.Context, e.g.:
package main
import (
"fmt"
"os"
"github.com/urfave/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)
}Setting and querying flags is simple.
package main
import (
"fmt"
"os"
"github.com/urfave/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/urfave/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/urfave/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:
< F438 div class="highlight highlight-source-go notranslate position-relative overflow-auto" dir="auto" data-snippet-clipboard-copy-content="package main import ( "os" "github.com/urfave/cli" ) func main() { app := cli.NewApp() app.Flags = []cli.Flag{ cli.StringFlag{ Name: "config, c", Usage: "Load configuration from `FILE`", }, } app.Run(os.Args) }">package main import ( "os" "github.com/urfave/cli" ) func main() { app := cli.NewApp() app.Flags = []cli.Flag{ cli.StringFlag{ Name: "config, c", Usage: "Load configuration from `FILE`", }, } app.Run(os.Args) }