cobra-viper

name	cobra-viper
description	Expert skill for building CLI applications with Cobra and Viper, authored by spf13 — the original creator of both libraries. Covers command-first architecture, decoupled business logic, configuration management, environment variable binding, context-aware commands, and in-memory CLI testing. Use when building or reviewing any Go CLI application that uses Cobra and/or Viper.

Go CLI Architecture: Cobra & Viper

Idiomatic patterns and best practices for building robust, configuration-driven command-line interfaces using Cobra and Viper.

When to Activate

• Writing a new CLI application in Go
• Adding commands, subcommands, or flags to an existing Cobra application
• Integrating Viper for configuration file, environment variable, or flag management
• Reviewing or refactoring CLI code that uses Cobra and/or Viper
• Designing the command structure or configuration schema for a CLI tool
• Testing CLI commands

Core Philosophy

The Command-First Architecture

Treat your application binary as a router for commands. The CLI framework (Cobra) should solely handle flags, arguments, and routing. Your core business logic should remain completely unaware of the CLI layer, making it highly testable and reusable.

Unified Configuration

Configuration should be environment-aware and unified. Viper acts as the single source of truth, merging defaults, config files, environment variables, and command-line flags into a cohesive state before passing it to the application logic.

CLI Package Organization

Anti-Pattern: Hiding all your commands and core logic deep inside an internal/ directory tree, or shoving everything into main.go.

Discoverable, Flat Structures

Command routing and business logic should live in standard, logically named packages. The cmd/ package handles the CLI surface area, while other top-level packages handle the domain logic.

mycli/
├── main.go               # Minimal entry point: strictly calls cmd.Execute()
├── cmd/                  # The Cobra routing layer
│   ├── root.go           # Base command, global flags, and Viper setup
│   ├── serve.go          # The 'serve' subcommand
│   └── build.go          # The 'build' subcommand
├── engine/               # Core business logic (name based on your domain)
│   ├── server.go
│   └── compiler.go
├── go.mod
└── go.sum

main.go is intentionally minimal:

package main

import "github.com/spf13/myapp/cmd"

func main() {
    cmd.Execute()
}

Decouple Commands from Execution

The files in your cmd/ package should do exactly three things:

1. Define the Cobra command, its aliases, and help text.
2. Bind Viper flags and configuration for that specific command.
3. Call a function in your core logic package (e.g., engine), passing in the parsed configuration and the command context.

Your core logic (the engine package) should have absolutely zero imports from github.com/spf13/cobra or github.com/spf13/viper.

Cobra Best Practices

1. Use RunE for Native Error Handling

Avoid Run. If a command fails, use RunE to return the error up the execution chain. This allows the root command to handle errors gracefully and consistently, rather than relying on scattered log.Fatal calls that bypass defer statements.

// Idiomatic: Returning errors to be handled by the executor
var serverCmd = &cobra.Command{
    Use:   "server",
    Short: "Starts the primary application server",
    RunE: func(cmd *cobra.Command, args []string) error {
        server := engine.NewServer()
        if err := server.Start(); err != nil {
            return fmt.Errorf("server failure: %w", err)
        }
        return nil
    },
}

2. Silence Usage on Application Errors

By default, Cobra prints the full help text whenever an error is returned. This is confusing if the error was a runtime failure (like a network timeout) rather than a syntax error.

// In cmd/root.go
rootCmd := &cobra.Command{
    Use:           "mycli",
    SilenceUsage:  true, // Don't print help on runtime errors
    SilenceErrors: true, // Allow main.go to handle the error printing
}

3. Context-Aware Commands

Modern Go relies heavily on context.Context for cancellation and timeouts. Pass the Cobra command's context directly to your business logic. This context automatically listens for OS termination signals (like SIGINT or Ctrl+C).

RunE: func(cmd *cobra.Command, args []string) error {
    // Passes context down for graceful shutdown
    return engine.Process(cmd.Context(), args)
}

4. PersistentPreRunE for Shared Setup

Use PersistentPreRunE on the root command to run setup (logging, config validation) after flags are parsed but before any subcommand runs:

rootCmd = &cobra.Command{
    Use:               "myapp",
    PersistentPreRunE: func(cmd *cobra.Command, args []string) error {
        // Safe to read viper values here — flags + config + env are all merged
        return setupLogger(viper.GetString("log-level"))
    },
}

Cobra runs PersistentPreRunE for every subcommand automatically. If a subcommand also defines PersistentPreRunE, you must call the parent's explicitly — Cobra does not chain them automatically.

5. Flag Design

// Persistent flags — inherited by all subcommands
rootCmd.PersistentFlags().String("config", "", "config file path")
rootCmd.PersistentFlags().Bool("verbose", false, "enable verbose output")

// Local flags — only for this command
serveCmd.Flags().String("addr", ":8080", "listen address")

// Required flags — Cobra validates before RunE is called
serveCmd.Flags().String("name", "", "required name")
serveCmd.MarkFlagRequired("name")

// Mutually exclusive flags
serveCmd.MarkFlagsMutuallyExclusive("json", "yaml")

• Use PersistentFlags for cross-cutting concerns (config, verbosity, output format).
• Use Flags for command-specific options.
• Always provide short flags (-v, -o) for common options.

6. Shell Completion

Cobra generates shell completion for free:

// Custom completions for a flag
serveCmd.RegisterFlagCompletionFunc("output", func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
    return []string{"json", "yaml", "table"}, cobra.ShellCompDirectiveNoFileComp
})

myapp completion bash        > /etc/bash_completion.d/myapp
myapp completion zsh         > "${fpath[1]}/_myapp"
myapp completion fish        > ~/.config/fish/completions/myapp.fish
myapp completion powershell  | Out-File -Encoding utf8 "$PROFILE\myapp.ps1"

Viper Configuration Patterns

1. Unmarshal into Typed Structs

Anti-Pattern: Calling viper.GetString("database.host") deep inside your business logic. This tightly couples your domain to Viper and scatters magic strings throughout your codebase.

Instead, define a strongly-typed configuration struct, unmarshal Viper's state into it at the routing layer (cmd/), and pass that struct down.

type Config struct {
    Host string `mapstructure:"host"`
    Port int    `mapstructure:"port"`
}

func initConfig() (*Config, error) {
    var cfg Config
    if err := viper.Unmarshal(&cfg); err != nil {
        return nil, fmt.Errorf("unable to decode config: %w", err)
    }
    return &cfg, nil
}

2. The Binding Hierarchy

Viper seamlessly merges configuration sources in this order (highest → lowest priority):

1. Explicit Set() calls in code
2. Flags (bound via BindPFlag)
3. Environment variables (MYCLI_PORT)
4. Config file (~/.mycli.yaml, ./.mycli.yaml)
5. Defaults (viper.SetDefault)

You must explicitly bind each source. Binding environment variables is crucial for containerized deployments:

func init() {
    // 1. Define the flag
    rootCmd.PersistentFlags().Int("port", 8080, "Server port")

    // 2. Bind the flag to Viper
    viper.BindPFlag("port", rootCmd.PersistentFlags().Lookup("port"))

    // 3. Enable environment variables (e.g., MYCLI_PORT)
    viper.SetEnvPrefix("mycli")
    viper.AutomaticEnv()

    // 4. Set fallback defaults
    viper.SetDefault("port", 8080)
}

3. Environment Variable Mapping

With viper.SetEnvPrefix("MYAPP") and viper.AutomaticEnv():

Viper key	Environment variable
log-level	MYAPP_LOG_LEVEL
serve.addr	MYAPP_SERVE_ADDR
db.password	MYAPP_DB_PASSWORD

Nested keys with dots or dashes require a replacer to map correctly to env var names:

viper.SetEnvKeyReplacer(strings.NewReplacer("-", "_", ".", "_"))

4. Config File Setup (cmd/root.go)

func initConfig() {
    if cfgFile != "" {
        viper.SetConfigFile(cfgFile)
    } else {
        home, err := os.UserHomeDir()
        cobra.CheckErr(err)

        viper.AddConfigPath(home)
        viper.AddConfigPath(".")
        viper.SetConfigType("yaml")
        viper.SetConfigName(".myapp")
    }

    viper.SetEnvPrefix("MYAPP")
    viper.AutomaticEnv()

    if err := viper.ReadInConfig(); err != nil {
        if _, ok := err.(viper.ConfigFileNotFoundError); !ok {
            fmt.Fprintf(os.Stderr, "Error reading config: %v\n", err)
            os.Exit(1)
        }
    }
}

Use YAML as the default format — it's readable and supports nesting:

# ~/.myapp.yaml
log-level: debug

serve:
  addr: ":9090"
  port: 9090

db:
  host: localhost
  port: 5432
  name: myapp

Version Command

// Set at build time via -ldflags
var (
    version = "dev"
    commit  = "none"
    date    = "unknown"
)

var versionCmd = &cobra.Command{
    Use:   "version",
    Short: "Print version information",
    Run: func(cmd *cobra.Command, args []string) {
        fmt.Printf("myapp %s (commit: %s, built: %s)\n", version, commit, date)
    },
}

go build -ldflags="-X 'github.com/spf13/myapp/cmd.version=1.2.3' \
                   -X 'github.com/spf13/myapp/cmd.commit=$(git rev-parse --short HEAD)' \
                   -X 'github.com/spf13/myapp/cmd.date=$(date -u +%Y-%m-%dT%H:%M:%SZ)'"

Testing CLI Commands

Anti-Pattern: Testing CLI commands by compiling the binary and using os/exec. This is extremely slow, brittle, and makes it difficult to measure test coverage.

Because Cobra commands are just Go structs, you can test them directly in memory by redirecting their inputs, outputs, and arguments.

// Idiomatic: In-memory CLI testing
func TestServerCommand(t *testing.T) {
    // Reset viper state between tests — Viper is a singleton; test pollution is real
    viper.Reset()

    buf := new(bytes.Buffer)
    cmd := serverCmd
    cmd.SetOut(buf)
    cmd.SetErr(buf)

    // Pass arguments exactly as a user would on the command line
    cmd.SetArgs([]string{"--port", "9090"})

    if err := cmd.Execute(); err != nil {
        t.Fatalf("unexpected error: %v", err)
    }

    if !strings.Contains(buf.String(), "Starting server on 9090") {
        t.Errorf("expected output to contain port 9090, got: %s", buf.String())
    }
}

• Always viper.Reset() between tests — Viper global state bleeds across test cases.
• Use cmd.SetOut / cmd.SetErr to capture output without monkey-patching os.Stdout.
• Never test via compiled binary + os/exec; use in-memory execution for speed and coverage.

Common Mistakes

• Accessing Viper before initConfig: Viper values are empty until cobra.OnInitialize callbacks have run. Don't read Viper in init() functions or var blocks.
• Forgetting BindPFlag: Flags are not automatically visible to Viper. You must bind them explicitly.
• Missing SetEnvKeyReplacer: Nested keys with dots (e.g., serve.addr) won't match MYAPP_SERVE_ADDR without a replacer.
• Cobra/Viper imports in business logic: The engine package must never import Cobra or Viper. Pass typed config structs instead.
• Mutating global command state in tests: rootCmd is a package-level variable. Tests that run in parallel will race. Use factory functions for fully testable CLIs.
• Over-nesting subcommands: Two levels (app command subcommand) is usually the right depth. Three or more levels confuse users.