package cli

import "github.com/urfave/cli"

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)
}

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)
}

Index ¶

• Variables
• func ShowAppHelp(c *Context)
• func ShowCommandHelp(c *Context, command string)
• func ShowVersion(c *Context)
• type App
• func NewApp() *App
• func (a *App) Command(name string) *Command
• func (a *App) Run(arguments []string) error
• type BoolFlag
• func (f BoolFlag) Apply(set *flag.FlagSet)
• func (f BoolFlag) String() string
• type Command
• func (c Command) HasName(name string) bool
• func (c Command) Run(ctx *Context) error
• type Context
• func NewContext(app *App, set *flag.FlagSet, globalSet *flag.FlagSet) *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
• func (f IntFlag) Apply(set *flag.FlagSet)
• func (f IntFlag) String() string
• type IntSlice
• func (f *IntSlice) Set(value string) error
• func (f *IntSlice) String() string
• func (f *IntSlice) Value() []int
• type IntSliceFlag
• func (f IntSliceFlag) Apply(set *flag.FlagSet)
• func (f IntSliceFlag) String() string
• type StringFlag
• func (f StringFlag) Apply(set *flag.FlagSet)
• func (f StringFlag) String() string
• type StringSlice
• func (f *StringSlice) Set(value string) error
• func (f *StringSlice) String() string
• func (f *StringSlice) Value() []string
• type StringSliceFlag
• func (f StringSliceFlag) Apply(set *flag.FlagSet)
• func (f StringSliceFlag) String() string

Examples ¶

• package
• App

Variables ¶

var AppHelpTemplate = "" /* 298 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 = "" /* 176 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 ShowAppHelp ¶

func ShowAppHelp(c *Context)

Prints help for the App

func ShowCommandHelp ¶

func ShowCommandHelp(c *Context, command string)

Prints help for the given command

func ShowVersion ¶

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
	// 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

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)
}

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 ¶

func (a *App) Command(name string) *Command

Returns the named command on App. Returns nil if the command does not exist

func (*App) Run ¶

func (a *App) Run(arguments []string) error

Entry point to the cli app. Parses the arguments slice and routes to the proper flag/args combination

type BoolFlag ¶

type BoolFlag struct {
	Name  string
	Usage string
}

func (BoolFlag) Apply ¶

func (f BoolFlag) Apply(set *flag.FlagSet)

func (BoolFlag) String ¶

func (f BoolFlag) String() 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 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.

func (Command) HasName ¶

func (c Command) HasName(name string) bool

Returns true if Command.Name or Command.ShortName matches given name

func (Command) Run ¶

func (c Command) Run(ctx *Context) error

Invokes the command given the context, parses ctx.Args() to generate command-specific flags

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 ¶

func NewContext(app *App, set *flag.FlagSet, globalSet *flag.FlagSet) *Context

Creates a new context. For use in when invoking an App or Command action.

func (*Context) Args ¶

func (c *Context) Args() []string

Returns the command line arguments associated with the context.

func (*Context) Bool ¶

func (c *Context) Bool(name string) bool

Looks up the value of a local bool flag, returns false if no bool flag exists

func (*Context) GlobalBool ¶

func (c *Context) GlobalBool(name string) bool

Looks up the value of a global bool flag, returns false if no bool flag exists

func (*Context) GlobalInt ¶

func (c *Context) GlobalInt(name string) int

Looks up the value of a global int flag, returns 0 if no int flag exists

func (*Context) GlobalIntSlice ¶

func (c *Context) GlobalIntSlice(name string) []int

Looks up the value of a global int slice flag, returns nil if no int slice flag exists

func (*Context) GlobalString ¶

func (c *Context) GlobalString(name string) string

Looks up the value of a global string flag, returns "" if no string flag exists

func (*Context) GlobalStringSlice ¶

func (c *Context) GlobalStringSlice(name string) []string

Looks up the value of a global string slice flag, returns nil if no string slice flag exists

func (*Context) Int ¶

func (c *Context) Int(name string) int

Looks up the value of a local int flag, returns 0 if no int flag exists

func (*Context) IntSlice ¶

func (c *Context) IntSlice(name string) []int

Looks up the value of a local int slice flag, returns nil if no int slice flag exists

func (*Context) String ¶

func (c *Context) String(name string) string

Looks up the value of a local string flag, returns "" if no string flag exists

func (*Context) StringSlice ¶

func (c *Context) StringSlice(name string) []string

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)
}

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 IntFlag ¶

type IntFlag struct {
	Name  string
	Value int
	Usage string
}

func (IntFlag) Apply ¶

func (f IntFlag) Apply(set *flag.FlagSet)

func (IntFlag) String ¶

func (f IntFlag) String() string

type IntSlice ¶

type IntSlice []int

func (*IntSlice) Set ¶

func (f *IntSlice) Set(value string) error

func (*IntSlice) String ¶

func (f *IntSlice) String() string

func (*IntSlice) Value ¶

func (f *IntSlice) Value() []int

type IntSliceFlag ¶

type IntSliceFlag struct {
	Name  string
	Value *IntSlice
	Usage string
}

func (IntSliceFlag) Apply ¶

func (f IntSliceFlag) Apply(set *flag.FlagSet)

func (IntSliceFlag) String ¶

func (f IntSliceFlag) String() string

type StringFlag ¶

type StringFlag struct {
	Name  string
	Value string
	Usage string
}

func (StringFlag) Apply ¶

func (f StringFlag) Apply(set *flag.FlagSet)

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) String ¶

func (f StringSliceFlag) String() string

Source Files ¶

app.go cli.go command.go context.go flag.go help.go