`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.
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
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.
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!
**This is where cli comes into play.** cli makes command line programming fun,
organized, and expressive!
## Installation
@ -33,7 +39,8 @@ To install cli, simply run:
$ go get github.com/urfave/cli
```
Make sure your `PATH` includes to the `$GOPATH/bin` directory so your commands can be easily used:
Make sure your `PATH` includes to the `$GOPATH/bin` directory so your commands
can be easily used:
```
export PATH=$PATH:$GOPATH/bin
```
@ -89,13 +96,19 @@ import (
## 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()`.
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()`.
<!-- {
"args": ["--help"],
"output": "A new cli application"
} -->
``` go
package main
import (
"os"
"github.com/urfave/cli"
)
@ -104,7 +117,8 @@ func main() {
}
```
This app will run and show help text, but is not very useful. Let's give an action to execute and some help documentation:
This app will run and show help text, but is not very useful. Let's give an
action to execute and some help documentation:
<!-- {
"output": "boom! I say!"
@ -132,13 +146,17 @@ func main() {
}
```
Running this already gives you a ton of functionality, plus support for things like subcommands and flags, which are covered below.
Running this already gives you a ton of functionality, plus support for things
like subcommands and flags, which are covered below.
## Example
## 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!
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:
Start by creating a directory named `greet`, and within it, add a file,
`greet.go` with the following code in it:
<!-- {
"output": "Hello friend!"
@ -201,87 +219,159 @@ GLOBAL OPTIONS
### Arguments
You can lookup arguments by calling the `Args` function on `cli.Context`.
You can lookup arguments by calling the `Args` function on `cli.Context`, e.g.:
<!-- {
"output": "Hello \""
} -->
``` go
...
app.Action = func(c *cli.Context) error {
fmt.Println("Hello", c.Args()[0])
return nil
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)
}
...
```
### Flags
Setting and querying flags is simple.
<!-- {
"output": "Hello Nefertiti"
} -->
``` go
...
app.Flags = []cli.Flag {
&cli.StringFlag{
Name: "lang",
Value: "english",
Usage: "language for the greeting",
},
}
app.Action = func(c *cli.Context) error {
name := "someone"
if c.NArg() > 0 {
name = c.Args()[0]
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",
},
}
if c.String("lang") == "spanish" {
fmt.Println("Hola", name)
} else {
fmt.Println("Hello", name)
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
}
return nil
app.Run(os.Args)
}
...
```
You can also set a destination variable for a flag, to which the content will be scanned.
You can also set a destination variable for a flag, to which the content will be
scanned.
<!-- {
"output": "Hello someone"
} -->
``` go
...
var language string
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]
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,
},
}
if language == "spanish" {
fmt.Println("Hola", name)
} else {
fmt.Println("Hello", name)
app.Action = func(c *cli.Context) error {
name := "someone"
if c.NArg() > 0 {
name = c.Args().Get(0)
}
if language == "spanish" {
fmt.Println("Hola", name)
} else {
fmt.Println("Hello", name)
}
return nil
}
return nil
app.Run(os.Args)
}
...
```
See full list of flags at http://godoc.org/github.com/urfave/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.
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:
<!-- {
"args": ["--help"],
"output": "--config FILE, -c FILE"
} -->
```go
&cli.StringFlag{
Name: "config",
Aliases: []string{"c"},
Usage: "Load configuration from `FILE`",
package main
import (
"os"
"github.com/urfave/cli"
)
func main() {
app := cli.NewApp()
app.Flags = []cli.Flag{
&cli.StringFlag{
Name: "config",
Aliases: []string{"c"},
Usage: "Load configuration from `FILE`",
},
}
app.Run(os.Args)
}
```
@ -291,148 +381,247 @@ 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.
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.
You can set alternate (or short) names for flags by providing a comma-delimited
list for the `Name`. e.g.
<!-- {
"args": ["--help"],
"output": "--lang value, -l value.*language for the greeting.*default: \"english\""
} -->
``` go
app.Flags = []cli.Flag {
&cli.StringFlag{
Name: "lang",
Aliases: []string{"l"},
Value: "english",
Usage: "language for the greeting",
},
package main
import (
"os"
"github.com/urfave/cli"
)
func main() {
app := cli.NewApp()
app.Flags = []cli.Flag {
&cli.StringFlag{
Name: "lang",
Aliases: []string{"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.
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.
#### Values from the Environment
You can also have the default value set from the environment via `EnvVars`. e.g.
<!-- {
"args": ["--help"],
"output": "language for the greeting.*APP_LANG"
} -->
``` go
app.Flags = []cli.Flag {
&cli.StringFlag{
Name: "lang",
Aliases: []string{"l"},
Value: "english",
Usage: "language for the greeting",
EnvVars: []string{"APP_LANG"},
},
package main
import (
"os"
"github.com/urfave/cli"
)
func main() {
app := cli.NewApp()
app.Flags = []cli.Flag {
&cli.StringFlag{
Name: "lang",
Aliases: []string{"l"},
Value: "english",
Usage: "language for the greeting",
EnvVars: []string{"APP_LANG"},
},
}
app.Run(os.Args)
}
```
If `EnvVars` contains more than one string, the first environment variable that resolves is used as the default.
If `EnvVars` contains more than one string, the first environment variable that
resolves is used as the default.
<!-- {
"args": ["--help"],
"output": "language for the greeting.*LEGACY_COMPAT_LANG.*APP_LANG.*LANG"
