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.

Commands Are Built, Not Declared

Construct the command tree with factory functions (NewRootCmd()), not package-level var declarations. Globals make commands untestable (state leaks between test runs) and unusable as a library. The only global in a well-built CLI is main.go calling the factory.

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           # Root command factory, global flags, 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 (
    "os"

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

func main() {
    if err := cmd.Execute(); err != nil {
        os.Exit(1)
    }
}

The Factory Pattern (cmd/root.go)

Each command file exports a constructor. The root factory creates its own Viper instance and wires everything together — no package-level state:

func Execute() error {
    return NewRootCmd().Execute()
}

func NewRootCmd() *cobra.Command {
    v := viper.New()

    rootCmd := &cobra.Command{
        Use:           "mycli",
        Short:         "A brief description",
        SilenceUsage:  true,
        SilenceErrors: true,
        PersistentPreRunE: func(cmd *cobra.Command, args []string) error {
            return initConfig(v, cmd)
        },
    }

    rootCmd.PersistentFlags().String("config", "", "config file path")
    rootCmd.PersistentFlags().String("log-level", "info", "log level")

    rootCmd.AddCommand(NewServeCmd(v))
    rootCmd.AddCommand(NewBuildCmd(v))
    return rootCmd
}

When globals are acceptable: a small, single-purpose tool that will never be tested in-process or embedded. The moment you write a test, switch to factories.

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
func NewServeCmd(v *viper.Viper) *cobra.Command {
    cmd := &cobra.Command{
        Use:   "serve",
        Short: "Starts the primary application server",
        RunE: func(cmd *cobra.Command, args []string) error {
            var cfg engine.Config
            if err := v.Unmarshal(&cfg); err != nil {
                return fmt.Errorf("decoding config: %w", err)
            }
            return engine.Serve(cmd.Context(), cfg)
        },
    }
    cmd.Flags().String("addr", ":8080", "listen address")
    return cmd
}

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. Set SilenceUsage: true and SilenceErrors: true on the root (as shown above) and let main.go print the error once.

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:

RunE: func(cmd *cobra.Command, args []string) error {
    return engine.Process(cmd.Context(), args)
}

To make that context respect Ctrl+C, wire signal handling in main.go:

ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()
err := cmd.NewRootCmd().ExecuteContext(ctx)

4. Validate Positional Arguments with Args

Never validate argument counts inside RunE — Cobra does it for you, before RunE runs, with correct usage errors:

cmd := &cobra.Command{
    Use:  "build [target]",
    Args: cobra.ExactArgs(1),
    // Also: cobra.NoArgs, cobra.MinimumNArgs(n), cobra.MaximumNArgs(n),
    // cobra.RangeArgs(min, max), cobra.OnlyValidArgs (with ValidArgs set)
    // Combine: cobra.MatchAll(cobra.ExactArgs(1), cobra.OnlyValidArgs)
}

5. PersistentPreRunE for Shared Setup

Use PersistentPreRunE on the root command to run setup (config loading, logging) after flags are parsed but before any subcommand runs. Cobra runs it for every subcommand automatically.

Gotcha: if a subcommand also defines PersistentPreRunE, it replaces the parent's — Cobra does not chain them by default. Either call the parent's explicitly, or opt into chaining globally with cobra.EnableTraverseRunHooks = true (Cobra 1.8+).

6. Flag Design

// Persistent flags — inherited by all subcommands
rootCmd.PersistentFlags().String("config", "", "config file path")
rootCmd.PersistentFlags().BoolP("verbose", "v", 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")

// Flag relationships (Cobra 1.8+ for OneRequired)
serveCmd.MarkFlagsMutuallyExclusive("json", "yaml")
serveCmd.MarkFlagsRequiredTogether("user", "password")
serveCmd.MarkFlagsOneRequired("file", "url")

• 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.

7. Group Commands in Help Output (Cobra 1.6+)

For CLIs with many subcommands, group them so --help reads as a story, not a dump:

rootCmd.AddGroup(&cobra.Group{ID: "core", Title: "Core Commands:"})
rootCmd.AddGroup(&cobra.Group{ID: "admin", Title: "Admin Commands:"})
serveCmd.GroupID = "core"
migrateCmd.GroupID = "admin"

8. Shell Completion

Cobra generates shell completion for free. Add dynamic completion for both flags and positional arguments:

// Flag value completion
serveCmd.RegisterFlagCompletionFunc("output", func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
    return []string{"json", "yaml", "table"}, cobra.ShellCompDirectiveNoFileComp
})

// Positional argument completion
buildCmd.ValidArgsFunction = func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
    return listTargets(), 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"

9. Print Through the Command, Not fmt.Printf

Inside any command, write to cmd.OutOrStdout() / cmd.ErrOrStderr() (or use cmd.Println). Direct fmt.Printf bypasses SetOut/SetErr, making output impossible to capture in tests.

Viper Configuration Patterns

1. Prefer a Viper Instance over the Global Singleton

viper.New() gives you an instance you can inject, isolate in tests, and run concurrently. The package-level viper.Get* singleton exists for convenience in small tools — the same trade-off as pflag's default FlagSet. For anything with tests or multiple commands, pass *viper.Viper explicitly (as the factory examples above do).

2. Unmarshal into Typed Structs

Anti-Pattern: Calling v.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"`
}

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

3. The Binding Hierarchy

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

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

You must explicitly bind each source. Bind a whole flag set at once rather than flag-by-flag:

// In PersistentPreRunE — after flags are parsed, before RunE
if err := v.BindPFlags(cmd.Flags()); err != nil {
    return err
}

Binding in PersistentPreRunE (rather than init()) also avoids the classic collision where two subcommands bind different flags to the same Viper key and the last init() silently wins.

4. Environment Variable Mapping

With v.SetEnvPrefix("MYAPP") and v.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:

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

Critical gotcha — AutomaticEnv + Unmarshal: Unmarshal only walks keys Viper already knows about (from defaults, config file, or explicit binds). A value set only via environment variable is invisible to Unmarshal unless the key was registered. The fix: call v.SetDefault for every key in your config struct, or v.BindEnv each key explicitly. This is the most common "my env var is ignored" bug in Viper applications.

5. Config File Setup

func initConfig(v *viper.Viper, cmd *cobra.Command) error {
    if cfgFile, _ := cmd.Flags().GetString("config"); cfgFile != "" {
        v.SetConfigFile(cfgFile)
    } else {
        home, err := os.UserHomeDir()
        if err != nil {
            return err
        }
        v.AddConfigPath(home)
        v.AddConfigPath(".")
        v.SetConfigType("yaml")
        v.SetConfigName(".myapp")
    }

    v.SetEnvPrefix("MYAPP")
    v.SetEnvKeyReplacer(strings.NewReplacer("-", "_", ".", "_"))
    v.AutomaticEnv()

    if err := v.ReadInConfig(); err != nil {
        var notFound viper.ConfigFileNotFoundError
        if !errors.As(err, &notFound) {
            return fmt.Errorf("reading config: %w", err)
        }
        // Not found is fine — defaults, env, and flags still apply
    }

    return v.BindPFlags(cmd.Flags())
}

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 Handling

Cobra has a built-in version mechanism — prefer it over a hand-rolled subcommand:

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

rootCmd := &cobra.Command{
    Use:     "myapp",
    Version: fmt.Sprintf("%s (commit: %s, built: %s)", version, commit, date),
}
// `myapp --version` now works for free.
// Customize the output with rootCmd.SetVersionTemplate if needed.

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)'"

Add a version subcommand only if you need structured output (version --json) — and print via cmd.OutOrStdout(), never fmt.Printf.

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.

Second anti-pattern: executing a package-level subcommand directly. cmd.Execute() always executes from the root of the command tree, and mutating a global command leaks flag state between tests. This is exactly why commands are built by factories.

// Idiomatic: In-memory CLI testing via the factory
func TestServeCommand(t *testing.T) {
    tests := []struct {
        name    string
        args    []string
        want    string
        wantErr bool
    }{
        {"default port", []string{"serve"}, "listening on :8080", false},
        {"custom port", []string{"serve", "--addr", ":9090"}, "listening on :9090", false},
        {"bad flag", []string{"serve", "--bogus"}, "", true},
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            buf := new(bytes.Buffer)

            root := cmd.NewRootCmd() // fresh tree + fresh Viper every test
            root.SetOut(buf)
            root.SetErr(buf)
            root.SetArgs(tt.args) // full CLI invocation, exactly as a user types it

            err := root.ExecuteContext(t.Context())
            if (err != nil) != tt.wantErr {
                t.Fatalf("Execute() error = %v, wantErr %v", err, tt.wantErr)
            }
            if !strings.Contains(buf.String(), tt.want) {
                t.Errorf("output = %q, want substring %q", buf.String(), tt.want)
            }
        })
    }
}

• Always execute through the root with SetArgs containing the subcommand name — that's the real code path users hit, including flag parsing and PersistentPreRunE.
• A fresh NewRootCmd() per test case means no shared state, no viper.Reset(), and tests can run in parallel.
• If you're stuck with the global Viper singleton, call viper.Reset() between tests — its state bleeds across test cases.
• Use SetOut / SetErr to capture output — which only works if commands print via cmd.OutOrStdout().
• Set config env vars with t.Setenv — it restores them automatically and blocks accidental t.Parallel misuse.

Common Mistakes

• Executing a subcommand variable directly in tests: serverCmd.Execute() runs the whole tree from the root, not just that command. Build fresh trees with a factory and drive them through SetArgs.
• Env-only values missing after Unmarshal: AutomaticEnv doesn't register keys. SetDefault or BindEnv every key in your config struct (see the gotcha above).
• Accessing Viper before config is loaded: values are empty until your setup has run (PersistentPreRunE or cobra.OnInitialize). Don't read Viper in init() functions or var blocks.
• Forgetting BindPFlags: flags are not automatically visible to Viper. Bind the command's flag set 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.
• fmt.Printf inside commands: bypasses SetOut, breaking test capture. Use cmd.OutOrStdout().
• Over-nesting subcommands: two levels (app command subcommand) is usually the right depth. Three or more levels confuse users.