chore: improve help command output (#968)

* chore: improve help command output

* chore: code review improvements

cmd/config.go

@@ -23,8 +23,9 @@ import (
 
 func init() {
 	configCmd := &cobra.Command{
-		Use:   "config",
-		Short: "Show system configuration",
+		Use:     "config",
+		GroupID: "broker",
+		Short:   "Show system configuration",
 		Long: `
 The GCP Service Broker can be configured using both environment variables and
 configuration files.

cmd/local.go

@@ -8,14 +8,22 @@ import (
 	"github.com/spf13/viper"
 )
 
+const localID = "local"
+
 func init() {
 	var params, plan, service, example string
 	var all bool
 
+	rootCmd.AddGroup(&cobra.Group{
+		ID:    localID,
+		Title: "Local Development",
+	})
+
 	marketplaceCmd := &cobra.Command{
-		Use:   "marketplace",
-		Short: "EXPERIMENTAL AND SUBJECT TO BREAKING CHANGE: list services and plans",
-		Args:  cobra.ExactArgs(0),
+		Use:     "marketplace",
+		GroupID: localID,
+		Short:   "EXPERIMENTAL AND SUBJECT TO BREAKING CHANGE: list services and plans",
+		Args:    cobra.ExactArgs(0),
 		Run: func(cmd *cobra.Command, args []string) {
 			local.Marketplace(viper.GetString(pakCachePath))
 		},
@@ -24,9 +32,10 @@ func init() {
 
 	const paramsFlag = "c"
 	createServiceCmd := &cobra.Command{
-		Use:   "create-service SERVICE PLAN NAME",
-		Short: "EXPERIMENTAL AND SUBJECT TO BREAKING CHANGE: create a service instance",
-		Args:  cobra.ExactArgs(3),
+		Use:     "create-service SERVICE PLAN NAME",
+		GroupID: localID,
+		Short:   "EXPERIMENTAL AND SUBJECT TO BREAKING CHANGE: create a service instance",
+		Args:    cobra.ExactArgs(3),
 		Run: func(cmd *cobra.Command, args []string) {
 			local.CreateService(args[0], args[1], args[2], params, viper.GetString(pakCachePath))
 		},
@@ -35,19 +44,21 @@ func init() {
 	rootCmd.AddCommand(createServiceCmd)
 
 	servicesCmd := &cobra.Command{
-		Use:   "services",
-		Short: "EXPERIMENTAL AND SUBJECT TO BREAKING CHANGE: list service instances",
-		Args:  cobra.ExactArgs(0),
+		Use:     "services",
+		GroupID: localID,
+		Short:   "EXPERIMENTAL AND SUBJECT TO BREAKING CHANGE: list service instances",
+		Args:    cobra.ExactArgs(0),
 		Run: func(cmd *cobra.Command, args []string) {
 			local.Services(viper.GetString(pakCachePath))
 		},
 	}
 	rootCmd.AddCommand(servicesCmd)
 
 	serviceCmd := &cobra.Command{
-		Use:   "service",
-		Short: "EXPERIMENTAL AND SUBJECT TO BREAKING CHANGE: provides information on a service instance",
-		Args:  cobra.ExactArgs(1),
+		Use:     "service",
+		GroupID: localID,
+		Short:   "EXPERIMENTAL AND SUBJECT TO BREAKING CHANGE: provides information on a service instance",
+		Args:    cobra.ExactArgs(1),
 		Run: func(cmd *cobra.Command, args []string) {
 			local.Service(args[0], viper.GetString(pakCachePath))
 		},
@@ -56,9 +67,10 @@ func init() {
 
 	const planFlag = "p"
 	updateServiceCmd := &cobra.Command{
-		Use:   "update-service NAME",
-		Short: "EXPERIMENTAL AND SUBJECT TO BREAKING CHANGE: update a service instance",
-		Args:  cobra.ExactArgs(1),
+		Use:     "update-service NAME",
+		GroupID: localID,
+		Short:   "EXPERIMENTAL AND SUBJECT TO BREAKING CHANGE: update a service instance",
+		Args:    cobra.ExactArgs(1),
 		Run: func(cmd *cobra.Command, args []string) {
 			local.UpdateService(args[0], plan, params, viper.GetString(pakCachePath))
 		},
@@ -68,29 +80,32 @@ func init() {
 	rootCmd.AddCommand(updateServiceCmd)
 
 	upgradeServiceCmd := &cobra.Command{
-		Use:   "upgrade-service NAME PREVIOUS_VERSION",
-		Short: "EXPERIMENTAL AND SUBJECT TO BREAKING CHANGE: upgrade a service instance from PREVIOUS_VERSION to current version",
-		Args:  cobra.ExactArgs(2),
+		Use:     "upgrade-service NAME PREVIOUS_VERSION",
+		GroupID: localID,
+		Short:   "EXPERIMENTAL AND SUBJECT TO BREAKING CHANGE: upgrade a service instance from PREVIOUS_VERSION to current version",
+		Args:    cobra.ExactArgs(2),
 		Run: func(cmd *cobra.Command, args []string) {
 			local.UpgradeService(args[0], args[1], viper.GetString(pakCachePath))
 		},
 	}
 	rootCmd.AddCommand(upgradeServiceCmd)
 
 	deleteServiceCmd := &cobra.Command{
-		Use:   "delete-service NAME",
-		Short: "EXPERIMENTAL AND SUBJECT TO BREAKING CHANGE: delete a service instance",
-		Args:  cobra.ExactArgs(1),
+		Use:     "delete-service NAME",
+		GroupID: localID,
+		Short:   "EXPERIMENTAL AND SUBJECT TO BREAKING CHANGE: delete a service instance",
+		Args:    cobra.ExactArgs(1),
 		Run: func(cmd *cobra.Command, args []string) {
 			local.DeleteService(args[0], viper.GetString(pakCachePath))
 		},
 	}
 	rootCmd.AddCommand(deleteServiceCmd)
 
 	createServiceKeyCmd := &cobra.Command{
-		Use:   "create-service-key SERVICE_INSTANCE SERVICE_KEY",
-		Short: "EXPERIMENTAL AND SUBJECT TO BREAKING CHANGE: create a service key",
-		Args:  cobra.ExactArgs(2),
+		Use:     "create-service-key SERVICE_INSTANCE SERVICE_KEY",
+		GroupID: localID,
+		Short:   "EXPERIMENTAL AND SUBJECT TO BREAKING CHANGE: create a service key",
+		Args:    cobra.ExactArgs(2),
 		Run: func(cmd *cobra.Command, args []string) {
 			local.CreateServiceKey(args[0], args[1], params, viper.GetString(pakCachePath))
 		},
@@ -99,39 +114,43 @@ func init() {
 	rootCmd.AddCommand(createServiceKeyCmd)
 
 	serviceKeyCmd := &cobra.Command{
-		Use:   "service-key SERVICE_INSTANCE SERVICE_KEY",
-		Short: "EXPERIMENTAL AND SUBJECT TO BREAKING CHANGE: print a service key",
-		Args:  cobra.ExactArgs(2),
+		Use:     "service-key SERVICE_INSTANCE SERVICE_KEY",
+		GroupID: localID,
+		Short:   "EXPERIMENTAL AND SUBJECT TO BREAKING CHANGE: print a service key",
+		Args:    cobra.ExactArgs(2),
 		Run: func(cmd *cobra.Command, args []string) {
 			local.ServiceKey(args[0], args[1])
 		},
 	}
 	rootCmd.AddCommand(serviceKeyCmd)
 
 	serviceKeysCmd := &cobra.Command{
-		Use:   "service-keys NAME",
-		Short: "EXPERIMENTAL AND SUBJECT TO BREAKING CHANGE: list service keys for a service instance",
-		Args:  cobra.ExactArgs(1),
+		Use:     "service-keys NAME",
+		GroupID: localID,
+		Short:   "EXPERIMENTAL AND SUBJECT TO BREAKING CHANGE: list service keys for a service instance",
+		Args:    cobra.ExactArgs(1),
 		Run: func(cmd *cobra.Command, args []string) {
 			local.ServiceKeys(args[0])
 		},
 	}
 	rootCmd.AddCommand(serviceKeysCmd)
 
 	deleteServiceKeyCmd := &cobra.Command{
-		Use:   "delete-service-key SERVICE_INSTANCE SERVICE_KEY",
-		Short: "EXPERIMENTAL AND SUBJECT TO BREAKING CHANGE: delete a service key",
-		Args:  cobra.ExactArgs(2),
+		Use:     "delete-service-key SERVICE_INSTANCE SERVICE_KEY",
+		GroupID: localID,
+		Short:   "EXPERIMENTAL AND SUBJECT TO BREAKING CHANGE: delete a service key",
+		Args:    cobra.ExactArgs(2),
 		Run: func(cmd *cobra.Command, args []string) {
 			local.DeleteServiceKey(args[0], args[1], viper.GetString(pakCachePath))
 		},
 	}
 	rootCmd.AddCommand(deleteServiceKeyCmd)
 
 	listExamplesCmd := &cobra.Command{
-		Use:   "examples",
-		Short: "EXPERIMENTAL AND SUBJECT TO BREAKING CHANGE: list example tests",
-		Args:  cobra.ExactArgs(0),
+		Use:     "examples",
+		GroupID: localID,
+		Short:   "EXPERIMENTAL AND SUBJECT TO BREAKING CHANGE: list example tests",
+		Args:    cobra.ExactArgs(0),
 		Run: func(cmd *cobra.Command, args []string) {
 			local.ListExamples(viper.GetString(pakCachePath))
 		},
@@ -144,9 +163,10 @@ func init() {
 		allFlag     = "all"
 	)
 	runExamplesCmd := &cobra.Command{
-		Use:   "run-examples",
-		Short: "EXPERIMENTAL AND SUBJECT TO BREAKING CHANGE: run example tests",
-		Args:  cobra.ExactArgs(0),
+		Use:     "run-examples",
+		GroupID: localID,
+		Short:   "EXPERIMENTAL AND SUBJECT TO BREAKING CHANGE: run example tests",
+		Args:    cobra.ExactArgs(0),
 		Run: func(cmd *cobra.Command, args []string) {
 			if !all && service == "" && example == "" {
 				log.Fatalln("specify --service-name and/or --example-name, or --all to run all the tests")

cmd/pak.go

@@ -32,9 +32,17 @@ const (
 func init() {
 	_ = viper.BindEnv(pakCachePath, "PAK_BUILD_CACHE_PATH")
 
+	pakGroup := &cobra.Group{
+		ID:    "pak",
+		Title: "Brokerpak Development",
+	}
+
+	rootCmd.AddGroup(pakGroup)
+
 	pakCmd := &cobra.Command{
-		Use:   "pak",
-		Short: "interact with user-defined service definition bundles",
+		Use:     "pak",
+		GroupID: "pak",
+		Short:   "interact with user-defined service definition bundles",
 		Long: `Lets you create, validate, and view service definition bundles.
 
 A service definition bundle is a zip file containing all the elements needed

cmd/purge.go

@@ -13,8 +13,9 @@ import (
 
 func init() {
 	purgeCmd := &cobra.Command{
-		Use:   "purge",
-		Short: "purge a service instance from the database",
+		Use:     "purge",
+		GroupID: "broker",
+		Short:   "purge a service instance from the database",
 		Long: `Lets you remove a service instance from the Cloud Service Broker database.
 
 It does not actually delete the service instance, it just removes all references from the database.

cmd/purge_binding.go

@@ -13,8 +13,9 @@ import (
 
 func init() {
 	purgeCmd := &cobra.Command{
-		Use:   "purge-binding",
-		Short: "purge a service binding from the database",
+		Use:     "purge-binding",
+		GroupID: "broker",
+		Short:   "purge a service binding from the database",
 		Long: `Lets you remove a service binding (or service key) from the Cloud Service Broker database.
 
 It does not actually delete the service binding, it just removes all references from the database.

cmd/root.go

@@ -27,6 +27,11 @@ import (
 
 var cfgFile string
 
+var brokerGroup = &cobra.Group{
+	ID:    "broker",
+	Title: "Broker Operation",
+}
+
 var rootCmd = &cobra.Command{
 	Use:   "cloud-service-broker",
 	Short: "GCP Service Broker is an OSB compatible service broker",
@@ -50,6 +55,7 @@ func Execute() {
 func init() {
 	cobra.OnInitialize(initConfig)
 	rootCmd.PersistentFlags().StringVar(&cfgFile, "config", "", "Configuration file to be read")
+	rootCmd.AddGroup(brokerGroup)
 	viper.SetEnvPrefix(utils.EnvironmentVarPrefix)
 	viper.SetEnvKeyReplacer(utils.PropertyToEnvReplacer)
 	viper.AutomaticEnv()

cmd/serve.go

@@ -54,8 +54,9 @@ var cfCompatibilityToggle = toggles.Features.Toggle("enable-cf-sharing", false,
 
 func init() {
 	rootCmd.AddCommand(&cobra.Command{
-		Use:   "serve",
-		Short: "Start the service broker",
+		Use:     "serve",
+		GroupID: "broker",
+		Short:   "Start the service broker",
 		Long: `Starts the service broker listening on a port defined by the
 	PORT environment variable.`,
 		Run: func(cmd *cobra.Command, args []string) {

cmd/tf.go

@@ -39,9 +39,10 @@ func init() {
 	)
 
 	tfCmd := &cobra.Command{
-		Use:   "tf",
-		Short: "Interact with the Terraform backend",
-		Long:  `Interact with the Terraform backend`,
+		Use:     "tf",
+		GroupID: "broker",
+		Short:   "Interact with the Terraform backend",
+		Long:    `Interact with the Terraform backend`,
 		PersistentPreRunE: func(cmd *cobra.Command, args []string) (err error) {
 			logger := utils.NewLogger("tf")
 			db := dbservice.New(logger)

cmd/version.go

@@ -24,9 +24,10 @@ import (
 
 func init() {
 	versionCmd := &cobra.Command{
-		Use:   "version",
-		Short: "Show the version info of the broker",
-		Long:  `Show the version info of the broker`,
+		Use:     "version",
+		GroupID: "broker",
+		Short:   "Show the version info of the broker",
+		Long:    `Show the version info of the broker`,
 		Run: func(cmd *cobra.Command, args []string) {
 			fmt.Println(utils.Version)
 		},