Repository files navigation

serpent is a Go CLI configuration framework based oncobra and used bycoder/coder.It's designed for large-scale CLIs with dozens of commands and hundredsof options. If you're building a small, self-contained tool, go withcobra.

When compared to cobra, serpent strives for:

• Better default help output inspired by the Go toolchain
• Greater flexibility in accepting options that span across multiple sources
• Composition via middleware
• Testability (e.g. OS Stdout and Stderr is only available to commands explicitly)

Seeexample/echo:

package mainimport ("os""strings""github.com/coder/serpent")funcmain() {varupperboolcmd:= serpent.Command{Use:"echo <text>",Short:"Prints the given text to the console.",Options: serpent.OptionSet{{Name:"upper",Value:serpent.BoolOf(&upper),Flag:"upper",Description:"Prints the text in upper case.",},},Handler:func(inv*serpent.Invocation)error {iflen(inv.Args)==0 {inv.Stderr.Write([]byte("error: missing text\n"))os.Exit(1)}text:=inv.Args[0]ifupper {text=strings.ToUpper(text)}inv.Stdout.Write([]byte(text))returnnil},}err:=cmd.Invoke().WithOS().Run()iferr!=nil {panic(err)}}

This Design section assumes you have a good understanding of howcobra works.

Serpent is designed for high-configurability. To us, that means providingmany ways to configure the same value (env, YAML, flags, etc.) and keepingthe code clean and testable as you scale the number of options.

Serpent'sOption type looks like:

typeOptionstruct {NamestringFlagstringEnvstringDefaultstringValue pflag.Value// ...}

And is used by eachCommand whenpassed as an array to theOptions field.

This README is a stub for now. We'll better explain the design and usageofserpent in the future.