`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
```
@ -86,13 +93,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"
)
@ -101,7 +114,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!"
@ -129,13 +143,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!"
@ -198,23 +216,53 @@ 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.:
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
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)
}
```
@ -288,13 +378,30 @@ 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
package main
import (
"os"
"github.com/urfave/cli"
)
func main() {
app := cli.NewApp()
app.Flags = []cli.Flag {
&cli.StringFlag{
Name: "lang",
@ -303,15 +410,35 @@ app.Flags = []cli.Flag {
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
package main
import (
"os"
"github.com/urfave/cli"
)
func main() {
app := cli.NewApp()
app.Flags = []cli.Flag {
&cli.StringFlag{
Name: "lang",
@ -321,11 +448,30 @@ app.Flags = []cli.Flag {
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"