cli

Overview ¶

Package cli provides a lightweight framework for creating command-line interfaces (CLIs). It supports defining commands as functions or objects, organizing them into subcommand groups, parsing flags using the [flag.FlagSet]s, and generating documentation via built-in commands: "help", "flags", and "commands".

Key features:

• Commands defined as functions or objects implementing the Command interface.
• Hierarchical subcommand groups.
• Flag parsing using flag.FlagSet with custom error handling.
• Automatic documentation through built-in commands.
• Custom documentation using optional interfaces.
• Context-aware execution for cancellation and timeouts.
• Redirect a command's stdout to any io.Writer.

Create commands with NewCommand for functions, NewGroup for subcommands, or custom types implementing the Command interface. Execute the CLI by passing commands to Run with command-line arguments.

Example (Function-based command):

var listFlags flag.FlagSet
verbose := listFlags.Bool("v", false, "Enable verbose output")
listCmd := func(ctx context.Context, args []string) error {
    if *verbose {
        fmt.Println("Verbose listing")
    } else {
        fmt.Println("Listing")
    }
    return nil
}
cmd := cli.NewCommand("list", listCmd, &listFlags, "List resources")
cli.Run(context.Background(), []cli.Command{cmd}, os.Args)

Example (Object-based command):

type GreetCommand struct {
    name  string
}
func (c *GreetCommand) Command() (string, *flag.FlagSet, cli.CmdFunc) {
    fset := new(flag.FlagSet)
    fset.StringVar(&c.name, "name", "World", "Name to greet")
    return "greet", fset, func(ctx context.Context, args []string) error {
        fmt.Printf("Hello, %s!\n", c.name)
        return nil
    }
}
cmd := &GreetCommand{}
cli.Run(context.Background(), []cli.Command{cmd}, os.Args)

Optional interfaces for documentation:

type Purpose interface {
  // One line use or summary for the command.
  Purpose() string
}

type Description interface {
  // Multi line or multi-paragraph help for the command.
  Description() string
}