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 ( "os" "github.com/codegangsta/cli" ) 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().First()) }, }, { Name: "complete", ShortName: "c", Usage: "complete a task on the list", Action: func(c *cli.Context) { println("completed task: ", c.Args().First()) }, }, } app.Run(os.Args) }
Output:
Index ¶
- Variables
- func DefaultAppComplete(c *Context)
- func ShowAppHelp(c *Context)
- func ShowCommandCompletions(ctx *Context, command string)
- func ShowCommandHelp(c *Context, command string)
- func ShowCompletions(c *Context)
- func ShowSubcommandHelp(c *Context)
- func ShowVersion(c *Context)
- type App
- type Args
- type BoolFlag
- type BoolTFlag
- type Command
- type Context
- func (c *Context) Args() Args
- func (c *Context) Bool(name string) bool
- func (c *Context) BoolT(name string) bool
- func (c *Context) Float64(name string) float64
- func (c *Context) Generic(name string) interface{}
- func (c *Context) GlobalBool(name string) bool
- func (c *Context) GlobalGeneric(name string) interface{}
- 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) IsSet(name string) bool
- func (c *Context) String(name string) string
- func (c *Context) StringSlice(name string) []string
- type Flag
- type Float64Flag
- type Generic
- type GenericFlag
- type IntFlag
- type IntSlice
- type IntSliceFlag
- type StringFlag
- type StringSlice
- type StringSliceFlag
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var AppHelpTemplate = `` /* 368-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 BashCompletionFlag = BoolFlag{
Name: "generate-bash-completion",
}
This flag enables bash-completion for all commands and subcommands
var CommandHelpTemplate = `` /* 222-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.
var HelpFlag = BoolFlag{
Name: "help, h",
Usage: "show help",
}
This flag prints the help for all commands and subcommands
var HelpPrinter = printHelp
Prints help for the App
var SubcommandHelpTemplate = `` /* 294-byte string literal not displayed */
The text template for the subcommand help topic. cli.go uses text/template to render templates. You can render custom help text by setting this variable.
var VersionFlag = BoolFlag{
Name: "version, v",
Usage: "print the version",
}
This flag prints the version for the application
Functions ¶
func DefaultAppComplete ¶ added in v1.1.0
func DefaultAppComplete(c *Context)
Prints the list of subcommands as the default app completion method
func ShowAppHelp ¶ added in v1.0.0
func ShowAppHelp(c *Context)
func ShowCommandCompletions ¶ added in v1.1.0
Prints the custom completions for a given command
func ShowCommandHelp ¶ added in v1.0.0
Prints help for the given command
func ShowCompletions ¶ added in v1.1.0
func ShowCompletions(c *Context)
Prints the lists of commands within a given context
func ShowSubcommandHelp ¶ added in v1.1.0
func ShowSubcommandHelp(c *Context)
Prints help for the given subcommand
func ShowVersion ¶ added in v1.0.0
func ShowVersion(c *Context)
Prints the version number of the App
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 // Boolean to enable bash completion commands EnableBashCompletion bool // Boolean to hide built-in help command HideHelp bool // An action to execute when the bash-completion flag is set BashComplete func(context *Context) // An action to execute before any subcommands are run, but after the context is ready // If a non-nil error is returned, no subcommands are run Before func(context *Context) error // The action to execute when no subcommands are specified Action func(context *Context) // Execute this function if the proper command cannot be found CommandNotFound func(context *Context, command string) // Compilation date Compiled time.Time // Author Author string // Author e-mail Email string }
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" "os" "github.com/codegangsta/cli" ) 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: "name", Value: "bob", Usage: "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.
func (*App) Command ¶ added in v1.0.0
Returns the named command on App. Returns nil if the command does not exist
func (*App) Run ¶
Entry point to the cli app. Parses the arguments slice and routes to the proper flag/args combination
func (*App) RunAndExitOnError ¶ added in v1.1.0
func (a *App) RunAndExitOnError()
Another entry point to the cli app, takes care of passing arguments and error handling
func (*App) RunAsSubcommand ¶ added in v1.1.0
Invokes the subcommand given the context, parses ctx.Args() to generate command-specific flags
type Args ¶ added in v1.1.0
type Args []string
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 explanation of how the command works Description string // The function to call when checking for bash command completions BashComplete func(context *Context) // An action to execute before any sub-subcommands are run, but after the context is ready // If a non-nil error is returned, no sub-subcommands are run Before func(context *Context) error // The function to call when this command is invoked Action func(context *Context) // List of child commands Subcommands []Command // List of flags to parse Flags []Flag // Treat all flags as normal arguments if true SkipFlagParsing bool // Boolean to hide built-in help command HideHelp bool }
Command is a subcommand for a cli.App.
type Context ¶
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) BoolT ¶ added in v1.1.0
Looks up the value of a local boolT flag, returns false if no bool flag exists
func (*Context) Float64 ¶ added in v1.1.0
Looks up the value of a local float64 flag, returns 0 if no float64 flag exists
func (*Context) Generic ¶ added in v1.1.0
Looks up the value of a local generic flag, returns nil if no generic flag exists
func (*Context) GlobalBool ¶
Looks up the value of a global bool flag, returns false if no bool flag exists
func (*Context) GlobalGeneric ¶ added in v1.1.0
Looks up the value of a global generic flag, returns nil if no generic flag exists
func (*Context) GlobalInt ¶
Looks up the value of a global int flag, returns 0 if no int flag exists
func (*Context) GlobalIntSlice ¶ added in v1.0.0
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 ¶ added in v1.0.0
Looks up the value of a global string slice flag, returns nil if no string slice flag exists
func (*Context) IntSlice ¶ added in v1.0.0
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 ¶ added in v1.0.0
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) // contains filtered or unexported methods }
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 Float64Flag ¶ added in v1.1.0
func (Float64Flag) Apply ¶ added in v1.1.0
func (f Float64Flag) Apply(set *flag.FlagSet)
func (Float64Flag) String ¶ added in v1.1.0
func (f Float64Flag) String() string
type GenericFlag ¶ added in v1.1.0
GenericFlag is the flag type for types implementing Generic
func (GenericFlag) Apply ¶ added in v1.1.0
func (f GenericFlag) Apply(set *flag.FlagSet)
func (GenericFlag) String ¶ added in v1.1.0
func (f GenericFlag) String() string
type IntSliceFlag ¶ added in v1.0.0
func (IntSliceFlag) Apply ¶ added in v1.0.0
func (f IntSliceFlag) Apply(set *flag.FlagSet)
func (IntSliceFlag) String ¶ added in v1.0.0
func (f IntSliceFlag) String() string
type StringFlag ¶
func (StringFlag) Apply ¶
func (f StringFlag) Apply(set *flag.FlagSet)
func (StringFlag) String ¶
func (f StringFlag) String() string
type StringSlice ¶ added in v1.0.0
type StringSlice []string
func (*StringSlice) Set ¶ added in v1.0.0
func (f *StringSlice) Set(value string) error
func (*StringSlice) String ¶ added in v1.0.0
func (f *StringSlice) String() string
func (*StringSlice) Value ¶ added in v1.0.0
func (f *StringSlice) Value() []string
type StringSliceFlag ¶ added in v1.0.0
type StringSliceFlag struct { Name string Value *StringSlice Usage string EnvVar string }
func (StringSliceFlag) Apply ¶ added in v1.0.0
func (f StringSliceFlag) Apply(set *flag.FlagSet)
func (StringSliceFlag) String ¶ added in v1.0.0
func (f StringSliceFlag) String() string