cli

Documentation

Overview

Package cli is a library for writing CLI applications. It supports subcommands, flags, command completion, before and after hooks, exit code control and more.

Here is an example that creates prints "Hello, world!\n" when invoked:

func main() {
	app := cli.NewApp()
	app.Action = func(ctx cli.Context) error {
		ctx.Printf("Hello, world!\n")
		return nil
	}
	os.Exit(app.Run(os.Args))
}

Index

• Constants
• Variables
• type App
  • func NewApp(opts ...Option) *App
  • func (app *App) Run(args []string) (exitStatus int)
• type Backcompat
• type Command
  • func (cmd Command) Names() []string
• type Context
  • func (ctx *Context) Bool(name string) bool
  • func (ctx *Context) Context() context.Context
  • func (ctx *Context) Duration(name string) time.Duration
  • func (ctx *Context) DurationSlice(name string) []time.Duration
  • func (ctx *Context) Errorf(format string, a ...interface{})
  • func (ctx *Context) Errorln(a ...interface{})
  • func (ctx *Context) FlagValue(name string) FlagValue
  • func (ctx *Context) Has(name string) bool
  • func (ctx *Context) Int(name string) int
  • func (ctx *Context) IntSlice(name string) []int
  • func (ctx *Context) Print(a ...interface{})
  • func (ctx Context) PrintHelp(out io.Writer)
  • func (ctx *Context) Printf(format string, a ...interface{})
  • func (ctx *Context) Println(a ...interface{})
  • func (ctx *Context) Slice(name string) []string
  • func (ctx Context) Sorted(f func())
  • func (ctx *Context) String(name string) string
  • func (ctx *Context) StringSlice(name string) []string
• type ContextOption
• type ErrorStringer
• type ExitCoder
  • func WithExitCode(exitCode int, err error) ExitCoder
• type FlagValue
• type Manpage
• type ManpageRef
• type OnExit
• type OnExitID
• type Option
  • func DebugHandler(errorStringer ErrorStringer) Option

Constants

const CompletionFlag = "--generate-bash-completion"

const (
	DebugFlagName = "debug"
)

const DefaultDecision string = ""

Variables

var (
	ErrDisplayHelpText = errors.New("display help text")
)

Types

type App

type App struct {
	Command
	Before         func(ctx Context) error
	ErrorHandler   func(ctx Context, err error) int
	Version        string
	Stdout         io.Writer
	Stderr         io.Writer
	Completion     map[string]completion.Provider
	Manpage        *Manpage
	Backcompat     []Backcompat
	OnExit         OnExit
	ContextConfig  func(Context, context.Context) context.Context
	ContextOptions []ContextOption
}

func NewApp

func NewApp(opts ...Option) *App

func (*App) Run

func (app *App) Run(args []string) (exitStatus int)

type Backcompat

type Backcompat struct {
	Path    []string
	Command Command
}

type Command

type Command struct {
	Name         string
	Alias        string
	Usage        string
	Description  string // prose
	Flags        []flag.Flag
	Subcommands  []Command
	DecisionFlag string
	Action       func(ctx Context) error
}

func (Command) Names

func (cmd Command) Names() []string

type Context

type Context struct {
	App        *App
	Command    *Command
	Path       []string
	IsTerminal func() bool
	// contains filtered or unexported fields
}

func (*Context) Bool

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

func (*Context) Context

func (ctx *Context) Context() context.Context

func (*Context) Duration

func (ctx *Context) Duration(name string) time.Duration

func (*Context) DurationSlice

func (ctx *Context) DurationSlice(name string) []time.Duration

func (*Context) Errorf

func (ctx *Context) Errorf(format string, a ...interface{})

func (*Context) Errorln

func (ctx *Context) Errorln(a ...interface{})

func (*Context) FlagValue

func (ctx *Context) FlagValue(name string) FlagValue

func (*Context) Has

func (ctx *Context) Has(name string) bool

func (*Context) Int

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

func (*Context) IntSlice

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

func (*Context) Print

func (ctx *Context) Print(a ...interface{})

func (Context) PrintHelp

func (ctx Context) PrintHelp(out io.Writer)

func (*Context) Printf

func (ctx *Context) Printf(format string, a ...interface{})

func (*Context) Println

func (ctx *Context) Println(a ...interface{})

func (*Context) Slice

func (ctx *Context) Slice(name string) []string

Slice is specifically for flag.StringSlice (whereas the other "*Slice" functions are for retrieving all of the values specified for an individual flag).

func (Context) Sorted

func (ctx Context) Sorted(f func())

func (*Context) String

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

func (*Context) StringSlice

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

type ContextOption

type ContextOption func(*Context)

type ErrorStringer

type ErrorStringer func(err error) string

type ExitCoder

type ExitCoder interface {
	error
	ExitCode() int
}

func WithExitCode

func WithExitCode(exitCode int, err error) ExitCoder

type FlagValue

type FlagValue interface {
	HasChanged() bool
	Name() string
	ValueString() string
	ValueType() string
}

FlagValue matches the interface specified by the viper package.

type Manpage

type Manpage struct {
	Source     string // e.g. Linux
	Manual     string // e.g. Linux Programmer's Manual
	BugTracker string
	SeeAlso    []ManpageRef
}

type ManpageRef

type ManpageRef struct {
	Name    string
	Section uint8
}

type OnExit

type OnExit interface {
	// Registers a function to be executed on exit of the cli application. If multiple functions are registered
	// they are executed in LIFO order.
	Register(f func()) OnExitID
	Unregister(id OnExitID)
	// contains filtered or unexported methods
}

type OnExitID

type OnExitID struct {
	// contains filtered or unexported fields
}

type Option

type Option func(*App)

func DebugHandler

func DebugHandler(errorStringer ErrorStringer) Option

DebugHandler returns an Option function that configures a provided *App with debug handler functionality by adding a global "debug" boolean flag and a custom error handler. If the debug flag is true, the error handler prints the representation of the error returned by errorStringer to the context's Stderr writer; otherwise, the output of the error's "Error" function is printed. If the error implements ExitCoder, the handler returns the value returned by the error's "ExitCode" function; otherwise, it returns 1.