Go Cobra: Build Complex CLIs Like `kubectl`

Why it exists

Building a command-line app from scratch in Go is tedious. You have to manually parse arguments, handle subcommands, generate help text, and manage flags. This leads to lots of boilerplate code that isn't consistent across applications. Cobra was created to solve this by providing a standard, powerful framework for building complex, production-grade CLIs.

The mental model

Think of Cobra as a skeleton for your CLI application. Instead of you figuring out how to connect a server command to a start subcommand, Cobra provides a "command tree." You define individual Command objects and attach them to each other, like branches on a tree. Cobra then handles routing user input (like app server start) to the correct function, parsing flags, and generating help text automatically.

How it works

You define your application's structure using cobra.Command structs. The root command is the main entry point. You add subcommands to it using the AddCommand() method. Each command has a Run function where you place its business logic. Flags are defined and bound to variables. Cobra uses this structure to parse the command line arguments, find the right command to execute, and populate your flag variables before calling your Run function. It also generates help and usage text based on the command definitions.

When to use it

Use Cobra when your Go application needs a rich command-line interface. This is especially true for applications with multiple nested subcommands (e.g., app db migrate up), persistent flags that apply globally (--config), required flags, and automatic shell completion. Its integration with Viper for configuration management also makes it a strong choice for 12-factor apps.

When not to use it

Avoid Cobra for very simple command-line tools that perform one task and only need a few flags. For these cases, Go's built-in flag package is simpler and results in less dependency overhead. Cobra's power is in managing command complexity; if there is no complexity, it can be overkill.

One canonical example

Kubernetes' kubectl is the quintessential Cobra application. It has hundreds of commands and subcommands (kubectl get pods, kubectl apply -f, kubectl logs my-pod). Cobra manages this entire complex tree, providing consistent flag parsing (like the global --namespace or -n flag), help text, and command discovery, making a massive tool manageable for users.