Tiny, simple, but powerful CLI framework for modern Go 🚀
Warning
CLI is still in development and is not yet stable
cli is a simple, minimalist, zero-dependency yet functional and powerful CLI framework for Go. Inspired by things like spf13/cobra and urfave/cli, but building on lessons learned and using modern Go techniques and idioms.
go get github.com/FollowTheProcess/cli@latestpackage main
import (
"fmt"
"os"
"github.com/FollowTheProcess/cli"
)
func main() {
if err := run(); err != nil {
fmt.Fprintf(os.Stderr, "Error: %v\n", err)
os.Exit(1)
}
}
func run() error {
var count int
cmd, err := cli.New(
"quickstart",
cli.Short("Short description of your command"),
cli.Long("Much longer text..."),
cli.Version("v1.2.3"),
cli.Commit("7bcac896d5ab67edc5b58632c821ec67251da3b8"),
cli.BuildDate("2024-08-17T10:37:30Z"),
cli.Allow(cli.MinArgs(1)), // Must have at least one argument
cli.Stdout(os.Stdout),
cli.Example("Do a thing", "quickstart something"),
cli.Example("Count the things", "quickstart something --count 3"),
cli.Flag(&count, "count", 'c', 0, "Count the things"),
cli.Run(runQuickstart(&count)),
)
if err != nil {
return err
}
return cmd.Execute()
}
func runQuickstart(count *int) func(cmd *cli.Command, args []string) error {
return func(cmd *cli.Command, args []string) error {
fmt.Fprintf(cmd.Stdout(), "Hello from quickstart!, my args were: %v, count was %d\n", args, *count)
return nil
}
}Will get you the following:
Tip
See usage section below and more examples under ./examples
To create CLI commands, you simply call cli.New:
cmd, err := cli.New(
"name", // The name of your command
cli.Short("A new command") // Shown in the help
cli.Run(func(cmd *cli.Command, args []string) error {
// This function is what your command does
fmt.Printf("name called with args: %v\n", args)
return nil
})
)Tip
The command can be customised by applying any number of functional options for setting the help text, describing the arguments or flags it takes, adding subcommands etc. see https://pkg.go.dev/github.com/FollowTheProcess/cli#Option
To add a subcommand underneath the command you've just created, it's again cli.New:
// Best to abstract it into a function
func buildSubcommand() (*cli.Command, error) {
return cli.New(
"sub", // Name of the sub command e.g. 'clone' for 'git clone'
cli.Short("A sub command"),
// etc..
)
}And add it to your parent command:
// From the example above
cmd, err := cli.New(
"name", // The name of your command
// ...
cli.SubCommands(buildSubcommand),
)This pattern can be repeated recursively to create complex command structures.
Flags in cli are generic, that is, there is one way to add a flag to your command, and that's with the cli.Flag option to cli.New
type options struct {
name string
force bool
size uint
items []string
}
func buildCmd() (*cli.Command, error) {
var opts options
return cli.New(
// ...
// Signature is cli.Flag(*T, name, shorthand, default, description)
cli.Flag(&options.name, "name", 'n', "", "The name of something"),
cli.Flag(&options.force, "force", cli.NoShortHand, false, "Force delete without confirmation"),
cli.Flag(&options.size, "size", 's', 0, "Size of something"),
cli.Flag(&options.items, "items", 'i', nil, "Items to include"),
cli.Run(runCmd(&options)), // Pass the parsed flag values to your command run function
)
}The types are all inferred automatically! No more BoolSliceVarP ✨
The types you can use for flags currently are:
intint8int16int32int64uintuint8uint16uint32uint64uintptrfloat32float64stringbool[]byte(interpreted as a hex string)Count(special type for flags that count things e.g. a--verbosityflag may be used like-vvvto increase verbosity to 3)time.Timetime.Durationnet.IP[]int[]int8[]int16[]int32[]int64[]uint[]uint16[]uint32[]uint64[]float32[]float64[]string
Note
You basically can't get this wrong, if you try and use an unsupported type, the Go compiler will yell at you
When designing and implementing cli, I had some core goals and guiding principles for implementation.
cli validates heavily and returns errors for you to handle. By contrast spf13/cobra (and by extension spf13/pflag) panic in a number of (IMO unnecessary) conditions including:
- Duplicate subcommand
- Command adding itself as a subcommand
- Duplicate flag
- Invalid shorthand flag letter
The design of cli is such that commands are instantiated with cli.New and a number of functional options. These options are in charge of configuring your command and each will perform validation prior to applying the setting.
These errors are joined and bubbled up to you in one go via cli.New so you don't have to play error whack-a-mole, and more importantly your application won't panic!
cli has an intentionally small public interface and gives you only what you need to build amazing CLI apps:
- No huge structs with hundreds of fields
- No confusing or conflicting options
- Customisation in areas where it makes sense, sensible opinionated defaults everywhere else
- No reflection or struct tags
There is one and only one way to do things (and that is usually to use an option in cli.New)
The dominant Go CLI toolkits were mostly built many years (and many versions of Go) ago. They are reliable and battle hardened but because of their high number of users, they have had to be very conservative with changes.
cli has none of these constraints and can use bang up to date Go techniques and idioms.
One example is generics, consider how you define a flag:
var force bool
cli.New("demo", cli.Flag(&force, "force", 'f', false, "Force something"))Note the type bool is inferred by cli.Flag. This will work with any type allowed by the Flaggable generic constraint so you'll get compile time feedback if you've got it wrong. No more flag.BoolStringSliceVarP 🎉
cli heavily leverages the functional options pattern to create a delightful experience building a CLI tool. It almost reads like plain english:
var count int
cmd, err := cli.New(
"test",
cli.Short("Short description of your command"),
cli.Long("Much longer text..."),
cli.Version("v1.2.3"),
cli.Allow(cli.MinArgs(1)),
cli.Stdout(os.Stdout),
cli.Example("Do a thing", "test run thing --now"),
cli.Flag(&count, "count", 'c', 0, "Count the things"),
)Typically, commands are implemented as a big struct with lots of fields. cli is no different in this regard.
What is different though is that this large struct can only be configured with cli.New. Once you've built your command, it can't be modified.
This eliminates a whole class of bugs and prevents misconfiguration and footguns 🔫
Everything in cli is (hopefully) clear, intuitive, and well-documented. There's a tonne of strict validation in a bunch of places and wherever possible, misuse results in a compilation error.
Consider the following example of a bad shorthand value:
var delete bool
// Note: "de" is a bad shorthand, it's two letters
cli.New("demo", cli.Flag(&delete, "delete", "de", false, "Delete something"))In cli this is impossible as we use rune as the type for a flag shorthand, so the above example would not compile. Instead you must specify a valid rune:
var delete bool
// Ahhh, that's better
cli.New("demo", cli.Flag(&delete, "delete", 'd', false, "Delete something"))And if you don't want a shorthand? i.e. just --delete with no -d option:
var delete bool
cli.New("demo", cli.Flag(&delete, "delete", cli.NoShortHand, false, "Delete something"))I built cli for my own uses really, so I've quickly adopted it across a number of tools. See the following projects for some working examples in real code: