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.
You can view the API docs here: http://godoc.org/github.com/codegangsta/cli
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)
}
}
...
Alternate Names
You can set alternate (or short) names for flags by providing a comma-delimited list for the Name. e.g.
app.Flags = []cli.Flag {
cli.StringFlag{"lang, l", "english", "language for the greeting"},
}
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.
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) GlobalIntSlice(name string) []int
- func (c *Context) GlobalString(name string) string
- func (c *Context) GlobalStringSlice(name string) []string
- func (c *Context) Int(name string) int
- func (c *Context) IntSlice(name string) []int
- func (c *Context) String(name string) string
- func (c *Context) StringSlice(name string) []string
- type Flag
- type IntFlag
- type IntSlice
- type IntSliceFlag
- type StringFlag
- type StringSlice
- type StringSliceFlag
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)
}
App is the main structure of a cli application. It is recomended that and app be created with the cli.NewApp() function
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
func NewApp ¶
func NewApp() *App
Creates a new cli Application with some reasonable defaults for Name, Usage, Version and Action.
type Command ¶
type Command struct {
// The name of the command
Name string
// short name of the command. Typically one character
ShortName string
// A short description of the usage of this command
Usage string
// A longer explaination of how the command works
Description string
// The function to call when this command is invoked
Action func(context *Context)
// List of flags to parse
Flags []Flag
}
Command is a subcommand for a cli.App.
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 NewContext ¶
Creates a new context. For use in when invoking an App or Command action.
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) GlobalIntSlice ¶
Looks up the value of a global int slice flag, returns nil if no int slice flag exists
func (*Context) GlobalString ¶
Looks up the value of a global string flag, returns "" if no string flag exists
func (*Context) GlobalStringSlice ¶
Looks up the value of a global string slice flag, returns nil if no string slice flag exists
func (*Context) IntSlice ¶
Looks up the value of a local int slice flag, returns nil if no int slice flag exists
func (*Context) String ¶
Looks up the value of a local string flag, returns "" if no string flag exists
func (*Context) StringSlice ¶
Looks up the value of a local string slice flag, returns nil if no string slice flag exists
type Flag ¶
type Flag interface {
fmt.Stringer
// Apply Flag settings to the given flag set
Apply(*flag.FlagSet)
GetName() string
}
Flag is a common interface related to parsing flags in cli. For more advanced flag parsing techniques, it is recomended that this interface be implemented.
type IntSliceFlag ¶
func (IntSliceFlag) Apply ¶
func (f IntSliceFlag) Apply(set *flag.FlagSet)
func (IntSliceFlag) GetName ¶
func (f IntSliceFlag) GetName() string
func (IntSliceFlag) String ¶
func (f IntSliceFlag) String() string
type StringFlag ¶
func (StringFlag) Apply ¶
func (f StringFlag) Apply(set *flag.FlagSet)
func (StringFlag) GetName ¶
func (f StringFlag) GetName() string
func (StringFlag) String ¶
func (f StringFlag) String() string
type StringSlice ¶
type StringSlice []string
func (*StringSlice) Set ¶
func (f *StringSlice) Set(value string) error
func (*StringSlice) String ¶
func (f *StringSlice) String() string
func (*StringSlice) Value ¶
func (f *StringSlice) Value() []string
type StringSliceFlag ¶
type StringSliceFlag struct {
Name string
Value *StringSlice
Usage string
}
func (StringSliceFlag) Apply ¶
func (f StringSliceFlag) Apply(set *flag.FlagSet)
func (StringSliceFlag) GetName ¶
func (f StringSliceFlag) GetName() string
func (StringSliceFlag) String ¶
func (f StringSliceFlag) String() string
Source Files