Go CLI开发教程：使用Cobra和Viper构建生产级命令行工具

golang-cli-cobra-viper by bobmatnyc/claude-mpm-skills

152 周安装量

27 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/bobmatnyc/claude-mpm-skills --skill golang-cli-cobra-viper

Go 开发运维命令行工具

🇨🇳中文介绍

使用 Cobra 和 Viper 进行 Go CLI 开发

概述

Cobra 和 Viper 是 Go 语言中用于构建生产级 CLI 的行业标准库。Cobra 提供命令结构和参数解析，而 Viper 则通过清晰的优先级规则管理来自多个源的配置。

主要特性：

🎯 Cobra 命令 ：符合 POSIX 标准的 CLI，支持子命令（app verb noun --flag）
⚙️ Viper 配置 ：统一来自标志、环境变量和配置文件的配置
🔄 集成：无缝的 Cobra + Viper 连接模式
🐚 Shell 补全 ：为 bash、zsh、fish、PowerShell 自动生成的补全功能
✅ 生产就绪 ：经过 kubectl、docker、gh、hugo 等项目的实战检验

使用者 ：Kubernetes (kubectl)、Docker CLI、GitHub CLI (gh)、Hugo、Helm 以及 100 多个主要项目

何时使用此技能

在以下情况下激活此技能：

构建带有子命令的多命令 CLI 工具时
创建开发者工具、项目生成器或脚手架实用程序时
为服务或基础设施实现管理 CLI 时
需要灵活的配置（标志 > 环境变量 > 配置文件 > 默认值）时
为常用 CLI 添加 shell 补全功能时
构建 DevOps 自动化工具或部署脚本时

Cobra 框架

命令结构模式

Cobra 遵循由 git 和 kubectl 推广的 APPNAME VERB NOUN --FLAG 模式。

// 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: "一个面向开发者的强大 CLI 工具",
    Long: `MyApp 是一个 CLI 工具，展示了构建生产级命令行应用程序的最佳实践。

完整文档请访问 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)

    // 持久标志（对所有子命令可用）
    rootCmd.PersistentFlags().StringVar(&cfgFile, "config", "", "配置文件（默认为 $HOME/.myapp.yaml）")
    rootCmd.PersistentFlags().Bool("verbose", false, "详细输出")

    // 将持久标志绑定到 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("使用配置文件：", viper.ConfigFileUsed())
        }
    }
}

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

带参数的子命令

// cmd/deploy.go
package cmd

import (
    "fmt"

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

var deployCmd = &cobra.Command{
    Use:   "deploy [environment]",
    Short: "将应用程序部署到指定环境",
    Long: `将应用程序部署到指定环境。
支持：dev、staging、production`,
    Args: cobra.ExactArgs(1),
    ValidArgs: []string{"dev", "staging", "production"},
    PreRunE: func(cmd *cobra.Command, args []string) error {
        // 验证逻辑在 RunE 之前运行
        env := args[0]
        if env == "production" && !viper.GetBool("force") {
            return fmt.Errorf("生产环境部署需要 --force 标志")
        }
        return nil
    },
    RunE: func(cmd *cobra.Command, args []string) error {
        env := args[0]
        region := viper.GetString("region")
        force := viper.GetBool("force")

        fmt.Printf("正在部署到 %s 区域 %s (force=%v)\n", env, region, force)

        // 实际的部署逻辑
        return deploy(env, region, force)
    },
    PostRunE: func(cmd *cobra.Command, args []string) error {
        // 清理或通知
        fmt.Println("部署完成")
        return nil
    },
}

func init() {
    rootCmd.AddCommand(deployCmd)

    // 本地标志（仅对此命令可用）
    deployCmd.Flags().StringP("region", "r", "us-east-1", "AWS 区域")
    deployCmd.Flags().BoolP("force", "f", false, "无需确认强制部署")

    // 将标志绑定到 viper
    viper.BindPFlag("region", deployCmd.Flags().Lookup("region"))
    viper.BindPFlag("force", deployCmd.Flags().Lookup("force"))
}

func deploy(env, region string, force bool) error {
    // 实现
    return nil
}

持久标志与本地标志

// 持久标志：对命令及其所有子命令可用
rootCmd.PersistentFlags().String("config", "", "配置文件路径")
rootCmd.PersistentFlags().Bool("verbose", false, "详细输出")

// 本地标志：仅对此特定命令可用
deployCmd.Flags().String("region", "us-east-1", "部署区域")
deployCmd.Flags().Bool("force", false, "强制部署")

// 必需标志
deployCmd.MarkFlagRequired("region")

// 标志依赖关系
deployCmd.MarkFlagsRequiredTogether("username", "password")
deployCmd.MarkFlagsMutuallyExclusive("json", "yaml")

PreRun/PostRun 钩子

Cobra 为设置和清理提供执行钩子：

var serverCmd = &cobra.Command{
    Use:   "server",
    Short: "启动 API 服务器",

    // 执行顺序（均为可选）：
    PersistentPreRunE: func(cmd *cobra.Command, args []string) error {
        // 在 PreRunE 之前运行，被子命令继承
        return setupLogging()
    },
    PreRunE: func(cmd *cobra.Command, args []string) error {
        // 在 RunE 之前进行验证和设置
        return validateConfig()
    },
    RunE: func(cmd *cobra.Command, args []string) error {
        // 主要命令逻辑
        return startServer()
    },
    PostRunE: func(cmd *cobra.Command, args []string) error {
        // 在 RunE 之后进行清理
        return cleanup()
    },
    PersistentPostRunE: func(cmd *cobra.Command, args []string) error {
        // 在 PostRunE 之后运行，被子命令继承
        return flushLogs()
    },
}

重要：使用 RunE、PreRunE、PostRunE（返回错误的版本）而不是 Run、PreRun、PostRun。

Viper 遵循严格的优先级顺序（从高到低）：

显式设置 (viper.Set("key", value))
命令行标志（通过 viper.BindPFlag 绑定）
环境变量 (MYAPP_KEY=value)
配置文件 (~/.myapp.yaml, ./config.yaml)
键/值存储（etcd、Consul - 可选）
默认值 (viper.SetDefault("key", value))

func initConfig() {

    // 1. 设置默认值（最低优先级）
    viper.SetDefault("port", 8080)
    viper.SetDefault("database.host", "localhost")
    viper.SetDefault("database.port", 5432)

    // 2. 配置文件位置（按顺序检查）
    viper.SetConfigName("config")
    viper.SetConfigType("yaml")
    viper.AddConfigPath("/etc/myapp/")
    viper.AddConfigPath("$HOME/.myapp")
    viper.AddConfigPath(".")

    // 3. 环境变量（前缀 + 自动映射）
    viper.SetEnvPrefix("MYAPP")
    viper.AutomaticEnv() // MYAPP_PORT, MYAPP_DATABASE_HOST 等

    // 4. 读取配置文件（可选）
    if err := viper.ReadInConfig(); err != nil {
        if _, ok := err.(viper.ConfigFileNotFoundError); ok {
            // 未找到配置文件 - 使用默认值和环境变量
        } else {
            // 找到配置文件但读取时出错
            return err
        }
    }

    // 5. 标志将在 init() 函数中绑定（最高优先级）
}

Viper 自动映射带有前缀和点号表示法的环境变量：

viper.SetEnvPrefix("MYAPP") // 环境变量的前缀
viper.AutomaticEnv()        // 启用自动映射

// 配置键 → 环境变量
// "port"              → MYAPP_PORT
// "database.host"     → MYAPP_DATABASE_HOST
// "database.port"     → MYAPP_DATABASE_PORT
// "aws.s3.region"     → MYAPP_AWS_S3_REGION

手动映射 非标准环境变量名称：

viper.BindEnv("database.host", "DB_HOST")          // 自定义环境变量名
viper.BindEnv("database.password", "DB_PASSWORD")  // 不同的命名约定

Viper 支持多种格式：YAML、JSON、TOML、HCL、INI、envfile、Java properties。

port: 8080
log_level: info

database:
  host: localhost
  port: 5432
  user: postgres
  ssl_mode: require

aws:
  region: us-east-1
  s3:
    bucket: my-app-bucket

访问配置值 :

port := viper.GetInt("port")                    // 8080
dbHost := viper.GetString("database.host")      // "localhost"
s3Bucket := viper.GetString("aws.s3.bucket")    // "my-app-bucket"

// 类型安全访问
if viper.IsSet("database.ssl_mode") {
    sslMode := viper.GetString("database.ssl_mode")
}

// 解组到结构体
type Config struct {
    Port     int    `mapstructure:"port"`
    LogLevel string `mapstructure:"log_level"`
    Database struct {
        Host    string `mapstructure:"host"`
        Port    int    `mapstructure:"port"`
        User    string `mapstructure:"user"`
        SSLMode string `mapstructure:"ssl_mode"`
    } `mapstructure:"database"`
}

var config Config
if err := viper.Unmarshal(&config); err != nil {
    return err
}

Cobra + Viper 集成

Cobra + Viper 集成的关键在于将标志绑定到 Viper 键：

// cmd/root.go
func init() {
    cobra.OnInitialize(initConfig) // 在命令执行前加载配置

    // 定义标志
    rootCmd.PersistentFlags().String("config", "", "配置文件")
    rootCmd.PersistentFlags().String("log-level", "info", "日志级别")
    rootCmd.PersistentFlags().Int("port", 8080, "服务器端口")

    // 将标志绑定到 Viper（关键步骤！）
    viper.BindPFlag("config", rootCmd.PersistentFlags().Lookup("config"))
    viper.BindPFlag("log_level", rootCmd.PersistentFlags().Lookup("log-level"))
    viper.BindPFlag("port", rootCmd.PersistentFlags().Lookup("port"))
}

func initConfig() {
    // 通过 cobra.OnInitialize 在命令执行前运行
    if cfgFile := viper.GetString("config"); cfgFile != "" {
        viper.SetConfigFile(cfgFile)
    } else {
        viper.AddConfigPath("$HOME/.myapp")
        viper.AddConfigPath(".")
        viper.SetConfigName("config")
    }

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

    viper.ReadInConfig() // 忽略错误 - 配置文件是可选的
}

标志绑定策略 :

// 策略 1：单独绑定每个标志（显式）
viper.BindPFlag("log_level", rootCmd.Flags().Lookup("log-level"))

// 策略 2：自动绑定所有标志（方便）
viper.BindPFlags(rootCmd.Flags())

// 策略 3：混合方法（推荐）
// - 全局绑定持久标志
// - 在每个命令的 init() 中绑定本地标志
rootCmd.PersistentFlags().String("config", "", "配置文件")
viper.BindPFlags(rootCmd.PersistentFlags())

deployCmd.Flags().String("region", "us-east-1", "AWS 区域")
viper.BindPFlag("deploy.region", deployCmd.Flags().Lookup("region"))

使用 PersistentPreRun 加载配置

使用 PersistentPreRunE 来加载和验证配置：

var rootCmd = &cobra.Command{
    Use:   "myapp",
    Short: "我的应用程序",
    PersistentPreRunE: func(cmd *cobra.Command, args []string) error {
        // 在所有命令之前运行（被子命令继承）

        // 1. 验证必需配置
        if !viper.IsSet("api_key") {
            return fmt.Errorf("未配置 API 密钥（设置 MYAPP_API_KEY 或添加到配置文件）")
        }

        // 2. 基于配置设置日志
        logLevel := viper.GetString("log_level")
        if err := setupLogging(logLevel); err != nil {
            return fmt.Errorf("无效的日志级别：%w", err)
        }

        // 3. 初始化客户端/服务
        apiKey := viper.GetString("api_key")
        if err := initAPIClient(apiKey); err != nil {
            return fmt.Errorf("初始化 API 客户端失败：%w", err)
        }

        return nil
    },
}

Cobra 为 bash、zsh、fish 和 PowerShell 生成 shell 补全脚本。

// cmd/completion.go
package cmd

import (
    "os"

    "github.com/spf13/cobra"
)

var completionCmd = &cobra.Command{
    Use:   "completion [bash|zsh|fish|powershell]",
    Short: "生成 shell 补全脚本",
    Long: `为 myapp 生成 shell 补全脚本。

加载补全：

Bash:
  $ source <(myapp completion bash)
  # 要自动加载，请添加到 ~/.bashrc：
  $ echo 'source <(myapp completion bash)' >> ~/.bashrc

Zsh:
  $ source <(myapp completion zsh)
  # 要自动加载，请添加到 ~/.zshrc：
  $ echo 'source <(myapp completion zsh)' >> ~/.zshrc

Fish:
  $ myapp completion fish | source
  # 要自动加载：
  $ myapp completion fish > ~/.config/fish/completions/myapp.fish

PowerShell:
  PS> myapp completion powershell | Out-String | Invoke-Expression
  # 要自动加载，请添加到 PowerShell 配置文件。
`,
    DisableFlagsInUseLine: true,
    ValidArgs:             []string{"bash", "zsh", "fish", "powershell"},
    Args:                  cobra.ExactValidArgs(1),
    RunE: func(cmd *cobra.Command, args []string) error {
        switch args[0] {
        case "bash":
            return cmd.Root().GenBashCompletion(os.Stdout)
        case "zsh":
            return cmd.Root().GenZshCompletion(os.Stdout)
        case "fish":
            return cmd.Root().GenFishCompletion(os.Stdout, true)
        case "powershell":
            return cmd.Root().GenPowerShellCompletionWithDesc(os.Stdout)
        }
        return nil
    },
}

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

自定义补全函数

为命令参数提供动态补全：

var deployCmd = &cobra.Command{
    Use:   "deploy [environment]",
    Short: "部署到环境",
    Args:  cobra.ExactArgs(1),
    ValidArgsFunction: func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
        // 返回可用环境
        envs := []string{"dev", "staging", "production"}
        return envs, cobra.ShellCompDirectiveNoFileComp
    },
    RunE: func(cmd *cobra.Command, args []string) error {
        return deploy(args[0])
    },
}

// 自定义标志补全
deployCmd.RegisterFlagCompletionFunc("region", func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
    regions := []string{"us-east-1", "us-west-2", "eu-west-1"}
    return regions, cobra.ShellCompDirectiveNoFileComp
})

用户友好的错误消息

// ❌ 不好：技术术语
return fmt.Errorf("数据库连接失败：EOF")

// ✅ 好：可操作的错误消息
return fmt.Errorf("无法连接到数据库 %s:%d\n请检查：\n  - 数据库是否正在运行\n  - 凭据是否正确 (MYAPP_DB_PASSWORD)\n  - 网络连接性", host, port)

// ✅ 好：建议修复方法
if !viper.IsSet("api_key") {
    return fmt.Errorf("未配置 API 密钥\n设置环境变量：export MYAPP_API_KEY=your-key\n或添加到配置文件：~/.myapp.yaml")
}

import "github.com/briandowns/spinner"

func deploy(env string) error {
    s := spinner.New(spinner.CharSets[11], 100*time.Millisecond)
    s.Suffix = " 正在部署到 " + env + "..."
    s.Start()
    defer s.Stop()

    // 部署逻辑
    if err := performDeployment(env); err != nil {
        s.Stop()
        return err
    }

    s.Stop()
    fmt.Println("✓ 部署成功")
    return nil
}

import (
    "encoding/json"
    "github.com/olekukonko/tablewriter"
)

func displayResults(items []Item, format string) error {
    switch format {
    case "json":
        enc := json.NewEncoder(os.Stdout)
        enc.SetIndent("", "  ")
        return enc.Encode(items)

    case "table":
        table := tablewriter.NewWriter(os.Stdout)
        table.SetHeader([]string{"ID", "名称", "状态"})
        for _, item := range items {
            table.Append([]string{item.ID, item.Name, item.Status})
        }
        table.Render()
        return nil

    default:
        return fmt.Errorf("未知格式：%s（使用 json 或 table）", format)
    }
}

日志记录与用户输出

import (
    "log"
    "os"
)

var (
    // 面向用户的输出（stdout）
    out = os.Stdout

    // 日志记录和错误（stderr）
    logger = log.New(os.Stderr, "[myapp] ", log.LstdFlags)
)

func RunCommand() error {
    // 用户输出：stdout
    fmt.Fprintln(out, "正在处理文件...")

    // 调试/详细日志记录：stderr
    if viper.GetBool("verbose") {
        logger.Println("从", viper.ConfigFileUsed(), "读取配置")
    }

    // 错误：stderr
    if err := process(); err != nil {
        fmt.Fprintf(os.Stderr, "错误：%v\n", err)
        return err
    }

    // 成功消息：stdout
    fmt.Fprintln(out, "✓ 完成")
    return nil
}

测试 CLI 应用程序

// cmd/deploy_test.go
package cmd

import (
    "bytes"
    "testing"

    "github.com/spf13/cobra"
    "github.com/stretchr/testify/assert"
    "github.com/stretchr/testify/require"
)

func executeCommand(root *cobra.Command, args ...string) (output string, err error) {
    buf := new(bytes.Buffer)
    root.SetOut(buf)
    root.SetErr(buf)
    root.SetArgs(args)

    err = root.Execute()
    return buf.String(), err
}

func TestDeployCommand(t *testing.T) {
    tests := []struct {
        name    string
        args    []string
        wantErr bool
        wantOut string
    }{
        {
            name:    "部署到 dev",
            args:    []string{"deploy", "dev"},
            wantErr: false,
            wantOut: "正在部署到 dev",
        },
        {
            name:    "部署到 production 但没有 force",
            args:    []string{"deploy", "production"},
            wantErr: true,
            wantOut: "生产环境部署需要 --force 标志",
        },
        {
            name:    "部署到 production 并带有 force",
            args:    []string{"deploy", "production", "--force"},
            wantErr: false,
            wantOut: "正在部署到 production",
        },
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            output, err := executeCommand(rootCmd, tt.args...)

            if tt.wantErr {
                require.Error(t, err)
            } else {
                require.NoError(t, err)
            }

            assert.Contains(t, output, tt.wantOut)
        })
    }
}

使用 Viper 配置进行测试

func TestCommandWithConfig(t *testing.T) {
    // 在每个测试前重置 viper 状态
    viper.Reset()

    // 设置测试配置
    viper.Set("region", "eu-west-1")
    viper.Set("api_key", "test-key-123")

    output, err := executeCommand(rootCmd, "deploy", "staging")

    require.NoError(t, err)
    assert.Contains(t, output, "eu-west-1")
}

func TestOutputFormat(t *testing.T) {
    // 捕获 stdout
    oldStdout := os.Stdout
    r, w, _ := os.Pipe()
    os.Stdout = w
    defer func() { os.Stdout = oldStdout }()

    // 执行命令
    err := listCmd.RunE(listCmd, []string{})
    require.NoError(t, err)

    // 读取输出
    w.Close()
    var buf bytes.Buffer
    io.Copy(&buf, r)
    output := buf.String()

    assert.Contains(t, output, "ID")
    assert.Contains(t, output, "名称")
}

在以下情况下使用 Cobra：

✅ 构建带有子命令的多命令 CLI（例如 git clone、docker run）
✅ 需要符合 POSIX 标准的标志解析（--flag、-f）
✅ 需要内置帮助生成（--help）
✅ 需要 shell 补全支持
✅ 构建供其他开发者使用的专业 CLI

在以下情况下不要使用 Cobra：

❌ 简单的单命令脚本（使用 flag 包）
❌ 仅内部使用且只有 1-2 个标志的工具
❌ 原型设计或一次性脚本

在以下情况下使用 Viper：

✅ 需要来自多个源的配置（标志、环境变量、文件）
✅ 需要清晰的配置优先级规则
✅ 支持多种配置文件格式（YAML、JSON、TOML）
✅ 需要带有前缀的环境变量映射
✅ 需要实时配置重新加载（监视配置文件变化）

在以下情况下不要使用 Viper：

❌ 仅使用命令行标志（仅 Cobra 就足够了）
❌ 硬编码的配置值
❌ 没有配置的简单脚本

何时添加 Shell 补全

在以下情况下添加 shell 补全：

✅ CLI 被开发者频繁使用（每天/每小时）
✅ 有许多子命令或复杂的标志组合
✅ 参数具有已知的有效值（例如环境、区域）
✅ 构建专业的开发者工具

在以下情况下跳过 shell 补全：

❌ CLI 很少使用（每月或更少）
❌ 选项很少的简单命令
❌ 仅内部使用的工具

何时使用持久标志

在以下情况下使用持久标志：

✅ 标志适用于所有子命令（例如 --verbose、--config）
✅ 跨命令共享的通用配置
✅ 全局行为修改器（例如 --dry-run、--output）

在以下情况下使用本地标志：

✅ 标志仅与特定命令相关
✅ 命令特定参数（例如 --region 用于 deploy 命令）

❌ 不在 PreRunE/RunE 中处理错误

var deployCmd = &cobra.Command{
    Use: "deploy",
    Run: func(cmd *cobra.Command, args []string) {
        deploy(args[0]) // 忽略错误！
    },
}

var deployCmd = &cobra.Command{
    Use: "deploy",
    RunE: func(cmd *cobra.Command, args []string) error {
        return deploy(args[0]) // 正确的错误处理
    },
}

❌ 混合配置源但没有明确的优先级

// 混乱：哪个优先？
config.Port = viper.GetInt("port")
if os.Getenv("PORT") != "" {
    config.Port = atoi(os.Getenv("PORT"))
}
if *flagPort != 0 {
    config.Port = *flagPort
}

// 清晰：Viper 自动处理优先级
viper.BindPFlag("port", rootCmd.Flags().Lookup("port"))
viper.SetEnvPrefix("MYAPP")
viper.AutomaticEnv()
viper.SetDefault("port", 8080)

config.Port = viper.GetInt("port") // 遵循：标志 > 环境变量 > 配置 > 默认值

❌ 忘记将标志绑定到 Viper

rootCmd.Flags().String("region", "us-east-1", "AWS 区域")
// 标志未绑定到 Viper - 不会遵循优先级！

func deploy() {
    region := viper.GetString("region") // 始终返回配置文件的值
}

rootCmd.Flags().String("region", "us-east-1", "AWS 区域")
viper.BindPFlag("region", rootCmd.Flags().Lookup("region")) // 绑定它！

func deploy() {
    region := viper.GetString("region") // 遵循：标志 > 环境变量 > 配置
}

❌ 不测试 CLI 命令

// 没有 CLI 命令的测试 - 错误会悄悄溜过

func TestDeployCommand(t *testing.T) {
    output, err := executeCommand(rootCmd, "deploy", "staging", "--region", "eu-west-1")
    require.NoError(t, err)
    assert.Contains(t, output, "正在部署到 staging")
    assert.Contains(t, output, "eu-west-1")
}

❌ 错误消息不佳

return fmt.Errorf("连接失败") // 没有帮助

return fmt.Errorf("无法连接到数据库 %s:%d\n检查：\n  - 数据库是否正在运行\n  - 凭据 (MYAPP_DB_PASSWORD)\n  - 防火墙规则", host, port)

❌ 使用 Run 而不是 RunE

var rootCmd = &cobra.Command{
    Use: "myapp",
    Run: func(cmd *cobra.Command, args []string) {
        if err := execute(); err != nil {
            fmt.Println(err) // 错误未传播
        }
    },
}

var rootCmd = &cobra.Command{
    Use: "myapp",
    RunE: func(cmd *cobra.Command, args []string) error {
        return execute() // Cobra 处理错误显示和退出代码
    },
}

最小化的生产就绪 CLI 结构：

myapp/
├── cmd/
│   ├── root.go          # 根命令 + 配置加载
│   ├── deploy.go        # Deploy 子命令
│   ├── status.go        # Status 子命令
│   └── completion.go    # Shell 补全
├── main.go              # 入口点
├── config.yaml          # 示例配置文件
└── go.mod

package main

import "myapp/cmd"

func main() {
    cmd.Execute()
}

cmd/root.go ：参见上面的“命令结构模式”部分

构建和安装 :

# 开发
go run main.go deploy staging --region us-west-2

# 生产构建
go build -o myapp

# 全局安装
go install

# 启用 shell 补全
myapp completion bash > /etc/bash_completion.d/myapp

Cobra 用户指南 - 官方框架文档
Viper 文档 - 配置管理指南

"使用 Cobra & Viper 在 Go 中构建 CLI 应用程序"（2025 年 11 月）- 综合教程
"Cobra & Viper 之旅" - CLI 开发的学习路径
Cobra 生成器 - 用于新 CLI 的脚手架工具

kubectl - Kubernetes CLI
docker - Docker CLI
gh - GitHub CLI
hugo - 静态站点生成器

golang-testing-strategies - 全面测试 CLI 命令
golang-http-servers - 使用配置构建 API 服务器
golang-concurrency-patterns - CLI 工具中的异步操作

当您满足以下条件时，您就掌握了 Cobra + Viper：

✅ 命令遵循 POSIX 约定（VERB NOUN --FLAG）
✅ 配置优先级清晰：标志 > 环境变量 > 配置 > 默认值
✅ 所有标志都绑定到 Viper 以进行统一配置访问
✅ 为所有主要 shell 生成 shell 补全
✅ 错误消息是可操作的且对用户友好
✅ CLI 命令有全面的测试
✅ 帮助文本自动生成且准确
✅ 使用 PersistentPreRunE 进行全局设置/验证
✅ 关注点分离：用户输出 (stdout) 与日志记录 (stderr)
✅ 配置文件可选 - CLI 仅使用标志/环境变量即可工作

2026 年 1 月 23 日

🇺🇸English

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())
        }
    }
}

Subcommands with Arguments

// cmd/deploy.go
package cmd

import (
    "fmt"

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

var deployCmd = &cobra.Command{
    Use:   "deploy [environment]",
    Short: "Deploy application to specified environment",
    Long: `Deploy the application to the specified environment.
Supports: dev, staging, production`,
    Args: cobra.ExactArgs(1),
    ValidArgs: []string{"dev", "staging", "production"},
    PreRunE: func(cmd *cobra.Command, args []string) error {
        // Validation logic runs before RunE
        env := args[0]
        if env == "production" && !viper.GetBool("force") {
            return fmt.Errorf("production deploys require --force flag")
        }
        return nil
    },
    RunE: func(cmd *cobra.Command, args []string) error {
        env := args[0]
        region := viper.GetString("region")
        force := viper.GetBool("force")

        fmt.Printf("Deploying to %s in region %s (force=%v)\n", env, region, force)

        // Actual deployment logic
        return deploy(env, region, force)
    },
    PostRunE: func(cmd *cobra.Command, args []string) error {
        // Cleanup or notifications
        fmt.Println("Deployment complete")
        return nil
    },
}

func init() {
    rootCmd.AddCommand(deployCmd)

    // Local flags (only for this command)
    deployCmd.Flags().StringP("region", "r", "us-east-1", "AWS region")
    deployCmd.Flags().BoolP("force", "f", false, "Force deployment without confirmation")

    // Bind flags to viper
    viper.BindPFlag("region", deployCmd.Flags().Lookup("region"))
    viper.BindPFlag("force", deployCmd.Flags().Lookup("force"))
}

func deploy(env, region string, force bool) error {
    // Implementation
    return nil
}

Persistent vs. Local Flags

// Persistent flags: Available to command and all subcommands
rootCmd.PersistentFlags().String("config", "", "config file path")
rootCmd.PersistentFlags().Bool("verbose", false, "verbose output")

// Local flags: Only available to this specific command
deployCmd.Flags().String("region", "us-east-1", "deployment region")
deployCmd.Flags().Bool("force", false, "force deployment")

// Required flags
deployCmd.MarkFlagRequired("region")

// Flag dependencies
deployCmd.MarkFlagsRequiredTogether("username", "password")
deployCmd.MarkFlagsMutuallyExclusive("json", "yaml")

PreRun/PostRun Hooks

Cobra provides execution hooks for setup and cleanup:

var serverCmd = &cobra.Command{
    Use:   "server",
    Short: "Start API server",

    // Execution order (all optional):
    PersistentPreRunE: func(cmd *cobra.Command, args []string) error {
        // Runs before PreRunE, inherited by subcommands
        return setupLogging()
    },
    PreRunE: func(cmd *cobra.Command, args []string) error {
        // Validation and setup before RunE
        return validateConfig()
    },
    RunE: func(cmd *cobra.Command, args []string) error {
        // Main command logic
        return startServer()
    },
    PostRunE: func(cmd *cobra.Command, args []string) error {
        // Cleanup after RunE
        return cleanup()
    },
    PersistentPostRunE: func(cmd *cobra.Command, args []string) error {
        // Runs after PostRunE, inherited by subcommands
        return flushLogs()
    },
}

Important : Use RunE, PreRunE, PostRunE (error-returning versions) instead of Run, PreRun, PostRun.

Viper Configuration Management

Configuration Priority

Viper follows a strict precedence order (highest to lowest):

Explicit Set (viper.Set("key", value))
Command-line Flags (bound with viper.BindPFlag)
Environment Variables (MYAPP_KEY=value)
Config File (~/.myapp.yaml, ./config.yaml)
Key/Value Store (etcd, Consul - optional)
Defaults (viper.SetDefault("key", value))

func initConfig() {

    // 1. Set defaults (lowest priority)
    viper.SetDefault("port", 8080)
    viper.SetDefault("database.host", "localhost")
    viper.SetDefault("database.port", 5432)

    // 2. Config file locations (checked in order)
    viper.SetConfigName("config")
    viper.SetConfigType("yaml")
    viper.AddConfigPath("/etc/myapp/")
    viper.AddConfigPath("$HOME/.myapp")
    viper.AddConfigPath(".")

    // 3. Environment variables (prefix + automatic mapping)
    viper.SetEnvPrefix("MYAPP")
    viper.AutomaticEnv() // MYAPP_PORT, MYAPP_DATABASE_HOST, etc.

    // 4. Read config file (optional)
    if err := viper.ReadInConfig(); err != nil {
        if _, ok := err.(viper.ConfigFileNotFoundError); ok {
            // Config file not found - use defaults and env vars
        } else {
            // Config file found but error reading it
            return err
        }
    }

    // 5. Flags will be bound in init() functions (highest priority)
}

Environment Variable Mapping

Viper automatically maps environment variables with prefix and dot notation:

viper.SetEnvPrefix("MYAPP") // Prefix for env vars
viper.AutomaticEnv()        // Enable automatic mapping

// Config key → Environment variable
// "port"              → MYAPP_PORT
// "database.host"     → MYAPP_DATABASE_HOST
// "database.port"     → MYAPP_DATABASE_PORT
// "aws.s3.region"     → MYAPP_AWS_S3_REGION

Manual mapping for non-standard env var names:

viper.BindEnv("database.host", "DB_HOST")          // Custom env var name
viper.BindEnv("database.password", "DB_PASSWORD")  // Different naming convention

Config File Formats

Viper supports multiple formats: YAML, JSON, TOML, HCL, INI, envfile, Java properties.

config.yaml :

port: 8080
log_level: info

database:
  host: localhost
  port: 5432
  user: postgres
  ssl_mode: require

aws:
  region: us-east-1
  s3:
    bucket: my-app-bucket

Accessing config values :

port := viper.GetInt("port")                    // 8080
dbHost := viper.GetString("database.host")      // "localhost"
s3Bucket := viper.GetString("aws.s3.bucket")    // "my-app-bucket"

// Type-safe access
if viper.IsSet("database.ssl_mode") {
    sslMode := viper.GetString("database.ssl_mode")
}

// Unmarshal into struct
type Config struct {
    Port     int    `mapstructure:"port"`
    LogLevel string `mapstructure:"log_level"`
    Database struct {
        Host    string `mapstructure:"host"`
        Port    int    `mapstructure:"port"`
        User    string `mapstructure:"user"`
        SSLMode string `mapstructure:"ssl_mode"`
    } `mapstructure:"database"`
}

var config Config
if err := viper.Unmarshal(&config); err != nil {
    return err
}

Cobra + Viper Integration

Critical Integration Pattern

The key to Cobra + Viper integration is binding flags to Viper keys:

// cmd/root.go
func init() {
    cobra.OnInitialize(initConfig) // Load config before command execution

    // Define flags
    rootCmd.PersistentFlags().String("config", "", "config file")
    rootCmd.PersistentFlags().String("log-level", "info", "log level")
    rootCmd.PersistentFlags().Int("port", 8080, "server port")

    // Bind flags to Viper (critical step!)
    viper.BindPFlag("config", rootCmd.PersistentFlags().Lookup("config"))
    viper.BindPFlag("log_level", rootCmd.PersistentFlags().Lookup("log-level"))
    viper.BindPFlag("port", rootCmd.PersistentFlags().Lookup("port"))
}

func initConfig() {
    // This runs BEFORE command execution via cobra.OnInitialize
    if cfgFile := viper.GetString("config"); cfgFile != "" {
        viper.SetConfigFile(cfgFile)
    } else {
        viper.AddConfigPath("$HOME/.myapp")
        viper.AddConfigPath(".")
        viper.SetConfigName("config")
    }

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

    viper.ReadInConfig() // Ignore errors - config file is optional
}

Flag binding strategies :

// Strategy 1: Bind each flag individually (explicit)
viper.BindPFlag("log_level", rootCmd.Flags().Lookup("log-level"))

// Strategy 2: Bind all flags automatically (convenient)
viper.BindPFlags(rootCmd.Flags())

// Strategy 3: Hybrid approach (recommended)
// - Bind persistent flags globally
// - Bind local flags in each command's init()
rootCmd.PersistentFlags().String("config", "", "config file")
viper.BindPFlags(rootCmd.PersistentFlags())

deployCmd.Flags().String("region", "us-east-1", "AWS region")
viper.BindPFlag("deploy.region", deployCmd.Flags().Lookup("region"))

PersistentPreRun for Config Loading

Use PersistentPreRunE to load and validate configuration:

var rootCmd = &cobra.Command{
    Use:   "myapp",
    Short: "My application",
    PersistentPreRunE: func(cmd *cobra.Command, args []string) error {
        // Runs before ALL commands (inherited by subcommands)

        // 1. Validate required config
        if !viper.IsSet("api_key") {
            return fmt.Errorf("API key not configured (set MYAPP_API_KEY or add to config file)")
        }

        // 2. Setup logging based on config
        logLevel := viper.GetString("log_level")
        if err := setupLogging(logLevel); err != nil {
            return fmt.Errorf("invalid log level: %w", err)
        }

        // 3. Initialize clients/services
        apiKey := viper.GetString("api_key")
        if err := initAPIClient(apiKey); err != nil {
            return fmt.Errorf("failed to initialize API client: %w", err)
        }

        return nil
    },
}

Shell Completion

Cobra generates shell completion scripts for bash, zsh, fish, and PowerShell.

Adding Completion Command

// cmd/completion.go
package cmd

import (
    "os"

    "github.com/spf13/cobra"
)

var completionCmd = &cobra.Command{
    Use:   "completion [bash|zsh|fish|powershell]",
    Short: "Generate shell completion script",
    Long: `Generate shell completion script for myapp.

To load completions:

Bash:
  $ source <(myapp completion bash)
  # To load automatically, add to ~/.bashrc:
  $ echo 'source <(myapp completion bash)' >> ~/.bashrc

Zsh:
  $ source <(myapp completion zsh)
  # To load automatically, add to ~/.zshrc:
  $ echo 'source <(myapp completion zsh)' >> ~/.zshrc

Fish:
  $ myapp completion fish | source
  # To load automatically:
  $ myapp completion fish > ~/.config/fish/completions/myapp.fish

PowerShell:
  PS> myapp completion powershell | Out-String | Invoke-Expression
  # To load automatically, add to PowerShell profile.
`,
    DisableFlagsInUseLine: true,
    ValidArgs:             []string{"bash", "zsh", "fish", "powershell"},
    Args:                  cobra.ExactValidArgs(1),
    RunE: func(cmd *cobra.Command, args []string) error {
        switch args[0] {
        case "bash":
            return cmd.Root().GenBashCompletion(os.Stdout)
        case "zsh":
            return cmd.Root().GenZshCompletion(os.Stdout)
        case "fish":
            return cmd.Root().GenFishCompletion(os.Stdout, true)
        case "powershell":
            return cmd.Root().GenPowerShellCompletionWithDesc(os.Stdout)
        }
        return nil
    },
}

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

Custom Completion Functions

Provide dynamic completions for command arguments:

var deployCmd = &cobra.Command{
    Use:   "deploy [environment]",
    Short: "Deploy to environment",
    Args:  cobra.ExactArgs(1),
    ValidArgsFunction: func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
        // Return available environments
        envs := []string{"dev", "staging", "production"}
        return envs, cobra.ShellCompDirectiveNoFileComp
    },
    RunE: func(cmd *cobra.Command, args []string) error {
        return deploy(args[0])
    },
}

// Custom flag completion
deployCmd.RegisterFlagCompletionFunc("region", func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
    regions := []string{"us-east-1", "us-west-2", "eu-west-1"}
    return regions, cobra.ShellCompDirectiveNoFileComp
})

CLI Best Practices

User-Friendly Error Messages

// ❌ BAD: Technical jargon
return fmt.Errorf("db connection failed: EOF")

// ✅ GOOD: Actionable error message
return fmt.Errorf("cannot connect to database at %s:%d\nPlease check:\n  - Database is running\n  - Credentials are correct (MYAPP_DB_PASSWORD)\n  - Network connectivity", host, port)

// ✅ GOOD: Suggest remediation
if !viper.IsSet("api_key") {
    return fmt.Errorf("API key not configured\nSet environment variable: export MYAPP_API_KEY=your-key\nOr add to config file: ~/.myapp.yaml")
}

Progress Indicators

import "github.com/briandowns/spinner"

func deploy(env string) error {
    s := spinner.New(spinner.CharSets[11], 100*time.Millisecond)
    s.Suffix = " Deploying to " + env + "..."
    s.Start()
    defer s.Stop()

    // Deployment logic
    if err := performDeployment(env); err != nil {
        s.Stop()
        return err
    }

    s.Stop()
    fmt.Println("✓ Deployment successful")
    return nil
}

Output Formatting

import (
    "encoding/json"
    "github.com/olekukonko/tablewriter"
)

func displayResults(items []Item, format string) error {
    switch format {
    case "json":
        enc := json.NewEncoder(os.Stdout)
        enc.SetIndent("", "  ")
        return enc.Encode(items)

    case "table":
        table := tablewriter.NewWriter(os.Stdout)
        table.SetHeader([]string{"ID", "Name", "Status"})
        for _, item := range items {
            table.Append([]string{item.ID, item.Name, item.Status})
        }
        table.Render()
        return nil

    default:
        return fmt.Errorf("unknown format: %s (use json or table)", format)
    }
}

Logging vs. User Output

import (
    "log"
    "os"
)

var (
    // User-facing output (stdout)
    out = os.Stdout

    // Logging and errors (stderr)
    logger = log.New(os.Stderr, "[myapp] ", log.LstdFlags)
)

func RunCommand() error {
    // User output: stdout
    fmt.Fprintln(out, "Processing files...")

    // Debug/verbose logging: stderr
    if viper.GetBool("verbose") {
        logger.Println("Reading config from", viper.ConfigFileUsed())
    }

    // Errors: stderr
    if err := process(); err != nil {
        fmt.Fprintf(os.Stderr, "Error: %v\n", err)
        return err
    }

    // Success message: stdout
    fmt.Fprintln(out, "✓ Complete")
    return nil
}

Testing CLI Applications

Testing Command Execution

// cmd/deploy_test.go
package cmd

import (
    "bytes"
    "testing"

    "github.com/spf13/cobra"
    "github.com/stretchr/testify/assert"
    "github.com/stretchr/testify/require"
)

func executeCommand(root *cobra.Command, args ...string) (output string, err error) {
    buf := new(bytes.Buffer)
    root.SetOut(buf)
    root.SetErr(buf)
    root.SetArgs(args)

    err = root.Execute()
    return buf.String(), err
}

func TestDeployCommand(t *testing.T) {
    tests := []struct {
        name    string
        args    []string
        wantErr bool
        wantOut string
    }{
        {
            name:    "deploy to dev",
            args:    []string{"deploy", "dev"},
            wantErr: false,
            wantOut: "Deploying to dev",
        },
        {
            name:    "deploy to production without force",
            args:    []string{"deploy", "production"},
            wantErr: true,
            wantOut: "production deploys require --force flag",
        },
        {
            name:    "deploy to production with force",
            args:    []string{"deploy", "production", "--force"},
            wantErr: false,
            wantOut: "Deploying to production",
        },
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            output, err := executeCommand(rootCmd, tt.args...)

            if tt.wantErr {
                require.Error(t, err)
            } else {
                require.NoError(t, err)
            }

            assert.Contains(t, output, tt.wantOut)
        })
    }
}

Testing with Viper Configuration

func TestCommandWithConfig(t *testing.T) {
    // Reset viper state before each test
    viper.Reset()

    // Set test configuration
    viper.Set("region", "eu-west-1")
    viper.Set("api_key", "test-key-123")

    output, err := executeCommand(rootCmd, "deploy", "staging")

    require.NoError(t, err)
    assert.Contains(t, output, "eu-west-1")
}

Capturing Output

func TestOutputFormat(t *testing.T) {
    // Capture stdout
    oldStdout := os.Stdout
    r, w, _ := os.Pipe()
    os.Stdout = w
    defer func() { os.Stdout = oldStdout }()

    // Execute command
    err := listCmd.RunE(listCmd, []string{})
    require.NoError(t, err)

    // Read output
    w.Close()
    var buf bytes.Buffer
    io.Copy(&buf, r)
    output := buf.String()

    assert.Contains(t, output, "ID")
    assert.Contains(t, output, "Name")
}

Decision Trees

When to Use Cobra

Use Cobra when:

✅ Building multi-command CLI with subcommands (e.g., git clone, docker run)
✅ Need POSIX-compliant flag parsing (--flag, -f)
✅ Want built-in help generation (--help)
✅ Require shell completion support
✅ Building professional CLI used by other developers

Don't use Cobra when:

❌ Simple single-command script (use flag package)
❌ Internal-only tool with 1-2 flags
❌ Prototyping or throwaway scripts

When to Use Viper

Use Viper when:

✅ Need configuration from multiple sources (flags, env vars, files)
✅ Want clear configuration precedence rules
✅ Support multiple config file formats (YAML, JSON, TOML)
✅ Require environment variable mapping with prefixes
✅ Need live config reloading (watch config file changes)

Don't use Viper when:

❌ Only using command-line flags (Cobra alone is sufficient)
❌ Hardcoded configuration values
❌ Simple scripts with no configuration

When to Add Shell Completion

Add shell completion when:

✅ CLI used frequently by developers (daily/hourly)
✅ Many subcommands or complex flag combinations
✅ Arguments have known valid values (e.g., environments, regions)
✅ Building professional developer tools

Skip shell completion when:

❌ CLI used rarely (monthly or less)
❌ Simple commands with few options
❌ Internal-only tools

When to Use Persistent Flags

Use persistent flags when:

✅ Flag applies to ALL subcommands (e.g., --verbose, --config)
✅ Common configuration shared across commands
✅ Global behavior modifiers (e.g., --dry-run, --output)

Use local flags when:

✅ Flag only relevant to specific command
✅ Command-specific parameters (e.g., --region for deploy command)

Anti-Patterns

❌ Not Handling Errors in PreRunE/RunE

Wrong :

var deployCmd = &cobra.Command{
    Use: "deploy",
    Run: func(cmd *cobra.Command, args []string) {
        deploy(args[0]) // Ignores error!
    },
}

Correct :

var deployCmd = &cobra.Command{
    Use: "deploy",
    RunE: func(cmd *cobra.Command, args []string) error {
        return deploy(args[0]) // Proper error handling
    },
}

❌ Mixing Configuration Sources Without Clear Precedence

Wrong :

// Confusing: Which takes precedence?
config.Port = viper.GetInt("port")
if os.Getenv("PORT") != "" {
    config.Port = atoi(os.Getenv("PORT"))
}
if *flagPort != 0 {
    config.Port = *flagPort
}

Correct :

// Clear: Viper handles precedence automatically
viper.BindPFlag("port", rootCmd.Flags().Lookup("port"))
viper.SetEnvPrefix("MYAPP")
viper.AutomaticEnv()
viper.SetDefault("port", 8080)

config.Port = viper.GetInt("port") // Respects: flag > env > config > default

❌ Forgetting to Bind Flags to Viper

Wrong :

rootCmd.Flags().String("region", "us-east-1", "AWS region")
// Flag not bound to Viper - won't respect precedence!

func deploy() {
    region := viper.GetString("region") // Always returns config file value
}

Correct :

rootCmd.Flags().String("region", "us-east-1", "AWS region")
viper.BindPFlag("region", rootCmd.Flags().Lookup("region")) // Bind it!

func deploy() {
    region := viper.GetString("region") // Respects flag > env > config
}

❌ Not Testing CLI Commands

Wrong :

// No tests for CLI commands - bugs slip through

Correct :

func TestDeployCommand(t *testing.T) {
    output, err := executeCommand(rootCmd, "deploy", "staging", "--region", "eu-west-1")
    require.NoError(t, err)
    assert.Contains(t, output, "Deploying to staging")
    assert.Contains(t, output, "eu-west-1")
}

❌ Poor Error Messages

Wrong :

return fmt.Errorf("connection failed") // Unhelpful

Correct :

return fmt.Errorf("cannot connect to database at %s:%d\nCheck:\n  - Database is running\n  - Credentials (MYAPP_DB_PASSWORD)\n  - Firewall rules", host, port)

❌ Using Run Instead of RunE

Wrong :

var rootCmd = &cobra.Command{
    Use: "myapp",
    Run: func(cmd *cobra.Command, args []string) {
        if err := execute(); err != nil {
            fmt.Println(err) // Error not propagated
        }
    },
}

Correct :

var rootCmd = &cobra.Command{
    Use: "myapp",
    RunE: func(cmd *cobra.Command, args []string) error {
        return execute() // Cobra handles error display and exit code
    },
}

Production Example

Minimal production-ready CLI structure:

myapp/
├── cmd/
│   ├── root.go          # Root command + config loading
│   ├── deploy.go        # Deploy subcommand
│   ├── status.go        # Status subcommand
│   └── completion.go    # Shell completion
├── main.go              # Entry point
├── config.yaml          # Example config file
└── go.mod

main.go :

package main

import "myapp/cmd"

func main() {
    cmd.Execute()
}

cmd/root.go : See "Command Structure Pattern" section above

Building and installing :

# Development
go run main.go deploy staging --region us-west-2

# Production build
go build -o myapp

# Install globally
go install

# Enable shell completion
myapp completion bash > /etc/bash_completion.d/myapp

Resources

Official Documentation :

Cobra User Guide - Official framework documentation
Viper Documentation - Configuration management guide

Learning Resources :

"Building CLI Apps in Go with Cobra & Viper" (November 2025) - Comprehensive tutorial
"The Cobra & Viper Journey" - Learning path for CLI development
Cobra Generator - Scaffolding tool for new CLIs

Production Examples :

kubectl - Kubernetes CLI
docker - Docker CLI
gh - GitHub CLI
hugo - Static site generator

Related Skills :

golang-testing-strategies - Testing CLI commands comprehensively
golang-http-servers - Building API servers with configuration
golang-concurrency-patterns - Async operations in CLI tools

Success Criteria

You know you've mastered Cobra + Viper when:

✅ Commands follow POSIX conventions (VERB NOUN --FLAG)
✅ Configuration precedence is clear: flags > env > config > defaults
✅ All flags bound to Viper for unified config access
✅ Shell completion generated for all major shells
✅ Error messages are actionable and user-friendly
✅ CLI commands have comprehensive tests
✅ Help text auto-generated and accurate
✅ PersistentPreRunE used for global setup/validation
✅ Separation of concerns: user output (stdout) vs. logging (stderr)
✅ Config files optional - CLI works with flags/env vars alone

Weekly Installs

152

Repository

bobmatnyc/claud…m-skills

GitHub Stars

First Seen

Jan 23, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykWarn

Installed on

opencode124

codex120

gemini-cli119

github-copilot117

claude-code116

cursor115

Azure 升级评估与自动化工具 - 轻松迁移 Functions 计划、托管层级和 SKU

90,800 周安装

Go CLI开发教程：使用Cobra和Viper构建生产级命令行工具

🇨🇳中文介绍

使用 Cobra 和 Viper 进行 Go CLI 开发

概述

何时使用此技能

Cobra 框架

命令结构模式

相关 Skills

带参数的子命令

持久标志与本地标志

PreRun/PostRun 钩子

Viper 配置管理

配置优先级

环境变量映射

配置文件格式

Cobra + Viper 集成

关键集成模式

使用 PersistentPreRun 加载配置

Shell 补全

添加补全命令

自定义补全函数

CLI 最佳实践

用户友好的错误消息

进度指示器

输出格式化

日志记录与用户输出

测试 CLI 应用程序

测试命令执行

使用 Viper 配置进行测试

捕获输出

决策树

何时使用 Cobra

何时使用 Viper

何时添加 Shell 补全

何时使用持久标志

反模式

❌ 不在 PreRunE/RunE 中处理错误

❌ 混合配置源但没有明确的优先级

❌ 忘记将标志绑定到 Viper

❌ 不测试 CLI 命令

❌ 错误消息不佳

❌ 使用 Run 而不是 RunE

生产示例

资源

成功标准

🇺🇸English

Go CLI Development with Cobra & Viper

Overview

When to Use This Skill

Cobra Framework

Command Structure Pattern

Subcommands with Arguments

Persistent vs. Local Flags

PreRun/PostRun Hooks

Viper Configuration Management

Configuration Priority

Environment Variable Mapping

Config File Formats

Cobra + Viper Integration

Critical Integration Pattern

PersistentPreRun for Config Loading

Shell Completion

Adding Completion Command

Custom Completion Functions

CLI Best Practices

User-Friendly Error Messages

Progress Indicators

Output Formatting

Logging vs. User Output

Testing CLI Applications

Testing Command Execution

Testing with Viper Configuration

Capturing Output

Decision Trees

When to Use Cobra

When to Use Viper

When to Add Shell Completion

When to Use Persistent Flags

Anti-Patterns

❌ Not Handling Errors in PreRunE/RunE