Cobra — API Surface#

API types#

Library (primary) — Cobra is consumed purely as a Go library. There is no HTTP server, no gRPC service, and no standalone binary. The doc/ subpackage adds a secondary, optional library API for documentation generation.

REST/HTTP API#

Not applicable. Cobra does not expose any HTTP endpoints.

gRPC API#

Not applicable. No .proto files exist in the repository.

CLI (if applicable)#

Cobra does not itself produce a CLI binary. Rather, it is the framework that other CLIs are built with. However, Cobra injects several built-in subcommands into every application that uses it:

• help [command] — auto-generated; shows usage for the root or any subcommand.
• completion [bash|zsh|fish|powershell] — auto-generated; prints the shell completion script for the chosen shell. Can be suppressed via CompletionOptions.DisableDefaultCmd.
• __complete / __completeNoDesc — hidden; called by shell completion scripts to obtain dynamic completion candidates at runtime.

Flag patterns injected by cobra#

• --help / -h — added lazily to every command via InitDefaultHelpFlag()
• --version / -v — added lazily to any command that sets Command.Version
• --no-descriptions — added to completion subcommands for shells that support descriptions

Plugin / Extension system#

Cobra does not have a plugin system in the hashicorp/go-plugin or RPC sense. Its extensibility is purely interface/function-field–based:

Extension points#

Library API (primary usage mode)#

Core package (github.com/spf13/cobra)#

Exported types#

Package-level variables (behavioral configuration)#

Positional argument validators (package-level functions)#

Completion helpers (package-level functions)#

Flag annotation helpers (package-level functions on pflag.FlagSet)#

Key *Command methods — grouped by concern#

Execution:

• Execute() error — entry point; parses os.Args[1:] and dispatches
• ExecuteContext(ctx) error — Execute with a context
• ExecuteC() (*Command, error) — Execute returning the matched command
• ExecuteContextC(ctx) (*Command, error) — combination of above two

Tree management:

• AddCommand(cmds ...*Command) — attach subcommands
• RemoveCommand(cmds ...*Command) — detach subcommands
• Commands() []*Command — list direct children
• ResetCommands() — remove all children
• AddGroup(groups ...*Group) — register display groups
• Groups() []*Group — list groups
• Parent() *Command / Root() *Command — navigation
• Find(args) (*Command, []string, error) — tree search by args
• Traverse(args) (*Command, []string, error) — tree search with flag parsing

Flag management:

• Flags() *pflag.FlagSet — local + inherited flags
• PersistentFlags() *pflag.FlagSet — flags inherited by children
• LocalFlags() *pflag.FlagSet — flags local to this command
• InheritedFlags() *pflag.FlagSet — flags from ancestors
• ParseFlags(args) error — invoke pflag parsing
• Flag(name) *pflag.Flag — lookup by name
• MarkFlagRequired(name) error — require a flag
• MarkPersistentFlagRequired(name) error
• MarkFlagFilename(name, exts...) error
• MarkPersistentFlagFilename(name, exts...) error
• MarkFlagDirname(name) error
• MarkPersistentFlagDirname(name) error
• MarkFlagsRequiredTogether(flagNames...) — cross-flag dependency
• MarkFlagsOneRequired(flagNames...) — at-least-one-required group
• MarkFlagsMutuallyExclusive(flagNames...) — mutual exclusion group
• ValidateFlagGroups() error — check cross-flag constraints
• RegisterFlagCompletionFunc(name, CompletionFunc) error — per-flag dynamic completions
• GetFlagCompletionFunc(name) (CompletionFunc, bool)

I/O:

• SetOut(io.Writer) / OutOrStdout() io.Writer
• SetErr(io.Writer) / ErrOrStderr() io.Writer
• SetIn(io.Reader) / InOrStdin() io.Reader
• Print, Println, Printf, PrintErr, PrintErrln, PrintErrf — write to configured writers

Display / help:

• SetHelpFunc(func(*Command, []string)) — override help rendering
• SetHelpTemplate(string) — override help template
• SetUsageFunc(func(*Command) error) — override usage rendering
• SetUsageTemplate(string) — override usage template
• SetVersionTemplate(string) — override version output
• SetErrPrefix(string) — prefix on error messages
• SetHelpCommand(*Command) — replace the built-in help command
• Help() error / Usage() error — manually invoke help/usage output
• UsageString() string — capture usage as a string

Shell completions:

• GenBashCompletionV2(w, includeDesc) error / GenBashCompletionFileV2(filename, includeDesc) error
• GenBashCompletion(w) error / GenBashCompletionFile(filename) error (legacy V1)
• GenZshCompletion(w) error / GenZshCompletionFile(filename) error
• GenZshCompletionNoDesc(w) error / GenZshCompletionFileNoDesc(filename) error
• GenFishCompletion(w, includeDesc) error / GenFishCompletionFile(filename, includeDesc) error
• GenPowerShellCompletion(w) error / GenPowerShellCompletionFile(filename) error
• GenPowerShellCompletionWithDesc(w) error / GenPowerShellCompletionFileWithDesc(filename) error
• InitDefaultCompletionCmd(args...) — manually trigger injection of completion subcommand

Inspection / metadata:

• Name() string / DisplayName() string / CommandPath() string
• HasSubCommands() bool / IsAvailableCommand() bool / Runnable() bool
• HasFlags() bool / HasPersistentFlags() bool / HasAvailableFlags() bool
• SuggestionsFor(typedName) []string — Levenshtein-based suggestions
• CalledAs() string — alias or name actually used at runtime
• ArgsLenAtDash() int — index of -- separator in args

Context:

• Context() context.Context
• SetContext(ctx context.Context)

doc/ subpackage (github.com/spf13/cobra/doc)#

Exported types#

Exported functions — grouped by output format#

All functions recursively walk the command tree via a shared Walk(cmd, fn) utility.

API style and design observations#

Fluent struct literal construction (primary idiom)#

Cobra’s API is designed around constructing Command structs with named fields in a struct literal — not via constructors or builders. This is the idiomatic entrypoint:

rootCmd := &cobra.Command{
    Use:   "myapp",
    Short: "A brief description",
    RunE: func(cmd *cobra.Command, args []string) error {
        return doWork(args)
    },
}

This makes command definitions readable and self-documenting but requires understanding a large struct.

Function fields over interfaces#

Hooks (Run, PreRun, ValidArgsFunction, etc.) are function fields, not interface methods. This avoids forcing consumers to define named types and enables inline closures. It is the dominant extensibility mechanism.

Method chaining is absent#

Cobra does not use a builder pattern. Configuration calls are independent method calls (cmd.Flags().StringVar(...), cmd.MarkFlagRequired(...)), not chained.

Backward compatibility#

Cobra maintains strong backward compatibility. Legacy APIs (GenBashCompletion V1, ExactValidArgs, MarkZshCompPositionalArgument*) are kept alongside their modern replacements. The doc/ package is separately versioned to avoid dragging doc-gen dependencies into the core.

pflag re-export#

Cobra does not re-export pflag types directly but exposes them through Flags(), PersistentFlags(), etc. Consumers must import pflag separately to call StringVar, BoolP, and similar flag definition methods.