golang-cli-cobra-viper

Go CLI Development with Cobra & Viper

Overview

Cobra and Viper are the industry-standard libraries for building production-quality CLIs in Go. Cobra provides command structure and argument parsing, while Viper manages configuration from multiple sources with clear precedence rules.

Key Features:

• 🎯 Cobra Commands: POSIX-compliant CLI with subcommands (app verb noun --flag)
• ⚙️ Viper Config: Unified configuration from flags, env vars, and config files
• 🔄 Integration: Seamless Cobra + Viper plumbing patterns
• 🐚 Shell Completion: Auto-generated completions for bash, zsh, fish, PowerShell
• ✅ Production Ready: Battle-tested by kubectl, docker, gh, hugo

Used By: Kubernetes (kubectl), Docker CLI, GitHub CLI (gh), Hugo, Helm, and 100+ major projects

When to Use This Skill

Activate this skill when:

• Building multi-command CLI tools with subcommands
• Creating developer tools, project generators, or scaffolding utilities
• Implementing admin CLIs for services or infrastructure
• Requiring flexible configuration (flags > env vars > config files > defaults)
• Adding shell completion for frequently-used CLIs
• Building DevOps automation tools or deployment scripts

Cobra Framework

Command Structure Pattern

Cobra follows the APPNAME VERB NOUN --FLAG pattern popularized by git and kubectl.

// cmd/root.go
package cmd

import (
    "fmt"
    "os"

    "github.com/spf13/cobra"
    "github.com/spf13/viper"
)

var cfgFile string

var rootCmd = &cobra.Command{
    Use:   "myapp",
    Short: "A powerful CLI tool for developers",
    Long: `MyApp is a CLI tool that demonstrates best practices
for building production-quality command-line applications.

Complete documentation is available at https://myapp.example.com`,
}

func Execute() {
    if err := rootCmd.Execute(); err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }
}

func init() {
    cobra.OnInitialize(initConfig)

    // Persistent flags (available to all subcommands)
    rootCmd.PersistentFlags().StringVar(&cfgFile, "config", "", "config file (default is $HOME/.myapp.yaml)")
    rootCmd.PersistentFlags().Bool("verbose", false, "verbose output")

    // Bind persistent flags to viper
    viper.BindPFlag("config", rootCmd.PersistentFlags().Lookup("config"))
    viper.BindPFlag("verbose", rootCmd.PersistentFlags().Lookup("verbose"))
}

func initConfig() {
    if cfgFile != "" {
        viper.SetConfigFile(cfgFile)
    } else {
        home, err := os.UserHomeDir()
        if err != nil {
            fmt.Fprintln(os.Stderr, err)
            os.Exit(1)
        }

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

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

    if err := viper.ReadInConfig(); err == nil {
        if viper.GetBool("verbose") {
            fmt.Println("Using config file:", viper.ConfigFileUsed())
        }
    }
}