如何在Cobra命令行工具的帮助文档中展示位置参数说明

解决方案 #

你只需要修改cobra.Command结构体的Use字段即可，Cobra的Use字段本身就是用来定义命令的使用语法，其中的参数占位符会直接渲染到帮助文档的Usage部分，无需自定义复杂的帮助模板。

修改后的代码示例 #

var (
    deleteCustomerCommand = &cobra.Command{
        // 仅需修改此处Use字段，追加参数占位符
        Use:        "delete customer_id [...customer_id]",
        Short:      "Delete Stripe customer(s) by ids.",
        Args:       cobra.MinimumNArgs(1),
        ArgAliases: []string{"stripe_customer_id"},
        // 可选：补充Example字段提供实际使用示例，降低用户理解成本
        Example: `  # 删除单个客户
  ./my-app stripe customers delete -k $STRIPE_API_KEY cus_xxx
  # 批量删除多个客户
  ./my-app stripe customers delete -k $STRIPE_API_KEY cus_xxx cus_yyy cus_zzz`,
        PreRun: func(cmd *cobra.Command, args []string) {

        },
        Run: func(cmd *cobra.Command, args []string) {
            log.Printf("IDs: %v", args)
        },
    }
)

最终效果 #

修改后再运行无参命令或者查看帮助，Usage部分就会自动渲染为你预期的格式：

Error: requires at least 1 arg(s), only received 0
Usage:
  my-app stripe customers delete [flags] customer_id [...customer_id]

Examples:
  # 删除单个客户
  ./my-app stripe customers delete -k $STRIPE_API_KEY cus_xxx
  # 批量删除多个客户
  ./my-app stripe customers delete -k $STRIPE_API_KEY cus_xxx cus_yyy cus_zzz

Flags:
  -h, --help                    help for delete
  -k, --stripe-api-key string   The Stripe API key. [env: stripe_api_key]

2021/09/13 12:00:39 Failed to execute command: requires at least 1 arg(s), only received 0

内容的提问来源于stack exchange，提问作者Naftuli Kay