cli

Documentation

Overview

Package cli provides a simple way to create tree-like command-line interfaces while staying as close as possible to the standard flag package.

Index

• Variables
• func Get(ctx context.Context, name string) any
• type Command
  • func (c *Command) Run(ctx context.Context, args []string) error

Variables

var Usage = func(c *Command, fs *flag.FlagSet) {
	w := fs.Output()

	usage := []any{"Usage:", c.Name}
	if c.Flags != nil {
		usage = append(usage, "[options]")
	}
	if len(c.Subcommands) > 0 {
		usage = append(usage, "COMMAND")
	}
	usage = append(usage, c.UsageArgs)
	fmt.Fprintln(w, usage...)

	if c.Usage != "" {
		fmt.Fprintln(w)
		fmt.Fprintln(w, c.Usage)
	}

	if c.Flags != nil {
		fmt.Fprintln(w)
		fmt.Fprintln(w, "Options:")
		fs.PrintDefaults()
	}

	if len(c.Subcommands) > 0 {
		fmt.Fprintln(w)
		fmt.Fprintln(w, "Commands:")

		lines := []fmt.Stringer{}
		width := 0
		for _, c := range c.Subcommands {
			lines = append(lines,
				stringerFunc(func() string { return fmt.Sprintf("  %-*s    %s", width, c.Name, c.Usage) }),
			)
			width = max(width, len(c.Name))
		}
		for _, line := range lines {
			fmt.Fprintln(w, line)
		}
	}
}

Usage is the function called when an error occurs when parsing flags or when help is requested. It may be customized by the user.

Functions

func Get

func Get(ctx context.Context, name string) any

Get looks for the named flag and returns its value. It returns nil if:

• the specified flag.Flag was not found
• its flag.Value does not implement flag.Getter
• the flag.Getter itself returns nil

Types

type Command

type Command struct {
	// Name of the command.
	Name string
	// Usage description of the command.
	Usage string
	// Usage command argument placeholders.
	UsageArgs string
	// Flags definition function for this command.
	Flags func(fs *flag.FlagSet)
	// Flags marked as required, enabling early failure.
	FlagsRequired []string
	// Function for adding custom code and passing values around the execution
	// of the actual [Command]. Any error returned here is reported by the
	// [Command.Run] method.
	//
	// For instance, this can be useful for handling shared resources:
	//
	// func(parent context.Context, run func(ctx context.Context) error) error {
	// 	db, err := sql.Open("postgres", cli.Get(parent, "dsn").(string))
	// 	if err != nil {
	// 		return err
	// 	}
	// 	defer db.Close()
	// 	return run(context.WithValue(parent, dbKey{}, db))
	// }
	//
	// This opens a database handler and stores it in the context, making it
	// available from this node to the remaining of the tree. This approach
	// supports deferred statements, keeping cleanup code idiomatic.
	RunContext func(parent context.Context, run func(ctx context.Context) error) error
	// Subcommands definitions.
	Subcommands []*Command
	// Command function to run.
	Func func(ctx context.Context, args []string) error
}

Command is the basic building block of command-line interfaces.

func (*Command) Run

func (c *Command) Run(ctx context.Context, args []string) error

Run runs the command tree by parsing environment & flag arguments into flag.Value and store them in the context. If a subcommand can be run using the remaining non-flag arguments, then it is run, otherwise it runs the Command's function. If there is no function to run, it prints usage and returns.