cli

func AnyArgs ¶

func AnyArgs() ArgValidator

AnyArgs is a positional argument validator that allows any arbitrary args, it never returns an error.

This is the default argument validator on a Command instantiated with cli.New.

func BetweenArgs ¶

func BetweenArgs(min, max int) ArgValidator

BetweenArgs is a positional argument validator that allows between min and max arguments (inclusive), any outside that range will return an error.

func Combine ¶

func Combine(validators ...ArgValidator) ArgValidator

Combine allows multiple positional argument validators to be composed together.

The first validator to fail will be the one that returns the error.

func ExactArgs ¶

func ExactArgs(n int) ArgValidator

ExactArgs is a positional argument validator that allows exactly n args, any more or less will return an error.

func MaxArgs ¶

func MaxArgs(n int) ArgValidator

MaxArgs is a positional argument validator that returns an error if there are more than n arguments.

func MinArgs ¶

func MinArgs(n int) ArgValidator

MinArgs is a positional argument validator that requires at least n arguments.

func NoArgs ¶

func NoArgs() ArgValidator

NoArgs is a positional argument validator that does not allow any arguments, it returns an error if there are any arguments.

func ValidArgs ¶

func ValidArgs(valid []string) ArgValidator

ValidArgs is a positional argument validator that only allows arguments that are contained in the valid slice. If any non-valid arguments are seen, an error will be returned.

func New ¶

func New(name string, options ...Option) (*Command, error)

New builds and returns a new Command.

The command can be customised by passing in a number of options enabling you to do things like configure stderr and stdout, add or customise help or version output add subcommands and run functions etc.

Without any options passed, the default implementation returns a Command with no subcommands, a -v/--version and a -h/--help flag, hooked up to os.Stdin, os.Stdout and os.Stderr and accepting arbitrary positional arguments from os.Args (with the command path stripped, equivalent to os.Args[1:]).

Options will validate their inputs where possible and return errors which will be bubbled up through New to aid debugging invalid configuration.

func Allow ¶

func Allow(validator ArgValidator) Option

Allow is an Option that allows for validating positional arguments to a Command.

You provide a validator function that returns an error if it encounters invalid arguments, and it will be run for you, passing in the non-flag arguments to the Command that was called.

Successive calls overwrite previous ones, use Combine to compose multiple validators.

// No positional arguments allowed
cli.New("test", cli.Allow(cli.NoArgs()))

func BuildDate ¶ added in v0.2.0

func BuildDate(date string) Option

BuildDate is an Option that sets the build date for a binary built with CLI. It is particularly useful for embedding rich version info into a binary using ldflags

Without this option, the build date is simply omitted from the version info shown when -v/--version is called.

If set to a non empty string, the build date will be shown.

cli.New("test", cli.BuildDate("2024-07-06T10:37:30Z"))

func Commit ¶ added in v0.2.0

func Commit(commit string) Option

Commit is an Option that sets the commit hash for a binary built with CLI. It is particularly useful for embedding rich version info into a binary using ldflags.

Without this option, the commit hash is simply omitted from the version info shown when -v/--version is called.

If set to a non empty string, the commit hash will be shown.

cli.New("test", cli.Commit("b43fd2c"))

func Example ¶

func Example(comment, command string) Option

Example is an Option that adds an example to a Command.

Examples take the form of an explanatory comment and a command showing the command to the CLI, these will show up in the help text.

For example, a program called "myrm" that deletes files and directories might have an example declared as follows:

cli.Example("Delete a folder recursively without confirmation", "myrm ./dir --recursive --force")

Which would show up in the help text like so:

Examples:
# Delete a folder recursively without confirmation
$ myrm ./dir --recursive --force

An arbitrary number of examples can be added to a Command, and calls to Example are additive.

func Flag ¶

func Flag[T Flaggable](p *T, name string, short rune, value T, usage string) Option

Flag is an Option that adds a flag to a Command, storing its value in a variable via it's pointer 'p'.

The variable is set when the flag is parsed during command execution. The value provided by the 'value' argument to Flag is used as the default value, which will be used if the flag value was not given via the command line.

If the default value is not the zero value for the type T, the flags usage message will show the default value in the commands help text.

To add a long flag only (e.g. --delete with no -d option), pass NoShortHand for "short".

Flags linked to slice values (e.g. []string) work by appending the passed values to the slice so multiple values may be given by repeat usage of the flag e.g. --items "one" --items "two".

// Add a force flag
var force bool
cli.New("rm", cli.Flag(&force, "force", 'f', false, "Force deletion without confirmation"))

func Long ¶

func Long(long string) Option

Long is an Option that sets the full description for a Command.

The long description will appear in the help text for a command. Users are responsible for wrapping the text at a sensible width.

For consistency of formatting, all leading and trailing whitespace is stripped.

Successive calls will simply overwrite any previous calls.

cli.New("rm", cli.Long("... lots of text here"))

func NoColour ¶ added in v0.10.0

func NoColour(noColour bool) Option

NoColour is an Option that disables all colour output from the Command.

CLI respects the values of $NO_COLOR and $FORCE_COLOR automatically so this need not be set for most applications.

Setting this option takes precedence over all other colour configuration.

func OptionalArg ¶ added in v0.10.0

func OptionalArg(name, description, value string) Option

OptionalArg is an Option that adds a named positional argument, with a default value, to a Command.

An optional named argument is given a name, a description, and a default value that will be shown in the help text. If the argument isn't given when the command is invoke, the default value is used in it's place.

The order of calls matters, each call to OptionalArg effectively appends an optional, named positional argument to the command so the following:

cli.New(
    "cp",
    cli.OptionalArg("src", "The file to copy", "./default-src.txt"),
    cli.OptionalArg("dest", "Where to copy to", "./default-dest.txt"),
)

results in a command that will expect the following args *in order*

cp src.txt dest.txt

If the argument should be required (e.g. no sensible default), use RequiredArg.

Arguments added to the command may be retrieved by name from within command logic with Command.Arg.

func OverrideArgs ¶ added in v0.6.0

func OverrideArgs(args []string) Option

OverrideArgs is an Option that sets the arguments for a Command, overriding any arguments parsed from the command line.

Without this option, the command will default to os.Args[1:], this option is particularly useful for testing.

Successive calls override previous ones.

// Override arguments for testing
cli.New("test", cli.OverrideArgs([]string{"test", "me"}))

func RequiredArg ¶ added in v0.10.0

func RequiredArg(name, description string) Option

RequiredArg is an Option that adds a required named positional argument to a Command.

A required named argument is given a name, and a description that will be shown in the help text. Failure to provide this argument on the command line when the command is invoked will result in an error from Command.Execute.

The order of calls matters, each call to RequiredArg effectively appends a required, named positional argument to the command so the following:

cli.New(
    "cp",
    cli.RequiredArg("src", "The file to copy"),
    cli.RequiredArg("dest", "Where to copy to"),
)

results in a command that will expect the following args *in order*

cp src.txt dest.txt

If the argument should have a default value if not specified on the command line, use OptionalArg.

Arguments added to the command may be retrieved by name from within command logic with Command.Arg.

func Run ¶

func Run(run func(cmd *Command, args []string) error) Option

Run is an Option that sets the run function for a Command.

The run function is the actual implementation of your command i.e. what you want it to do when invoked.

Successive calls overwrite previous ones.

func Short ¶

func Short(short string) Option

Short is an Option that sets the one line usage summary for a Command.

The one line usage will appear in the help text as well as alongside subcommands when they are listed.

For consistency of formatting, all leading and trailing whitespace is stripped.

Successive calls will simply overwrite any previous calls.

cli.New("rm", cli.Short("Delete files and directories"))

func Stderr ¶

func Stderr(stderr io.Writer) Option

Stderr is an Option that sets the Stderr for a Command.

Successive calls will simply overwrite any previous calls. Without this option the command will default to os.Stderr.

// Set stderr to a temporary buffer
buf := &bytes.Buffer{}
cli.New("test", cli.Stderr(buf))

func Stdin ¶

func Stdin(stdin io.Reader) Option

Stdin is an Option that sets the Stdin for a Command.

Successive calls will simply overwrite any previous calls. Without this option the command will default to os.Stdin.

// Set stdin to os.Stdin (the default anyway)
cli.New("test", cli.Stdin(os.Stdin))

func Stdout ¶

func Stdout(stdout io.Writer) Option

Stdout is an Option that sets the Stdout for a Command.

Successive calls will simply overwrite any previous calls. Without this option the command will default to os.Stdout.

// Set stdout to a temporary buffer
buf := &bytes.Buffer{}
cli.New("test", cli.Stdout(buf))

func SubCommands ¶

func SubCommands(builders ...Builder) Option

SubCommands is an Option that attaches 1 or more subcommands to the command being configured.

Sub commands must have unique names, any duplicates will result in an error.

This option is additive and can be called as many times as desired, subcommands are effectively appended on every call.

func Version ¶

func Version(version string) Option

Version is an Option that sets the version for a Command.

Without this option, the command defaults to a version of "dev".

cli.New("test", cli.Version("v1.2.3"))