cli: adopt Cobra cli reference style (#997)

* adapt to Cobra CLI ref style

* linting

* change multi-line reference style

* lowercase short descriptions

* Revert "lowercase short descriptions"

This reverts commit 499dc3577a.

* use 2 newlines on long description and add dots

* mark required flags

* Update cli/internal/cmd/iamcreateaws.go

Co-authored-by: Paul Meyer <49727155+katexochen@users.noreply.github.com>

* Update cli/internal/cmd/upgradeexecute.go

Co-authored-by: Paul Meyer <49727155+katexochen@users.noreply.github.com>

* Update cli/internal/cmd/upgradeexecute.go

Co-authored-by: Paul Meyer <49727155+katexochen@users.noreply.github.com>

Co-authored-by: Paul Meyer <49727155+katexochen@users.noreply.github.com>

cli/internal/cmd/configfetchmeasurements.go

@@ -30,9 +30,10 @@ func newConfigFetchMeasurementsCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "fetch-measurements",
 		Short: "Fetch measurements for configured cloud provider and image",
-		Long:  "Fetch measurements for configured cloud provider and image. A config needs to be generated first!",
-		Args:  cobra.ExactArgs(0),
-		RunE:  runConfigFetchMeasurements,
+		Long: "Fetch measurements for configured cloud provider and image.\n\n" +
+			"A config needs to be generated first.",
+		Args: cobra.ExactArgs(0),
+		RunE: runConfigFetchMeasurements,
 	}
 	cmd.Flags().StringP("url", "u", "", "alternative URL to fetch measurements from")
 	cmd.Flags().StringP("signature-url", "s", "", "alternative URL to fetch measurements' signature from")

cli/internal/cmd/iam.go

@@ -32,7 +32,7 @@ func newIAMCreateCmd() *cobra.Command {
 		Args:  cobra.ExactArgs(0),
 	}
 
-	cmd.PersistentFlags().Bool("generate-config", false, "Automatically generate a config file and fill in the required fields")
+	cmd.PersistentFlags().Bool("generate-config", false, "automatically generate a configuration file and fill in the required fields")
 
 	cmd.AddCommand(newIAMCreateAWSCmd())
 	cmd.AddCommand(newIAMCreateAzureCmd())

cli/internal/cmd/iamcreateaws.go

@@ -26,11 +26,13 @@ func newIAMCreateAWSCmd() *cobra.Command {
 		RunE:  runIAMCreateAWS,
 	}
 
-	cmd.Flags().String("prefix", "", "Name prefix for all resources.")
+	cmd.Flags().String("prefix", "", "name prefix for all resources (required)")
 	must(cobra.MarkFlagRequired(cmd.Flags(), "prefix"))
-	cmd.Flags().String("zone", "", "AWS availability zone the resources will be created in (e.g. us-east-2a). Find available zones here: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html#concepts-availability-zones. Note that we do not support every zone / region. You can find a list of all supported regions in our docs.")
+	cmd.Flags().String("zone", "", "AWS availability zone the resources will be created in, e.g. us-east-2a (required)\n"+
+		"Find available zones here: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html#concepts-availability-zones. "+
+		"Note that we do not support every zone / region. You can find a list of all supported regions in our docs.")
 	must(cobra.MarkFlagRequired(cmd.Flags(), "zone"))
-	cmd.Flags().Bool("yes", false, "Create the IAM configuration without further confirmation.")
+	cmd.Flags().Bool("yes", false, "create the IAM configuration without further confirmation")
 
 	return cmd
 }

cli/internal/cmd/iamcreateazure.go

@@ -25,13 +25,13 @@ func newIAMCreateAzureCmd() *cobra.Command {
 		RunE:  runIAMCreateAzure,
 	}
 
-	cmd.Flags().String("resourceGroup", "", "Name prefix of the two resource groups your cluster / IAM resources will be created in.")
+	cmd.Flags().String("resourceGroup", "", "name prefix of the two resource groups your cluster / IAM resources will be created in (required)")
 	must(cobra.MarkFlagRequired(cmd.Flags(), "resourceGroup"))
-	cmd.Flags().String("region", "", "Region the resources will be created in. (e.g. westus)")
+	cmd.Flags().String("region", "", "region the resources will be created in, e.g. westus (required)")
 	must(cobra.MarkFlagRequired(cmd.Flags(), "region"))
-	cmd.Flags().String("servicePrincipal", "", "Name of the service principal that will be created.")
+	cmd.Flags().String("servicePrincipal", "", "name of the service principal that will be created (required)")
 	must(cobra.MarkFlagRequired(cmd.Flags(), "servicePrincipal"))
-	cmd.Flags().Bool("yes", false, "Create the IAM configuration without further confirmation.")
+	cmd.Flags().Bool("yes", false, "create the IAM configuration without further confirmation")
 
 	return cmd
 }

cli/internal/cmd/iamcreategcp.go

@@ -37,13 +37,16 @@ func newIAMCreateGCPCmd() *cobra.Command {
 		RunE:  runIAMCreateGCP,
 	}
 
-	cmd.Flags().String("zone", "", "GCP zone the cluster will be deployed in. Find a list of available zones here: https://cloud.google.com/compute/docs/regions-zones#available")
+	cmd.Flags().String("zone", "", "GCP zone the cluster will be deployed in (required)\n"+
+		"Find a list of available zones here: https://cloud.google.com/compute/docs/regions-zones#available.")
 	must(cobra.MarkFlagRequired(cmd.Flags(), "zone"))
-	cmd.Flags().String("serviceAccountID", "", "ID for the service account that will be created. Must match ^[a-z](?:[-a-z0-9]{4,28}[a-z0-9])$")
+	cmd.Flags().String("serviceAccountID", "", "ID for the service account that will be created (required)\n"+
+		"Must match ^[a-z](?:[-a-z0-9]{4,28}[a-z0-9])$.")
 	must(cobra.MarkFlagRequired(cmd.Flags(), "serviceAccountID"))
-	cmd.Flags().String("projectID", "", "ID of the GCP project the configuration will be created in. Find it on the welcome screen of your project: https://console.cloud.google.com/welcome")
+	cmd.Flags().String("projectID", "", "ID of the GCP project the configuration will be created in (required)\n"+
+		"Find it on the welcome screen of your project: https://console.cloud.google.com/welcome.")
 	must(cobra.MarkFlagRequired(cmd.Flags(), "projectID"))
-	cmd.Flags().Bool("yes", false, "Create the IAM configuration without further confirmation.")
+	cmd.Flags().Bool("yes", false, "create the IAM configuration without further confirmation")
 
 	return cmd
 }

cli/internal/cmd/init.go

@@ -44,9 +44,10 @@ func NewInitCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "init",
 		Short: "Initialize the Constellation cluster",
-		Long:  "Initialize the Constellation cluster. Start your confidential Kubernetes.",
-		Args:  cobra.ExactArgs(0),
-		RunE:  runInitialize,
+		Long: "Initialize the Constellation cluster.\n\n" +
+			"Start your confidential Kubernetes.",
+		Args: cobra.ExactArgs(0),
+		RunE: runInitialize,
 	}
 	cmd.Flags().String("master-secret", "", "path to base64-encoded master secret")
 	cmd.Flags().Bool("conformance", false, "enable conformance mode")

cli/internal/cmd/miniup.go

@@ -34,14 +34,14 @@ func newMiniUpCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "up",
 		Short: "Create and initialize a new MiniConstellation cluster",
-		Long: "Create and initialize a new MiniConstellation cluster.\n" +
-			"A mini cluster consists of a single control-plane and worker node, hosted using QEMU/KVM.\n",
+		Long: "Create and initialize a new MiniConstellation cluster.\n\n" +
+			"A mini cluster consists of a single control-plane and worker node, hosted using QEMU/KVM.",
 		Args: cobra.ExactArgs(0),
 		RunE: runUp,
 	}
 
 	// override global flag so we don't have a default value for the config
-	cmd.Flags().String("config", "", "path to the config file to use for the cluster")
+	cmd.Flags().String("config", "", "path to the configuration file to use for the cluster")
 
 	return cmd
 }

cli/internal/cmd/recover.go

@@ -35,8 +35,8 @@ func NewRecoverCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "recover",
 		Short: "Recover a completely stopped Constellation cluster",
-		Long: "Recover a Constellation cluster by sending a recovery key to an instance in the boot stage." +
-			"\nThis is only required if instances restart without other instances available for bootstrapping.",
+		Long: "Recover a Constellation cluster by sending a recovery key to an instance in the boot stage.\n\n" +
+			"This is only required if instances restart without other instances available for bootstrapping.",
 		Args: cobra.ExactArgs(0),
 		RunE: runRecover,
 	}

cli/internal/cmd/terminate.go

@@ -25,9 +25,10 @@ func NewTerminateCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "terminate",
 		Short: "Terminate a Constellation cluster",
-		Long:  "Terminate a Constellation cluster. The cluster can't be started again, and all persistent storage will be lost.",
-		Args:  cobra.NoArgs,
-		RunE:  runTerminate,
+		Long: "Terminate a Constellation cluster.\n\n" +
+			"The cluster can't be started again, and all persistent storage will be lost.",
+		Args: cobra.NoArgs,
+		RunE: runTerminate,
 	}
 	cmd.Flags().BoolP("yes", "y", false, "terminate the cluster without further confirmation")
 	return cmd

cli/internal/cmd/upgradeexecute.go

@@ -31,9 +31,12 @@ func newUpgradeExecuteCmd() *cobra.Command {
 		RunE:  runUpgradeExecute,
 	}
 
-	cmd.Flags().Bool("helm", false, "Execute helm upgrade. This feature is still in development an may change without anounncement. Upgrades all helm charts deployed during constellation-init.")
-	cmd.Flags().BoolP("yes", "y", false, "Run upgrades without further confirmation. WARNING: might delete your resources in case you are using cert-manager in your cluster. Please read the docs.")
-	cmd.Flags().Duration("timeout", 3*time.Minute, "Change helm upgrade timeout. This feature is still in development an may change without anounncement. Might be useful for slow connections or big clusters.")
+	cmd.Flags().Bool("helm", false, "execute helm upgrade\n"+
+		"This feature is still in development an may change without announcement. Upgrades all helm charts deployed during constellation-init.")
+	cmd.Flags().BoolP("yes", "y", false, "run upgrades without further confirmation\n"+
+		"WARNING: might delete your resources in case you are using cert-manager in your cluster. Please read the docs.")
+	cmd.Flags().Duration("timeout", 3*time.Minute, "change helm upgrade timeout\n"+
+		"This feature is still in development an may change without announcement. Might be useful for slow connections or big clusters.")
 	if err := cmd.Flags().MarkHidden("helm"); err != nil {
 		panic(err)
 	}

dev-docs/conventions.md

@@ -77,7 +77,7 @@ Further we try to adhere to the following guidelines:
   ```
 
 * Use the `With()` method to add structured context to your log messages. The context tags should be easily searchable to allow for easy log filtering. Try to keep consistent tag naming!
-  
+
   Example:
 
   ```Go
@@ -169,6 +169,16 @@ In case the scope of your PR is too wide, use the alternative format.
 
 and `<Title>` starts with a capital letter.
 
+## CLI reference
+
+The command reference within the CLI should follow the following conventions:
+
+- Short description: Starts with a capital letter, beginnings of sentences, names and acronyms are capitalized, ends without a period. It should be a single sentence.
+- Long description: Starts with a capital letter, beginnings of sentences, names and acronyms are capitalized, ends with a period.
+  - If the long description contains multiple sentences, the first sentence is formatted as a long description, followed by 2 newlines and the rest of the sentences. The rest of the sentences start with a capital letter, beginnings of sentences, names and acronyms are capitalized and each sentence ends with a period.
+- Flag: Starts with a lowercase letter, beginnings of sentences, names and acronyms are capitalized, ends without a period.
+  - If a flag contains multiple sentences, the first sentence is formatted as a normal flag, followed by a newline and the rest of the sentences. The rest of the sentences start with a capital letter, beginnings of sentences, names and acronyms are capitalized and each sentence ends with a period.
+
 ## Naming convention
 
 ### Network