如何使用Go Cobra库递归生成所有命令的--help帮助文本

Cobra本身没有内置一键输出所有层级命令帮助的现成命令，但可以通过其提供的命令树遍历能力，用极少量代码实现该需求，不需要修改框架源码。

核心实现原理 #

每个Cobra命令实例的*cobra.Command结构体自带三个核心能力支撑递归遍历：

• Commands()方法：返回当前命令下所有直接子命令的实例列表
• PersistentFlags()/LocalFlags()方法：分别返回当前命令的继承类持久化flag、仅当前命令生效的本地flag集合
• 命令自带的Short/Long字段存储了配置的帮助文本，Hidden/Deprecated字段可用来标记需要过滤的隐藏、废弃命令

可直接复用的实现示例 #

你可以选择给根命令加一个专属flag触发全量帮助打印，也可以新增一个隐藏的all-help子命令承载该逻辑，以下是带自定义层级排版的实现代码：

package main

import (
	"fmt"
	"os"
	"strings"

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

// 递归遍历打印命令树所有帮助信息
func printAllCommandHelp(cmd *cobra.Command, indent int) {
	prefix := strings.Repeat("  ", indent)
	// 打印分隔线和命令基础信息
	fmt.Printf("%s%s\n", prefix, strings.Repeat("=", 80-len(prefix)))
	fmt.Printf("%s▸ 命令: %s\n", prefix, cmd.CommandPath())
	if cmd.Short != "" {
		fmt.Printf("%s  简介: %s\n", prefix, cmd.Short)
	}
	if cmd.Long != "" {
		fmt.Printf("%s  详细说明:\n%s  %s\n", prefix, prefix, strings.ReplaceAll(cmd.Long, "\n", "\n"+prefix+"  "))
	}

	// 打印持久化Flags
	if cmd.PersistentFlags().HasAvailableFlags() {
		fmt.Printf("%s  ▶ 持久化Flags(子命令可继承):\n", prefix)
		cmd.PersistentFlags().VisitAll(func(f *pflag.Flag) {
			fmt.Printf("%s    --%s (%s)\n", prefix, f.Name, f.Value.Type())
			fmt.Printf("%s      默认值: %s\n", prefix, f.DefValue)
			fmt.Printf("%s      说明: %s\n", prefix, f.Usage)
		})
	}

	// 打印本地Flags
	if cmd.LocalFlags().HasAvailableFlags() {
		fmt.Printf("%s  ▶ 本地Flags(仅当前命令生效):\n", prefix)
		cmd.LocalFlags().VisitAll(func(f *pflag.Flag) {
			fmt.Printf("%s    --%s (%s)\n", prefix, f.Name, f.Value.Type())
			fmt.Printf("%s      默认值: %s\n", prefix, f.DefValue)
			fmt.Printf("%s      说明: %s\n", prefix, f.Usage)
		})
	}
	fmt.Println()

	// 递归处理所有非隐藏、非废弃子命令
	for _, subCmd := range cmd.Commands() {
		if !subCmd.Hidden && subCmd.Deprecated == "" {
			printAllCommandHelp(subCmd, indent+1)
		}
	}
}

// 初始化根命令和触发逻辑
var rootCmd = &cobra.Command{
	Use:   "mycommand",
	Short: "你的业务应用根命令",
	// 原有业务逻辑放在此处
}

func init() {
	var printAllHelp bool
	// 给根命令加全量帮助触发flag
	rootCmd.PersistentFlags().BoolVar(&printAllHelp, "all-help", false, "打印所有层级命令、Flags及对应帮助文本")
	rootCmd.PersistentPreRun = func(cmd *cobra.Command, args []string) {
		if printAllHelp {
			printAllCommandHelp(rootCmd, 0)
			os.Exit(0)
		}
	}

	// 以下是原有子命令定义示例
	cmd1 := &cobra.Command{
		Use:   "cmd1",
		Short: "首个测试子命令",
		Long:  "这是cmd1的详细帮助文本，用来验证全量帮助的递归打印效果",
	}
	cmd1.Flags().String("demo-flag", "default_val", "cmd1专属的测试flag")
	rootCmd.AddCommand(cmd1)
}

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

使用说明 #

编译应用后执行mycommand --all-help，就会按缩进层级输出从根命令开始所有命令的路径、简介、详细说明、所有flag的类型、默认值和帮助文本。
如果偏好Cobra原生的单命令帮助格式，只需要把递归逻辑里自定义打印的部分替换为cmd.Help()调用，再自行调整层级分隔格式即可。

内容的提问来源于stack exchange，提问作者Mark Harrison