📦 Golang Spf13 Cobra 是一个流行的命令行框架，用于构建强大的命令行接口（CLI）应用程序。它提供了一个简单且灵活的方式来定义命令、参数和标志。Spf13 Cobra 是 GitHub 上的一个开源项目，广泛用于许多流行的项目中，包括 Kubernetes 和 Docker。它支持自动生成帮助文档、自动完成和错误处理等功能。使用 Spf13 Cobra，可以轻松地创建复杂的命令行应用程序，并且可以与 API 集成。

角色：您是一名Go CLI工程师，构建感觉像Unix shell原生命令的命令树。您首先设计用户界面，然后将行为连接到正确的钩子。

模式：

• 构建：从头开始创建一个新的CLI，按照命令树设置、钩子连接和标志部分的顺序进行。
• 扩展：向现有的CLI添加子命令、标志或补全，首先阅读当前的命令树，然后应用与现有结构一致的更改。
• 审核：审计现有的CLI，检查常见错误表，验证RunE的使用、OutOrStdout()、钩子链顺序和参数验证。

使用spf13/cobra进行Go CLI命令树构建 Cobra是Go CLI应用程序的事实标准。它提供命令/子命令树、标志解析（通过pflag）、参数验证、shell补全生成和文档生成。它不处理配置分层——这是viper的工作。

官方资源：

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

本技能并不详尽，请参考库文档和代码示例以获取更多信息。Context7可以作为发现平台提供帮助。 使用go get github.com/spf13/cobra@latest安装Cobra。

Cobra与viper 这些库从根本上做着不同的事情，可以独立使用。

• 通过BindPFlag将pflag.Flag传递给viper
• 将cobra标志视为最高优先级层

使用场景：

• 当二进制文件仅需要标志和参数时，使用cobra。
• 当长期运行的服务从YAML + 环境变量读取配置且没有CLI子命令时，使用viper。
• 当需要同时使用两者时，绑定到根命令的PersistentPreRunE上。

命令树 每个cobra CLI都有一个根命令和零个或多个通过AddCommand注册的子命令。根命令名称是二进制名称。

var rootCmd = &cobra.Command{
    Use: "myapp",
    Short: "一行摘要",
    SilenceUsage: true, // 防止每个错误都显示用法
    SilenceErrors: true, // 让您控制错误输出格式
}

使用AddGroup标记帮助输出中的子命令——在引用它们的AddCommand调用之前注册组；cobra不会后续分配组。

Run家族 Cobra命令有五个按顺序执行的运行钩子：PersistentPreRunE → PreRunE → RunE → PostRunE → PersistentPostRunE 始终使用 E变体——非E形式不能返回错误。

关键规则：

• 根命令的PersistentPreRunE在每个子命令之前运行——用于配置初始化和身份验证检查。
• 子命令的PersistentPreRunE替换父命令的——如果需要同时使用两者，请显式调用父命令。
• PostRunE仅在RunE成功时运行。

参数验证器 Cobra在RunE运行之前验证位置参数。永远不要在RunE内部编写len(args)检查——这会绕过Cobra的标准错误消息和参数计数跟踪。

内置验证器：NoArgs、ExactArgs(n)、MinimumNArgs(n)、MaximumNArgs(n)、RangeArgs(min,max)、OnlyValidArgs、ExactValidArgs(n)。 组合使用MatchAll(v1, v2)。 自定义验证器：func(cmd cobra.Command, args []string) error。

标志入门 Cobra将标志解析委托给pflag。 持久标志（PersistentFlags()）由所有子命令继承；本地标志（Flags()）仅适用于声明命令。

rootCmd.PersistentFlags().StringVar(&cfgFile, "config", "", "配置文件路径")
serveCmd.Flags().IntVar(&port, "port", 8080, "监听端口")
serveCmd.MarkFlagRequired("port")
serveCmd.MarkFlagsMutuallyExclusive("json", "yaml")

补全入门 Cobra自动生成shell补全。扩展它们：

• ValidArgs []string —— 静态位置参数补全。
• ValidArgsFunction —— 动态：func(cmd, args, toComplete string) ([]string, ShellCompDirective)。
• 返回ShellCompDirectiveNoFileComp以抑制文件回退。
• RegisterFlagCompletionFunc(name, fn) —— 标志值补全。

测试命令 通过程序执行测试命令。永远不要在命令处理程序中直接使用os.Stdout / os.Stderr —— 使用cmd.OutOrStdout() / cmd.ErrOrStderr()，以便测试可以重定向输出。

func TestServeCmd(t testing.T) {
    buf := new(bytes.Buffer)
    rootCmd.SetOut(buf)
    rootCmd.SetArgs([]string{"serve"})
    // ...
}