Cobra

Cobra is a Go library for building modern, POSIX-compliant command-line applications with nested subcommands, persistent and local flags, and automatic help generation. It provides both an interface for defining commands and a controller for organizing application code, following the APPNAME COMMAND ARG --FLAG pattern used by tools like git and go.

Cobra powers CLIs for some of the most widely used projects in the Go ecosystem, including Kubernetes, Hugo, and the GitHub CLI. Beyond command dispatch, it auto-generates shell completions for bash, zsh, fish, and PowerShell, plus man pages, Markdown, REST, and YAML documentation directly from the same command definitions.

What You Get

• A Command struct with a full lifecycle (PersistentPreRun -> PreRun -> Run/RunE -> PostRun -> PersistentPostRun) for organizing CLI logic
• POSIX-compliant flag parsing via the bundled pflag library, with cascading persistent and local flags
• Auto-generated shell completions for bash, zsh, fish, and PowerShell
• Auto-generated man pages, Markdown, REST, and YAML documentation from your command definitions
• The cobra-cli generator to scaffold new CLI projects and commands

Common Use Cases

• Building a git- or kubectl-style CLI with nested subcommands and per-command flags
• Adding a controller layer that organizes a Go application’s command-line entry points
• Shipping shell autocompletion alongside a CLI without hand-writing completion scripts
• Generating consistent man pages and reference docs directly from command source

Under The Hood

Architecture

Cobra’s core abstraction is the Command struct (command.go, 2000+ lines) organized into a tree: each Command holds child Commands, its own pflag.FlagSet, and a chain of lifecycle hooks (PersistentPreRun -> PreRun -> Run/RunE -> PostRun -> PersistentPostRun). Execute() walks up to the root Command via Root(), then ExecuteC() resolves os.Args against the Command tree, parses flags through the embedded pflag.FlagSet, and dispatches into the matched command’s lifecycle chain. That same tree is reused as the single source of truth for shell completion generation (completions.go plus per-shell files for bash/zsh/fish/powershell) and documentation generation (the doc/ package, which walks Use/Short/Long/Example fields to emit man pages, Markdown, REST, and YAML docs). This ‘one struct drives execution, completion, and docs’ design is Cobra’s central architectural decision.

Tech Stack

go.mod declares module github.com/spf13/cobra targeting Go 1.15 for broad compatibility, with a deliberately minimal dependency set: github.com/spf13/pflag (Cobra’s own POSIX-compliant flag-parsing fork, doing the actual flag work), github.com/cpuguy83/go-md2man/v2 (Markdown-to-man-page conversion for generated docs), github.com/inconshreveable/mousetrap (a Windows-only check that warns users who double-click the binary instead of running it from a terminal), and go.yaml.in/yaml/v3 (YAML doc generation). There is no runtime framework dependency beyond pflag - the library compiles straight into consumer code, and a Makefile plus a GitHub Actions workflow drive linting, testing, and doc generation in CI.

Code Quality

The repository ships 11 _test.go files at the package root (command_test.go, args_test.go, completions_test.go, bash_completions_test.go, flag_groups_test.go, and more) plus a further test suite inside doc/ for the generated-docs package, covering command resolution, argument validation, flag groups, and every completion shell. Error handling is idiomatic Go - RunE/PreRunE/PersistentPreRunE variants return error rather than panicking, and Args validators (args.go) return descriptive errors on mismatch (ExactArgs, MinimumNArgs, OnlyValidArgs). Naming is consistent and exported identifiers are documented with godoc comments throughout; command.go is the one large file (2000+ lines) that centralizes most of the Command type’s behavior rather than splitting it across files, a defensible but monolithic choice for a struct this central.

API Design Cobra’s public API is declarative: a consumer builds cobra.Command{Use, Short, Long, RunE: ...} values and calls AddCommand/Execute, with almost no required boilerplate to get a working CLI with --help, -h, and command suggestions (‘did you mean…’) for free. Persistent and local flags cascade automatically from parent to child commands, and the same struct fields (Use, Short, Long, Example, ValidArgs) simultaneously drive --help output, shell completions, and generated docs, so documenting a command once documents it everywhere. The companion cobra-cli generator scaffolds new commands/projects, further lowering the barrier to a consistent project layout - this consistency is what most reviewers cite as Cobra’s strongest developer-experience trait.