README
¶
Go CLI Library 
cli is a library for implementing powerful command-line interfaces in Go. cli is the library that powers the CLI for Packer, Serf, and Consul.
Features
-
Easy sub-command based CLIs:
cli foo,cli bar, etc. -
Optional support for default subcommands so
clidoes something other than error. -
Automatic help generation for listing subcommands
-
Automatic help flag recognition of
-h,--help, etc. -
Automatic version flag recognition of
-v,--version. -
Helpers for interacting with the terminal, such as outputting information, asking for input, etc. These are optional, you can always interact with the terminal however you choose.
-
Use of Go interfaces/types makes augmenting various parts of the library a piece of cake.
Example
Below is a simple example of creating and running a CLI
package main
import (
"log"
"os"
"github.com/mitchellh/cli"
)
func main() {
c := cli.NewCLI("app", "1.0.0")
c.Args = os.Args[1:]
c.Commands = map[string]cli.CommandFactory{
"foo": fooCommandFactory,
"bar": barCommandFactory,
}
exitStatus, err := c.Run()
if err != nil {
log.Println(err)
}
os.Exit(exitStatus)
}
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( UiColorNone UiColor = UiColor{-1, false} UiColorRed = UiColor{31, false} UiColorGreen = UiColor{32, false} UiColorYellow = UiColor{33, false} UiColorBlue = UiColor{34, false} UiColorMagenta = UiColor{35, false} UiColorCyan = UiColor{36, false} )
A list of colors that are useful. These are all non-bolded by default.
Functions ¶
This section is empty.
Types ¶
type BasicUi ¶
BasicUi is an implementation of Ui that just outputs to the given writer. This UI is not threadsafe by default, but you can wrap it in a ConcurrentUi to make it safe.
type CLI ¶
type CLI struct {
// Args is the list of command-line arguments received excluding
// the name of the app. For example, if the command "./cli foo bar"
// was invoked, then Args should be []string{"foo", "bar"}.
Args []string
// Commands is a mapping of subcommand names to a factory function
// for creating that Command implementation. If there is a command
// with a blank string "", then it will be used as the default command
// if no subcommand is specified.
Commands map[string]CommandFactory
// Name defines the name of the CLI.
Name string
// Version of the CLI.
Version string
// HelpFunc and HelpWriter are used to output help information, if
// requested.
//
// HelpFunc is the function called to generate the generic help
// text that is shown if help must be shown for the CLI that doesn't
// pertain to a specific command.
//
// HelpWriter is the Writer where the help text is outputted to. If
// not specified, it will default to Stderr.
HelpFunc HelpFunc
HelpWriter io.Writer
// contains filtered or unexported fields
}
CLI contains the state necessary to run subcommands and parse the command line arguments.
func (*CLI) IsVersion ¶
IsVersion returns whether or not the version flag is present within the arguments.
func (*CLI) Subcommand ¶
Subcommand returns the subcommand that the CLI would execute. For example, a CLI from "--version version --help" would return a Subcommand of "version"
func (*CLI) SubcommandArgs ¶
SubcommandArgs returns the arguments that will be passed to the subcommand.
type ColoredUi ¶
type ColoredUi struct {
OutputColor UiColor
InfoColor UiColor
ErrorColor UiColor
WarnColor UiColor
Ui Ui
}
ColoredUi is a Ui implementation that colors its output according to the given color schemes for the given type of output.
type Command ¶
type Command interface {
// Help should return long-form help text that includes the command-line
// usage, a brief few sentences explaining the function of the command,
// and the complete list of flags the command accepts.
Help() string
// Run should run the actual command with the given CLI instance and
// command-line arguments. It should return the exit status when it is
// finished.
Run(args []string) int
// Synopsis should return a one-line, short synopsis of the command.
// This should be less than 50 characters ideally.
Synopsis() string
}
A command is a runnable sub-command of a CLI.
type CommandFactory ¶
CommandFactory is a type of function that is a factory for commands. We need a factory because we may need to setup some state on the struct that implements the command itself.
type ConcurrentUi ¶
type ConcurrentUi struct {
Ui Ui
// contains filtered or unexported fields
}
ConcurrentUi is a wrapper around a Ui interface (and implements that interface) making the underlying Ui concurrency safe.
func (*ConcurrentUi) AskSecret ¶ added in v0.1.2
func (u *ConcurrentUi) AskSecret(query string) (string, error)
func (*ConcurrentUi) Error ¶
func (u *ConcurrentUi) Error(message string)
func (*ConcurrentUi) Info ¶
func (u *ConcurrentUi) Info(message string)
func (*ConcurrentUi) Output ¶
func (u *ConcurrentUi) Output(message string)
func (*ConcurrentUi) Warn ¶
func (u *ConcurrentUi) Warn(message string)
type HelpFunc ¶
type HelpFunc func(map[string]CommandFactory) string
HelpFunc is the type of the function that is responsible for generating the help output when the CLI must show the general help text.
func BasicHelpFunc ¶
BasicHelpFunc generates some basic help output that is usually good enough for most CLI applications.
func FilteredHelpFunc ¶
FilteredHelpFunc will filter the commands to only include the keys in the include parameter.
type MockCommand ¶
type MockCommand struct {
// Settable
HelpText string
RunResult int
SynopsisText string
// Set by the command
RunCalled bool
RunArgs []string
}
MockCommand is an implementation of Command that can be used for tests. It is publicly exported from this package in case you want to use it externally.
func (*MockCommand) Help ¶
func (c *MockCommand) Help() string
func (*MockCommand) Run ¶
func (c *MockCommand) Run(args []string) int
func (*MockCommand) Synopsis ¶
func (c *MockCommand) Synopsis() string
type MockUi ¶
type MockUi struct {
InputReader io.Reader
ErrorWriter *bytes.Buffer
OutputWriter *bytes.Buffer
// contains filtered or unexported fields
}
MockUi is a mock UI that is used for tests and is exported publicly for use in external tests if needed as well.
type PrefixedUi ¶
type PrefixedUi struct {
AskPrefix string
AskSecretPrefix string
OutputPrefix string
InfoPrefix string
ErrorPrefix string
WarnPrefix string
Ui Ui
}
PrefixedUi is an implementation of Ui that prefixes messages.
func (*PrefixedUi) AskSecret ¶ added in v0.1.2
func (u *PrefixedUi) AskSecret(query string) (string, error)
func (*PrefixedUi) Error ¶
func (u *PrefixedUi) Error(message string)
func (*PrefixedUi) Info ¶
func (u *PrefixedUi) Info(message string)
func (*PrefixedUi) Output ¶
func (u *PrefixedUi) Output(message string)
func (*PrefixedUi) Warn ¶
func (u *PrefixedUi) Warn(message string)
type Ui ¶
type Ui interface {
// Ask asks the user for input using the given query. The response is
// returned as the given string, or an error.
Ask(string) (string, error)
// AskSecret asks the user for input using the given query, but does not echo
// the keystrokes to the terminal.
AskSecret(string) (string, error)
// Output is called for normal standard output.
Output(string)
// Info is called for information related to the previous output.
// In general this may be the exact same as Output, but this gives
// Ui implementors some flexibility with output formats.
Info(string)
// Error is used for any error messages that might appear on standard
// error.
Error(string)
// Warn is used for any warning messages that might appear on standard
// error.
Warn(string)
}
Ui is an interface for interacting with the terminal, or "interface" of a CLI. This abstraction doesn't have to be used, but helps provide a simple, layerable way to manage user interactions.
Source Files