Cobra
By spf13 and Cobra contributors
Cobra is a Go library for building command-line applications with nested subcommands, flags, and automatically generated help text, modeled after the command structure used by tools such as Git and Kubernetes' `kubectl`. It provides a…
Definition
Cobra is a Go library for building command-line applications with nested subcommands, flags, and automatically generated help text, modeled after the command structure used by tools such as Git and Kubernetes' `kubectl`. It provides a `Command` type that can be composed into trees of commands and subcommands, each with its own flags, arguments, and execution logic. Cobra is used by many well-known Go CLI tools to structure commands consistently and generate polished help output with minimal boilerplate.
Overview
Cobra was created by developer Steve Francia to give Go developers a standard way to build command-line interfaces with the kind of nested-subcommand structure common in modern developer tools, where a single binary exposes many related actions, such as `git commit` or `docker container ls`, rather than a flat list of flags on one command. Before libraries like Cobra existed, teams typically hand-rolled subcommand parsing on top of Go's standard `flag` package, which becomes unwieldy once a tool grows past a handful of top-level actions. Mechanically, a Cobra application is built from `Command` structs, each carrying a name, short and long descriptions, a `Run` function containing its logic, and a set of flags defined either locally to that command or persistently, meaning they are inherited by all of its subcommands. Commands are attached to a root command to form a tree, and Cobra's runtime handles parsing the command line, walking that tree to find the matching command, and invoking its `Run` function with any remaining arguments and parsed flags. Cobra also auto-generates help text, usage strings, and shell completion scripts for Bash, Zsh, Fish, and PowerShell directly from the command tree's metadata, without requiring the author to write that documentation by hand. Cobra is frequently paired with Viper, a companion configuration library also associated with the same maintainers, which lets a CLI's flags, environment variables, and configuration files feed into the same set of settings; the two are commonly used together but are independent libraries with no hard dependency on each other. Compared with Go's standard `flag` package, Cobra adds the subcommand tree, structured help generation, and completion scripts that `flag` does not provide on its own, at the cost of pulling in an external dependency and adopting Cobra's own conventions for defining commands. In practice, Cobra underlies the CLI structure of many prominent Go-based tools, including Kubernetes' `kubectl`, Hugo, GitHub's `gh` CLI, and Docker's CLI components, which has made its command-tree pattern a familiar convention across the Go tooling ecosystem. A companion tool, `cobra-cli`, can scaffold a new Cobra-based project and generate boilerplate for new commands, further reducing setup time for common CLI patterns. Cobra's main trade-off is that its command-tree abstraction adds a layer of indirection compared to a flat `flag`-based parser, which is unnecessary overhead for a tool with only one or two top-level actions; teams building very simple CLIs sometimes skip Cobra in favor of the standard library or a smaller flag-parsing package, reserving Cobra for tools expected to grow a genuinely nested command surface over time.
Key Features
- Command struct supporting nested trees of subcommands
- Persistent flags inherited automatically by child commands
- Auto-generated help text and usage strings from command metadata
- Shell completion script generation for Bash, Zsh, Fish, PowerShell
- Commonly paired with Viper for unified configuration handling
- cobra-cli scaffolding tool for generating new command boilerplate
- Used as the CLI foundation for kubectl, Hugo, and the gh CLI