README.md

boa - all snake, no venom

A venom-free generator for cobra applications.

Installation

go get -u github.com/oncilla/boa/cmd/boa

Docker

If you prefer using docker instead:

WORKDIR=$(pwd)/path/to/application
docker run \
    -v $WORKDIR/:/workdir \
    --user "$(id -u):$(id -g)" \
    docker.pkg.github.com/oncilla/boa/boa:latest

Getting started

boa proposes a different layout than what cobra proposes as a typical structure.

The commands all live in main package, alongside the main function.

cmd/my-app/
├── my-app.go      # main function
├── completion.go  # completion command
└── version.go     # version command

The commands should be fairly slim and only take care of checking flags and initializing the application. Business logic should not go here, but move to a separate package to ensure it is decoupled from the CLI, reusable and has no access to global values.

Where you put it is up to you, just try to have the main package as slim as possible.

Initializing an application

With boa, your project can have one or multiple cobra based applications. The simplest approach is to have the main package in the project root.

boa init my-app

This creates a runnable cobra application skeleton. Try it out with:

go run *.go --help

The completion and version are created by default, to showcase how a boa style application can look like.

If you want to support multiple cobra applications in your project, or want to keep the root directory clean, you can create the application in a sub-directory:

boa init --path cmd/my-app my-app

Adding a command

To add a command, simply run the add command:

boa add greet --flags name:string,age:int

If you have provided a path before, make sure to provide the same path again, or navigate to the corresponding main package first.

This command creates new file called greet.go with a license header and a cobra command generation function.

func newGreet(pather CommandPather) *cobra.Command {
        var flags struct {
                name string
                age  int
        }

        var cmd = &cobra.Command{
                Use:     "greet <arg>",
                Short:   "greet does amazing work!",
                Example: fmt.Sprintf("  %[1]s greet --sample", pather.CommandPath()),
                RunE: func(cmd *cobra.Command, args []string) error {
                        // Add basic sanity checks, where the usage help message should be
                        // printed on error, before this line. After this line, the usage
                        // message is no longer printed on error.
                        cmd.SilenceUsage = true

                        // TODO: Amazing work goes here!
                        return nil
                },
        }

        cmd.Flags().StringVar(&flags.name, "name", "", "name description")
        cmd.Flags().IntVar(&flags.age, "age", 0, "age description")
        return cmd
}

Boa suggests to use the SilenceErrors and SilenceUsage. For more information, see: spf13/cobra#340 (comment)

You now need to register the command with its parent. For the sake of this example, it is simply the root command. Update my-app.go with:

    cmd.AddCommand(
        newCompletion(cmd),
        newGreet(cmd),
        newVersion(cmd),
    )

That's it, the new command is now registered and can already be used:

$ go run *.go greet --help
greet does amazing work!

Usage:
  my-app greet <arg> [flags]

Examples:
  my-app greet --sample

Flags:
      --age int       age description
  -h, --help          help for greet
      --name string   name description

Why boa?

The cobra library is an amazing and powerful toolkit for creating command line applications. However, the example projects display some drawbacks that boa tries to improve upon.

Directory structure

The proposed rigid directory structure in the examples and the generator go against the commonly used patterns how applications are structured nowadays.

boa proposes to have all commands in the same directory. The key here is, that the main package should only be used for initialization and very simple tasks. Bigger business logic should live in a separate package, ensuring that it is reusable, and decoupled from the CLI interface.

Command registration

Commands are proposed to be registered inside an init function. Essentially forcing global state, and making it hard for commands to be tested.

With the approach proposed by boa, testing a command is as simple as:

func TestMyCommand(t *testing.T) {
    cmd := newMyCommand(boa.Pather(""))
    cmd.SetArgs([]string{"--my", "args"})
    err := cmd.Execute()
    if err != nil {
        t.Fail()
    }
}

Global flags

Flags are proposed to be package global variables and registered in the init function. This can lead to code that is full of surprises, as package globals taint logic very easily if you do not take care.

With the approach proposed by boa, each instance of a command has its own set of flags, and there is no way for other components to access them directly.