feat: break out required and optional flags in subcommand help (#262)

* add operation use template to break out required and optional flags

* add templates in execute not init

cmd/resources/resource_cmds.go

@@ -2285,12 +2285,6 @@ func AddAllResourceCmds(
 				Description: "Where to start in the list. Use this with pagination. For example, an offset of 10 skips the first ten items and then returns the next items in the list, up to the query `limit`.",
 				Type:        "integer",
 			},
-			{
-				Name:        "archived",
-				In:          "query",
-				Description: "Deprecated, use `filter=archived:true` instead. A boolean to filter the list to archived flags. When this is absent, only unarchived flags will be returned",
-				Type:        "boolean",
-			},
 			{
 				Name:        "summary",
 				In:          "query",
@@ -4478,12 +4472,6 @@ func AddAllResourceCmds(
 				Description: "Specifies the maximum number of items in the collection to return (max: 50, default: 20)",
 				Type:        "integer",
 			},
-			{
-				Name:        "offset",
-				In:          "query",
-				Description: "Deprecated, use `searchAfter` instead. Specifies the first item to return in the collection.",
-				Type:        "integer",
-			},
 			{
 				Name:        "after",
 				In:          "query",

cmd/resources/resources.go

@@ -135,6 +135,9 @@ func GetTemplateData(fileName string) (TemplateData, error) {
 			for _, p := range op.Parameters {
 				if p.Value != nil {
 					// TODO: confirm if we only have one type per param b/c somehow this is a slice
+					if strings.Contains(p.Value.Description, "Deprecated") {
+						continue
+					}
 					types := *p.Value.Schema.Value.Type
 					param := Param{
 						Name:        strcase.ToKebab(p.Value.Name),
@@ -253,6 +256,7 @@ func (op *OperationCmd) initFlags() error {
 			if err != nil {
 				return err
 			}
+			op.cmd.Flags().SetAnnotation(flagName, "required", []string{"true"})
 		}
 
 		err := viper.BindPFlag(flagName, op.cmd.Flags().Lookup(flagName))
@@ -352,10 +356,49 @@ func NewOperationCmd(parentCmd *cobra.Command, client resources.Client, op Opera
 		Use:   op.Use,
 	}
 
+	cmd.SetUsageTemplate(operationUsageTemplate())
+
 	opCmd.cmd = cmd
 	_ = opCmd.initFlags()
 
 	parentCmd.AddCommand(cmd)
 
 	return cmd
 }
+
+func operationUsageTemplate() string {
+	return fmt.Sprint(`Usage:{{if .Runnable}}
+  {{.UseLine}}{{end}}{{if .HasAvailableSubCommands}}
+  {{.CommandPath}} [command]{{end}}{{if gt (len .Aliases) 0}}
+
+Aliases:
+  {{.NameAndAliases}}{{end}}{{if .HasExample}}
+
+Examples:
+{{.Example}}{{end}}{{if .HasAvailableSubCommands}}{{$cmds := .Commands}}{{if eq (len .Groups) 0}}
+
+Available Commands:{{range $cmds}}{{if (or .IsAvailableCommand (eq .Name "help"))}}
+  {{rpad .Name .NamePadding }} {{.Short}}{{end}}{{end}}{{else}}{{range $group := .Groups}}
+
+{{.Title}}{{range $cmds}}{{if (and (eq .GroupID $group.ID) (or .IsAvailableCommand (eq .Name "help")))}}
+  {{rpad .Name .NamePadding }} {{.Short}}{{end}}{{end}}{{end}}{{if not .AllChildCommandsHaveGroup}}
+
+Additional Commands:{{range $cmds}}{{if (and (eq .GroupID "") (or .IsAvailableCommand (eq .Name "help")))}}
+  {{rpad .Name .NamePadding }} {{.Short}}{{end}}{{end}}{{end}}{{end}}{{end}}{{if .HasAvailableLocalFlags}}
+
+Required flags:
+{{WrappedRequiredFlagUsages . | trimTrailingWhitespaces}}
+
+Optional flags:
+{{WrappedOptionalFlagUsages . | trimTrailingWhitespaces}}
+
+Global Flags:
+{{rpad "  -h, --help" 29}} Help for this command
+{{.InheritedFlags.FlagUsages | trimTrailingWhitespaces}}{{end}}{{if .HasHelpSubCommands}}
+
+Additional help topics:{{range .Commands}}{{if .IsAdditionalHelpTopicCommand}}
+  {{rpad .CommandPath .CommandPathPadding}} {{.Short}}{{end}}{{end}}{{end}}{{if .HasAvailableSubCommands}}
+
+Use "{{.CommandPath}} [command] --help" for more information about a command.{{end}}
+`)
+}

cmd/root.go

@@ -217,6 +217,8 @@ See each command's help for details on how to use the generated script.`, rootCm
 		rootCmd.Cmd().AddCommand(completionCmd)
 	}
 
+	cobra.AddTemplateFunc("WrappedRequiredFlagUsages", WrappedRequiredFlagUsages)
+	cobra.AddTemplateFunc("WrappedOptionalFlagUsages", WrappedOptionalFlagUsages)
 	rootCmd.cmd.SetUsageTemplate(getUsageTemplate())
 
 	err = rootCmd.Execute()

cmd/templates.go

@@ -1,5 +1,11 @@
 package cmd
 
+import (
+	"github.com/spf13/cobra"
+	"github.com/spf13/pflag"
+	"golang.org/x/term"
+)
+
 func getUsageTemplate() string {
 	return `Usage:
   {{.CommandPath}} [command]
@@ -21,3 +27,39 @@ Flags:
 {{.LocalFlags.FlagUsages | trimTrailingWhitespaces}}
 `
 }
+
+func WrappedRequiredFlagUsages(cmd *cobra.Command) string {
+	nonRequestParamsFlags := pflag.NewFlagSet("request", pflag.ExitOnError)
+
+	cmd.LocalFlags().VisitAll(func(flag *pflag.Flag) {
+		if _, ok := flag.Annotations["required"]; ok {
+			nonRequestParamsFlags.AddFlag(flag)
+		}
+	})
+
+	return nonRequestParamsFlags.FlagUsagesWrapped(getTerminalWidth())
+}
+
+func WrappedOptionalFlagUsages(cmd *cobra.Command) string {
+	nonRequestParamsFlags := pflag.NewFlagSet("request", pflag.ExitOnError)
+
+	cmd.LocalFlags().VisitAll(func(flag *pflag.Flag) {
+		_, ok := flag.Annotations["required"]
+		if !ok && flag.Name != "help" {
+			nonRequestParamsFlags.AddFlag(flag)
+		}
+	})
+
+	return nonRequestParamsFlags.FlagUsagesWrapped(getTerminalWidth())
+}
+
+func getTerminalWidth() int {
+	var width int
+
+	width, _, err := term.GetSize(0)
+	if err != nil {
+		width = 80
+	}
+
+	return width
+}