Golang Spf13 Cobra

Persona: You are a Go CLI engineer building command trees that feel native to the Unix shell. You design the user-facing surface first, then wire behavior into the right hook.

Modes:

• Build — creating a new CLI from scratch: follow command tree setup, hook wiring, and flag sections sequentially.
• Extend — adding subcommands, flags, or completions to an existing CLI: read the current command tree first, then apply changes consistent with the existing structure.
• Review — auditing an existing CLI: check the Common Mistakes table, verify RunE usage, OutOrStdout(), hook chain ordering, and args validation.

Using spf13/cobra for CLI command trees in Go

Cobra is the de facto standard for Go CLI applications. It provides the command/subcommand tree, flag parsing (via pflag), args validation, shell completion generation, and documentation generation. It does not handle configuration layering — that's viper's job.

Official Resources:

• pkg.go.dev/github.com/spf13/cobra
• github.com/spf13/cobra
• cobra.dev

This skill is not exhaustive. Please refer to library documentation and code examples for more information. Context7 can help as a discoverability platform. For Go package docs, versions, symbols, and known vulnerabilities, → See samber/cc-skills-golang@golang-pkg-go-dev skill.

go get github.com/spf13/cobra@latest

Cobra vs. viper

These libraries do fundamentally different things and can be used independently.

Use cobra alone when your binary takes flags and args but needs no config file or env resolution. Use viper alone when you have a long-running service reading config from YAML + env with no CLI subcommands. Use both when you need both — bind at PersistentPreRunE on the root command.

→ See samber/cc-skills-golang@golang-spf13-viper for the viper side of this integration.

Command tree

Every cobra CLI has a root command plus zero or more subcommands registered with AddCommand. The root command name is the binary name.

var rootCmd = &cobra.Command{
    Use:          "myapp",
    Short:        "One-line summary",
    SilenceUsage: true,  // ✓ prevents usage wall on every error
    SilenceErrors: true, // ✓ lets you control error output format
}

Use AddGroup to label subcommands in help output — register groups before the AddCommand calls that reference them; cobra does not retroactively assign groups.

The Run\* family

Cobra commands have five run hooks executed in order:

PersistentPreRunE → PreRunE → RunE → PostRunE → PersistentPostRunE

Always use *E variants — the non-E forms cannot return errors. Key rules:

• PersistentPreRunE on the root runs before every subcommand — use it for config init and auth checks.
• A child PersistentPreRunE replaces the parent's entirely — call the parent explicitly if you need both.
• PostRunE runs only if RunE succeeded.

For the full lifecycle and inheritance rules, see commands-and-args.md.

Args validators

Cobra validates positional arguments before RunE runs. Never write len(args) checks inside RunE — that bypasses cobra's standard error messages and arg count tracking.

Built-ins: NoArgs, ExactArgs(n), MinimumNArgs(n), MaximumNArgs(n), RangeArgs(min,max), OnlyValidArgs, ExactValidArgs(n). Compose with MatchAll(v1, v2). Custom validator: func(cmd *cobra.Command, args []string) error.

For the full validator set with examples and MatchAll patterns, see commands-and-args.md.

Flags primer

Cobra delegates flag parsing to pflag. Persistent flags (PersistentFlags()) are inherited by all subcommands; local flags (Flags()) apply only to the declaring command.

rootCmd.PersistentFlags().StringVar(&cfgFile, "config", "", "config file path") // inherited by all subcommands
serveCmd.Flags().IntVar(&port, "port", 8080, "listen port")                     // local to serveCmd only
serveCmd.MarkFlagRequired("port")
serveCmd.MarkFlagsMutuallyExclusive("json", "yaml")

For pflag types, custom flag values, flag groups, and viper binding, see flags.md.

Completions primer

Cobra generates shell completions automatically. Extend them with:

• `ValidArgs []string` — static positional arg completion.
• `ValidArgsFunction` — dynamic: func(cmd, args, toComplete string) ([]string, ShellCompDirective). Return ShellCompDirectiveNoFileComp to suppress file fallback.
• `RegisterFlagCompletionFunc(name, fn)` — flag value completion.

For ShellCompDirective values, annotations, and testing, see completions.md.

Testing commands

Test commands by executing them programmatically. Never use `os.Stdout` / `os.Stderr` directly in command handlers — use cmd.OutOrStdout() / cmd.ErrOrStderr() so tests can redirect output.

func TestServeCmd(t *testing.T) {
    buf := new(bytes.Buffer)
    rootCmd.SetOut(buf)
    rootCmd.SetArgs([]string{"serve", "--port", "9090"})
    require.NoError(t, rootCmd.Execute())
    assert.Contains(t, buf.String(), "listening on :9090")
}

Cobra accumulates flag state across Execute() calls — build a fresh command tree per test. For isolation patterns, golden files, and testing completions, see testing.md.

Best Practices

1. Always use `RunE`, never `Run` — Run cannot return an error; the only escape is os.Exit or panic, bypassing defers. 2. Put config initialization in `PersistentPreRunE` — it runs before every subcommand; the right place for viper binding and auth checks. 3. Validate positional args with `Args`, not inside `RunE` — Args gives cobra's standard error messages; MatchAll composes validators. 4. Use `cmd.OutOrStdout()` / `cmd.ErrOrStderr()` for all output — direct os.Stdout writes cannot be captured by tests. 5. Re-create the command tree per test — cobra accumulates flag state across Execute() calls on the same instance.

Common Mistakes

Further Reading

• commands-and-args.md — full PreRun\/PostRun\ chain, every Args validator, PersistentPreRunE inheritance rules
• flags.md — pflag types, required/exclusive/oneRequired groups, custom value types, viper binding
• completions.md — ShellCompDirective set, annotation-based completions, testing completions
• generators.md — man page, markdown, YAML, RST doc generation; cobra-cli scaffolder
• testing.md — isolation patterns, golden files, testing completions, table-driven command tests

Cross-References

• → See samber/cc-skills-golang@golang-cli skill for general CLI architecture — project layout, exit codes, signal handling, I/O patterns
• → See samber/cc-skills-golang@golang-spf13-viper skill for configuration layering alongside cobra (flag → env → file → default precedence)
• → See samber/cc-skills-golang@golang-testing skill for general Go testing patterns

If you encounter a bug or unexpected behavior in spf13/cobra, open an issue at <https://github.com/spf13/cobra/issues>.

Cobra Commands, Hooks, and Args Validators

The Run\* lifecycle

Cobra commands have five run hooks. Cobra executes them in this fixed order:

PersistentPreRunE → PreRunE → RunE → PostRunE → PersistentPostRunE

Each *E hook returns error. The non-*E variants (PersistentPreRun, PreRun, Run, PostRun, PersistentPostRun) have signature func(cmd *cobra.Command, args []string) — they cannot signal failure without os.Exit or panic. *Always use the `E` variants.**

Which hook to use

Inheritance rules

PersistentPreRunE defined on the root command runs before every subcommand. But if a child command defines its own PersistentPreRunE, it replaces (does not chain) the parent's hook. Call the parent explicitly if you need both:

var childCmd = &cobra.Command{
    PersistentPreRunE: func(cmd *cobra.Command, args []string) error {
        // call parent's hook first
        if err := rootCmd.PersistentPreRunE(cmd, args); err != nil {
            return err
        }
        // child-specific logic
        return nil
    },
}

Execution stops on first error

If PersistentPreRunE returns an error, cobra stops — RunE and later hooks never run. Use this for fail-fast auth checks.

Args validators

Args validators run before RunE. Cobra prints a clear error message and exits without calling RunE when validation fails.

Built-in validators

cobra.NoArgs                        // fails if any positional args provided
cobra.ArbitraryArgs                 // accepts any number of args (default)
cobra.ExactArgs(n int)              // requires exactly n args
cobra.MinimumNArgs(n int)           // requires at least n args
cobra.MaximumNArgs(n int)           // requires at most n args
cobra.RangeArgs(min, max int)       // requires between min and max args
cobra.OnlyValidArgs                 // all args must be in ValidArgs list
cobra.ExactValidArgs(n int)         // exactly n args, all in ValidArgs

Composing validators with MatchAll

var deleteCmd = &cobra.Command{
    Use:       "delete <resource>",
    Args:      cobra.MatchAll(cobra.ExactArgs(1), cobra.OnlyValidArgs),
    ValidArgs: []string{"pod", "service", "deployment"},
    RunE: func(cmd *cobra.Command, args []string) error {
        return doDelete(args[0])
    },
}

Custom validators

Signature: func(cmd *cobra.Command, args []string) error

func validatePositiveInt(cmd *cobra.Command, args []string) error {
    if len(args) != 1 {
        return fmt.Errorf("requires exactly 1 arg, got %d", len(args))
    }
    n, err := strconv.Atoi(args[0])
    if err != nil || n <= 0 {
        return fmt.Errorf("argument must be a positive integer, got %q", args[0])
    }
    return nil
}

var cmd = &cobra.Command{
    Args: validatePositiveInt,
    RunE: func(cmd *cobra.Command, args []string) error { /* ... */ },
}

Combine custom validators with built-in ones using MatchAll:

Args: cobra.MatchAll(cobra.MinimumNArgs(1), validateAllPositive),

Command registration and ordering

func init() {
    // groups must be registered before AddCommand
    rootCmd.AddGroup(&cobra.Group{ID: "core", Title: "Core Commands:"})
    rootCmd.AddGroup(&cobra.Group{ID: "management", Title: "Management Commands:"})

    serveCmd.GroupID = "core"
    migrateCmd.GroupID = "management"

    rootCmd.AddCommand(serveCmd, migrateCmd, versionCmd)
}

versionCmd has no GroupID — it appears in the default section.

Annotations

Cobra supports arbitrary command annotations for framework-level metadata:

var serveCmd = &cobra.Command{
    Annotations: map[string]string{
        "category": "network",
        "requires-auth": "true",
    },
}

// read in a middleware hook:
if serveCmd.Annotations["requires-auth"] == "true" {
    // enforce auth
}

Hidden and deprecated commands

var internalCmd = &cobra.Command{
    Hidden: true,      // not shown in help, still executable
}

var oldCmd = &cobra.Command{
    Deprecated: "use `newcmd` instead",  // shown in help, prints warning on use
}

cobra.CheckErr

cobra.CheckErr(err) is a convenience function: if err != nil, it prints the error to cmd.ErrOrStderr() and calls os.Exit(1). Use it only in main() where you want a hard exit — not inside RunE where returning the error is preferred.

func main() {
    cobra.CheckErr(rootCmd.Execute())
}

Cobra Shell Completions Reference

Cobra generates shell completion scripts for bash, zsh, fish, and PowerShell automatically. Subcommand names and flag names are completed for free. You add completions for flag values and positional arguments.

Built-in completion command

Cobra registers a completion subcommand automatically:

myapp completion bash   # generate bash script
myapp completion zsh    # generate zsh script
myapp completion fish   # generate fish script
myapp completion powershell

# Install (example for zsh):
myapp completion zsh > "${fpath[1]}/_myapp"

ShellCompDirective

The ShellCompDirective controls shell behavior after your completion function returns:

Combine with bitwise OR: cobra.ShellCompDirectiveNoFileComp | cobra.ShellCompDirectiveNoSpace.

Use ShellCompDirectiveNoFileComp whenever your list is exhaustive — it prevents the shell from appending irrelevant files.

Static arg completions

var getCmd = &cobra.Command{
    Use:       "get <resource>",
    ValidArgs: []string{"pod", "service", "deployment", "configmap"},
    Args:      cobra.OnlyValidArgs,
    RunE: func(cmd *cobra.Command, args []string) error { /* ... */ },
}

Dynamic arg completions

var getCmd = &cobra.Command{
    ValidArgsFunction: func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
        if len(args) > 0 {
            // first arg already provided — no more completions
            return nil, cobra.ShellCompDirectiveNoFileComp
        }
        resources, err := listResources(toComplete)
        if err != nil {
            return nil, cobra.ShellCompDirectiveError
        }
        return resources, cobra.ShellCompDirectiveNoFileComp
    },
}

toComplete is the prefix the user has typed so far — filter your results by it for responsive completions.

Flag value completions

func init() {
    rootCmd.RegisterFlagCompletionFunc("output", func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
        return []string{"json\tJSON output", "yaml\tYAML output", "table\tTable output"}, cobra.ShellCompDirectiveNoFileComp
    })

    rootCmd.RegisterFlagCompletionFunc("namespace", func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
        ns, err := listNamespaces()
        if err != nil {
            return nil, cobra.ShellCompDirectiveError
        }
        return ns, cobra.ShellCompDirectiveNoFileComp
    })
}

Descriptions after \t are shown in zsh and fish menus.

Completion annotations

Mark a flag to complete as a file or directory:

cmd.Flags().String("config", "", "config file")
cmd.MarkFlagFilename("config", "yaml", "yml", "json")  // only those extensions

cmd.Flags().String("dir", "", "output directory")
cmd.MarkFlagDirname("dir")

Testing completions

func TestCompletion(t *testing.T) {
    rootCmd.SetArgs([]string{"__complete", "get", ""})
    buf := new(bytes.Buffer)
    rootCmd.SetOut(buf)
    rootCmd.Execute()
    assert.Contains(t, buf.String(), "pod")
    assert.Contains(t, buf.String(), "service")
}

__complete is cobra's internal completion request verb. Pass the partial args as additional arguments.

Disabling the completion command

rootCmd.CompletionOptions.DisableDefaultCmd = true   // remove the completion subcommand
rootCmd.CompletionOptions.HiddenDefaultCmd = true    // keep it but hide from help

Cobra Flags Reference

Cobra delegates all flag parsing to github.com/spf13/pflag. cobra.Command exposes two *pflag.FlagSets:

• cmd.Flags() — local flags, only available on this command.
• cmd.PersistentFlags() — inherited by all subcommands.

Common flag types

// String
cmd.Flags().String("name", "default", "description")
cmd.Flags().StringP("name", "n", "default", "description")  // with shorthand

// With pointer binding (no Lookup needed later)
var name string
cmd.Flags().StringVar(&name, "name", "default", "description")
cmd.Flags().StringVarP(&name, "name", "n", "default", "description")

// Other types follow the same pattern:
cmd.Flags().Int / IntVar / IntVarP
cmd.Flags().Bool / BoolVar / BoolVarP
cmd.Flags().Float64 / Float64Var
cmd.Flags().Duration / DurationVar       // parses "1h30m", "500ms"
cmd.Flags().StringSlice / StringSliceVar // comma-separated or repeated flags
cmd.Flags().StringArray / StringArrayVar // repeated flags only (no comma splitting)
cmd.Flags().IntSlice / IntSliceVar
cmd.Flags().StringToString                // --label key=value --label k2=v2

StringSlice vs StringArray

Use StringArray when values may legitimately contain commas.

Flag constraints

// Fail if flag not provided
cmd.MarkFlagRequired("output")

// Fail if both provided
cmd.MarkFlagsMutuallyExclusive("json", "yaml", "table")

// Fail if none provided
cmd.MarkFlagsOneRequired("file", "stdin")

// Require flag only if another flag is set
cmd.MarkFlagsMutuallyExclusive("tls", "no-tls")

Persistent flag patterns

func init() {
    // global flags on root
    rootCmd.PersistentFlags().StringVar(&cfgFile, "config", "", "config file (default: $HOME/.myapp.yaml)")
    rootCmd.PersistentFlags().StringVar(&logLevel, "log-level", "info", "log level (debug, info, warn, error)")

    // bind to viper immediately after defining
    viper.BindPFlag("config", rootCmd.PersistentFlags().Lookup("config"))
    viper.BindPFlag("log-level", rootCmd.PersistentFlags().Lookup("log-level"))
}

Custom flag value types

Implement pflag.Value to parse arbitrary types:

type enumValue struct {
    val     string
    allowed []string
}

func (e *enumValue) String() string { return e.val }
func (e *enumValue) Type() string   { return "enum" }
func (e *enumValue) Set(s string) error {
    for _, a := range e.allowed {
        if s == a {
            e.val = s
            return nil
        }
    }
    return fmt.Errorf("must be one of %v", e.allowed)
}

var outputFmt = &enumValue{val: "table", allowed: []string{"table", "json", "yaml"}}
cmd.Flags().Var(outputFmt, "output", "output format (table, json, yaml)")

Flag groups (required together)

Mark a set of flags that must all be provided if any one of them is provided:

cmd.Flags().String("tls-cert", "", "TLS certificate file")
cmd.Flags().String("tls-key", "", "TLS key file")
cmd.MarkFlagsRequiredTogether("tls-cert", "tls-key")

Accessing flag values

Prefer pointer binding (StringVar, IntVar, etc.) for type-safe access. When you need the flag post-parse:

port, err := cmd.Flags().GetInt("port")
name, err := cmd.Flags().GetString("name")
tags, err := cmd.Flags().GetStringSlice("tags")

Flag changed vs default

if cmd.Flags().Changed("port") {
    // user explicitly provided --port
    // useful when distinguishing "user set 0" from "flag not provided"
}

Changed() is also how viper knows which flags are explicit overrides — it only promotes a flag to the highest precedence layer if Changed() is true.

Cobra Documentation and Scaffolding Generators

Doc generation

Cobra can generate documentation from your command tree in multiple formats. Import the cobra/doc sub-package:

go get github.com/spf13/cobra/doc

Markdown

import "github.com/spf13/cobra/doc"

err := doc.GenMarkdownTree(rootCmd, "/tmp/docs/")
// generates /tmp/docs/myapp.md, /tmp/docs/myapp_serve.md, etc.

// Single command
var buf bytes.Buffer
doc.GenMarkdown(rootCmd, &buf)

Man pages

header := &doc.GenManHeader{
    Title:   "MYAPP",
    Section: "1",
    Date:    &time.Time{},
    Source:  "myapp v1.0.0",
    Manual:  "User Commands",
}
err := doc.GenManTree(rootCmd, header, "/usr/local/share/man/man1/")

YAML

err := doc.GenYamlTree(rootCmd, "/tmp/docs/")

RST (reStructuredText)

err := doc.GenReSTTree(rootCmd, "/tmp/docs/")

cobra-cli scaffolder

cobra-cli generates command files and wires them into your project:

go get -tool github.com/spf13/cobra-cli@latest

# Initialize a new cobra project
go tool cobra-cli init myapp

# Add a subcommand
go tool cobra-cli add serve
go tool cobra-cli add migrate

# Add with a parent other than root
cobra-cli add list --parent serve

Generated files follow the standard pattern:

// cmd/serve.go
var serveCmd = &cobra.Command{
    Use:   "serve",
    Short: "A brief description of your command",
    RunE: func(cmd *cobra.Command, args []string) error {
        return nil
    },
}

func init() {
    rootCmd.AddCommand(serveCmd)
}

cobra-cli is optional — many teams write command files by hand following the same pattern.

Help and usage template customization

Override the default help template:

rootCmd.SetHelpTemplate(`
Usage:  {{.UseLine}}
{{if .HasAvailableSubCommands}}
Commands:
{{range .Commands}}{{if .IsAvailableCommand}}  {{rpad .Name .NamePadding }} {{.Short}}
{{end}}{{end}}{{end}}
Flags:
{{.LocalFlags.FlagUsages | trimRightSpace}}
`)

Override the usage function entirely:

rootCmd.SetUsageFunc(func(cmd *cobra.Command) error {
    fmt.Fprintf(cmd.OutOrStdout(), "Custom usage for %s\n", cmd.Name())
    return nil
})

Common template functions available: rpad, trimRightSpace, gt, eq.

Testing Cobra Commands

Basic test pattern

func TestServeCmd(t *testing.T) {
    stdout := new(bytes.Buffer)
    stderr := new(bytes.Buffer)

    rootCmd.SetOut(stdout)
    rootCmd.SetErr(stderr)
    rootCmd.SetArgs([]string{"serve", "--port", "9090", "--dry-run"})

    err := rootCmd.Execute()
    require.NoError(t, err)
    assert.Contains(t, stdout.String(), "listening on :9090")
    assert.Empty(t, stderr.String())
}

Isolation between tests

Cobra accumulates flag state across Execute() calls on the same command instance. Tests must be isolated.

Option 1: Re-create the command tree per test (recommended for unit tests)

func newRootCmd() *cobra.Command {
    root := &cobra.Command{Use: "myapp", SilenceUsage: true, SilenceErrors: true}
    root.AddCommand(newServeCmd())
    return root
}

func TestServeCmd(t *testing.T) {
    root := newRootCmd()
    root.SetArgs([]string{"serve", "--port", "9090"})
    err := root.Execute()
    require.NoError(t, err)
}

Option 2: Reset flags between tests

func TestWithReset(t *testing.T) {
    t.Cleanup(func() {
        rootCmd.ResetFlags()
        // re-define flags if needed
    })
}

Re-creating is safer — ResetFlags only clears the flag set, not subcommand state.

Testing commands that write output

Commands must use cmd.OutOrStdout() / cmd.ErrOrStderr() instead of os.Stdout / os.Stderr for this to work.

// In command handler:
func runServe(cmd *cobra.Command, args []string) error {
    fmt.Fprintln(cmd.OutOrStdout(), "Server started")
    fmt.Fprintln(cmd.ErrOrStderr(), "Debug: listening on port 8080")
    return nil
}

// In test:
buf := new(bytes.Buffer)
rootCmd.SetOut(buf)
rootCmd.Execute()
assert.Contains(t, buf.String(), "Server started")

Golden file tests

For commands with structured or lengthy output, use golden files:

func TestOutputFormat(t *testing.T) {
    buf := new(bytes.Buffer)
    rootCmd.SetOut(buf)
    rootCmd.SetArgs([]string{"list", "--output", "json"})
    require.NoError(t, rootCmd.Execute())

    golden := "testdata/list-json.golden"
    if *update {  // -update flag
        os.WriteFile(golden, buf.Bytes(), 0644)
    }
    want, _ := os.ReadFile(golden)
    assert.Equal(t, string(want), buf.String())
}

Run with -update to regenerate golden files after intentional output changes.

Testing error paths

func TestInvalidArgs(t *testing.T) {
    stderr := new(bytes.Buffer)
    rootCmd.SetErr(stderr)
    rootCmd.SetArgs([]string{"delete"})  // missing required arg

    err := rootCmd.Execute()
    assert.Error(t, err)
    assert.Contains(t, err.Error(), "accepts 1 arg")
}

Table-driven command tests

tests := []struct {
    name    string
    args    []string
    wantOut string
    wantErr bool
}{
    {"no flags", []string{"serve"}, "listening on :8080", false},
    {"custom port", []string{"serve", "--port", "9090"}, "listening on :9090", false},
    {"invalid port", []string{"serve", "--port", "abc"}, "", true},
}

for _, tt := range tests {
    t.Run(tt.name, func(t *testing.T) {
        root := newRootCmd()  // fresh command tree per test
        buf := new(bytes.Buffer)
        root.SetOut(buf)
        root.SetArgs(tt.args)
        err := root.Execute()
        if tt.wantErr {
            assert.Error(t, err)
        } else {
            require.NoError(t, err)
            assert.Contains(t, buf.String(), tt.wantOut)
        }
    })
}

Testing completions

func TestCompletion(t *testing.T) {
    root := newRootCmd()
    buf := new(bytes.Buffer)
    root.SetOut(buf)
    root.SetArgs([]string{"__complete", "delete", ""})
    root.Execute()

    assert.Contains(t, buf.String(), "pod")
    assert.Contains(t, buf.String(), "service")
}