README
¶
cli.go
cli.go is 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.
This is where cli.go comes into play. cli.go makes command line programming fun, organized, and expressive!
Installation
Make sure you have the a working Go environment (go 1.1 is required). See the install instructions.
To install cli.go, simply run:
$ go get github.com/codegangsta/cli
Make sure your PATH includes to the $GOPATH/bin directory so your commands can be easily used:
export PATH=$PATH:$GOPATH/bin
Getting Started
One of the philosophies behind cli.go is that an API should be playful and full of discovery. So a cli.go app can be as little as one line of code in main().
package main
import "os"
import "github.com/codegangsta/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 "os"
import "github.com/codegangsta/cli"
func main() {
app := cli.NewApp()
app.Name = "boom"
app.Usage = "make an explosive entrance"
app.Action = func(c *cli.Context) {
println("boom! I say!")
}
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.
Example
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!
/* greet.go */
package main
import "os"
import "github.com/codegangsta/cli"
func main() {
app := cli.NewApp()
app.Name = "greet"
app.Usage = "fight the loneliness!"
app.Action = func(c *cli.Context) {
println("Hello friend!")
}
app.Run(os.Args)
}
Install our command to the $GOPATH/bin directory:
$ go install
Finally run our new command:
$ greet
Hello friend!
cli.go also generates some bitchass 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.
...
app.Action = func(c *cli.Context) {
println("Hello", c.Args()[0])
}
...
Flags
Setting and querying flags is simple.
...
app.Flags = []cli.Flag {
cli.StringFlag{"lang", "english", "language for the greeting"},
}
app.Action = func(c *cli.Context) {
name := "someone"
if len(c.Args()) > 0 {
name = c.Args()[0]
}
if c.String("lang") == "spanish" {
println("Hola", name)
} else {
println("Hello", name)
}
}
...
Subcommands
Subcommands can be defined for a more git-like command line app.
...
app.Commands = []cli.Command{
{
Name: "add",
ShortName: "a",
Usage: "add a task to the list",
Action: func(c *cli.Context) {
println("added task: ", c.Args()[0])
},
},
{
Name: "complete",
ShortName: "c",
Usage: "complete a task on the list",
Action: func(c *cli.Context) {
println("completed task: ", c.Args()[0])
},
},
}
...
About
cli.go is written by none other than the Code Gangsta
Documentation
¶
Overview ¶
Package cli provides a minimal framework for creating and organizing command line Go applications. cli is designed to be easy to understand and write, the most simple cli application can be written as follows:
func main() {
cli.NewApp().Run(os.Args)
}
Of course this application does not do much, so let's make this an actual application:
func main() {
app := cli.NewApp()
app.Name = "greet"
app.Usage = "say a greeting"
app.Action = func(c *cli.Context) {
println("Greetings")
}
app.Run(os.Args)
}
Example ¶
package main
import (
"github.com/codegangsta/cli"
"os"
)
func main() {
app := cli.NewApp()
app.Name = "todo"
app.Usage = "task list on the command line"
app.Commands = []cli.Command{
{
Name: "add",
ShortName: "a",
Usage: "add a task to the list",
Action: func(c *cli.Context) {
println("added task: ", c.Args()[0])
},
},
{
Name: "complete",
ShortName: "c",
Usage: "complete a task on the list",
Action: func(c *cli.Context) {
println("completed task: ", c.Args()[0])
},
},
}
app.Run(os.Args)
}
Output:
Index ¶
- Variables
- func ShowAppHelp(c *Context)
- func ShowCommandHelp(c *Context, command string)
- func ShowVersion(c *Context)
- type App
- type BoolFlag
- type Command
- type Context
- func (c *Context) Args() []string
- func (c *Context) Bool(name string) bool
- func (c *Context) GlobalBool(name string) bool
- func (c *Context) GlobalInt(name string) int
- func (c *Context) GlobalString(name string) string
- func (c *Context) Int(name string) int
- func (c *Context) String(name string) string
- type Flag
- type IntFlag
- type StringFlag
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var AppHelpTemplate = `` /* 296-byte string literal not displayed */
The text template for the Default help topic. cli.go uses text/template to render templates. You can render custom help text by setting this variable.
var CommandHelpTemplate = `` /* 174-byte string literal not displayed */
The text template for the command help topic. cli.go uses text/template to render templates. You can render custom help text by setting this variable.
Functions ¶
func ShowCommandHelp ¶
Prints help for the given command
Types ¶
type App ¶
type App struct {
// The name of the program. Defaults to os.Args[0]
Name string
// Description of the program.
Usage string
// Version of the program
Version string
// List of commands to execute
Commands []Command
// List of flags to parse
Flags []Flag
// The action to execute when no subcommands are specified
Action func(context *Context)
}
Example ¶
package main
import (
"fmt"
"github.com/codegangsta/cli"
"os"
)
func main() {
// set args for examples sake
os.Args = []string{"greet", "--name", "Jeremy"}
app := cli.NewApp()
app.Name = "greet"
app.Flags = []cli.Flag{
cli.StringFlag{"name", "bob", "a name to say"},
}
app.Action = func(c *cli.Context) {
fmt.Printf("Hello %v\n", c.String("name"))
}
app.Run(os.Args)
}
Output: Hello Jeremy
type Command ¶
type Context ¶
type Context struct {
App *App
// contains filtered or unexported fields
}
Context is a type that is passed through to each Handler action in a cli application. Context can be used to retrieve context-specific Args and parsed command-line options.
func (*Context) Bool ¶
Looks up the value of a local bool flag, returns false if no bool flag exists
func (*Context) GlobalBool ¶
Looks up the value of a global bool flag, returns false if no bool flag exists
func (*Context) GlobalInt ¶
Looks up the value of a global int flag, returns 0 if no int flag exists
func (*Context) GlobalString ¶
Looks up the value of a global string flag, returns "" if no string flag exists
type StringFlag ¶
func (StringFlag) Apply ¶
func (f StringFlag) Apply(set *flag.FlagSet)
func (StringFlag) String ¶
func (f StringFlag) String() string
Source Files