[CLI-2571] Update --help output to align with our Style Guide for C…

…onfluent Documentation (#2055) Co-authored-by: Brian Strauch <[email protected]> Co-authored-by: tikimims <[email protected]>
confluentinc · Jul 6, 2023 · 3e4dca0 · 3e4dca0
1 parent 524c8ee
commit 3e4dca0
Show file tree

Hide file tree

Showing 594 changed files with 747 additions and 727 deletions.
diff --git a/cmd/docs/main.go b/cmd/docs/main.go
@@ -27,7 +27,7 @@ func main() {
 	// Generate documentation for both subsets of commands: cloud and on-prem
 	configs := []*v1.Config{
 		{CurrentContext: "Cloud", Contexts: map[string]*v1.Context{"Cloud": {PlatformName: "https://confluent.cloud"}}},
-		{CurrentContext: "On-Prem", Contexts: map[string]*v1.Context{"On-Prem": {PlatformName: "https://example.com"}}},
+		{CurrentContext: "On-Premises", Contexts: map[string]*v1.Context{"On-Premises": {PlatformName: "https://example.com"}}},
 	}
 
 	tabs := make([]docs.Tab, len(configs))

diff --git a/cmd/lint/main.go b/cmd/lint/main.go
@@ -39,7 +39,9 @@ var commandRules = []linter.CommandRule{
 	linter.RequireValidExamples(),
 
 	// Soft Requirements
-	linter.RequireLengthBetween("Short", 10, 60),
+	linter.Filter(linter.RequireLengthBetween("Short", 10, 60),
+		linter.ExcludeCommand("audit-log config edit"),
+		linter.ExcludeCommand("audit-log config update")),
 }
 
 var flagRules = []linter.FlagRule{

diff --git a/internal/cmd/asyncapi/command_import.go b/internal/cmd/asyncapi/command_import.go
@@ -110,7 +110,7 @@ func newImportCommand(prerunner pcmd.PreRunner) *cobra.Command {
 
 	c := &command{pcmd.NewAuthenticatedCLICommand(cmd, prerunner)}
 	cmd.RunE = c.asyncapiImport
-	cmd.Flags().String("file", "", "Input file name.")
+	cmd.Flags().String("file", "", "Input filename.")
 	cmd.Flags().Bool("overwrite", false, "Overwrite existing topics with the same name.")
 	cmd.Flags().String("kafka-api-key", "", "Kafka cluster API key.")
 	cmd.Flags().String("schema-registry-api-key", "", "API key for Schema Registry.")

diff --git a/internal/cmd/audit-log/command_config_describe.go b/internal/cmd/audit-log/command_config_describe.go
@@ -11,8 +11,8 @@ import (
 func (c *configCommand) newDescribeCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "describe",
-		Short: "Prints the audit log configuration spec object.",
-		Long:  `Prints the audit log configuration spec object, where "spec" refers to the JSON blob that describes audit log routing rules.`,
+		Short: "Prints the audit log configuration specification object.",
+		Long:  `Prints the audit log configuration specification object, where "specification" refers to the JSON blob that describes audit log routing rules.`,
 		Args:  cobra.NoArgs,
 		RunE:  c.describe,
 	}

diff --git a/internal/cmd/audit-log/command_config_edit.go b/internal/cmd/audit-log/command_config_edit.go
@@ -17,8 +17,8 @@ import (
 func (c *configCommand) newEditCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "edit",
-		Short: "Edit the audit-log config spec interactively.",
-		Long:  "Edit the audit-log config spec object interactively, using the $EDITOR specified in your environment (for example, vim).",
+		Short: "Edit the audit-log configuration specification interactively.",
+		Long:  "Edit the audit-log configuration specification object interactively using the $EDITOR specified in your environment (for example, vim).",
 		Args:  cobra.NoArgs,
 		RunE:  c.edit,
 	}

diff --git a/internal/cmd/audit-log/command_config_update.go b/internal/cmd/audit-log/command_config_update.go
@@ -16,7 +16,7 @@ import (
 func (c *configCommand) newUpdateCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "update",
-		Short: "Submits audit-log config spec object to the API.",
+		Short: "Submits audit-log configuration specification object to the API.",
 		Long:  "Submits an audit-log configuration specification JSON object to the API.",
 		Args:  cobra.NoArgs,
 		RunE:  c.update,

diff --git a/internal/cmd/command.go b/internal/cmd/command.go
@@ -69,7 +69,7 @@ func NewConfluentCommand(cfg *v1.Config) *cobra.Command {
 	cmd.Flags().Bool("version", false, fmt.Sprintf("Show version of the %s.", pversion.FullCLIName))
 	cmd.PersistentFlags().BoolP("help", "h", false, "Show help for this command.")
 	cmd.PersistentFlags().CountP("verbose", "v", "Increase verbosity (-v for warn, -vv for info, -vvv for debug, -vvvv for trace).")
-	cmd.PersistentFlags().Bool("unsafe-trace", false, "Equivalent to -vvvv, but also log HTTP requests and responses which may contain plaintext secrets.")
+	cmd.PersistentFlags().Bool("unsafe-trace", false, "Equivalent to -vvvv, but also log HTTP requests and responses which might contain plaintext secrets.")
 
 	disableUpdateCheck := cfg.DisableUpdates || cfg.DisableUpdateCheck
 	updateClient := update.NewClient(pversion.CLIName, disableUpdateCheck)

diff --git a/internal/cmd/connect/command_cluster_create.go b/internal/cmd/connect/command_cluster_create.go
@@ -34,7 +34,7 @@ func (c *clusterCommand) newCreateCommand() *cobra.Command {
 		),
 	}
 
-	cmd.Flags().String("config-file", "", "JSON connector config file.")
+	cmd.Flags().String("config-file", "", "JSON connector configuration file.")
 	pcmd.AddClusterFlag(cmd, c.AuthenticatedCLICommand)
 	pcmd.AddContextFlag(cmd, c.CLICommand)
 	pcmd.AddEnvironmentFlag(cmd, c.AuthenticatedCLICommand)

diff --git a/internal/cmd/connect/command_cluster_update.go b/internal/cmd/connect/command_cluster_update.go
@@ -20,7 +20,7 @@ func (c *clusterCommand) newUpdateCommand() *cobra.Command {
 	}
 
 	cmd.Flags().StringSlice("config", nil, `A comma-separated list of configuration overrides ("key=value") for the connector being updated.`)
-	cmd.Flags().String("config-file", "", "JSON connector config file.")
+	cmd.Flags().String("config-file", "", "JSON connector configuration file.")
 	pcmd.AddClusterFlag(cmd, c.AuthenticatedCLICommand)
 	pcmd.AddContextFlag(cmd, c.CLICommand)
 	pcmd.AddEnvironmentFlag(cmd, c.AuthenticatedCLICommand)

diff --git a/internal/cmd/connect/command_plugin_install.go b/internal/cmd/connect/command_plugin_install.go
@@ -43,7 +43,7 @@ func (c *pluginCommand) newInstallCommand() *cobra.Command {
 				Code: "confluent connect plugin install confluentinc/kafka-connect-datagen:latest",
 			},
 			examples.Example{
-				Text: "Install the latest version of the Datagen connector in a user-specified directory and update a worker-config file.",
+				Text: "Install the latest version of the Datagen connector in a user-specified directory and update a worker configuration file.",
 				Code: "confluent connect plugin install confluentinc/kafka-connect-datagen:latest --plugin-directory $CONFLUENT_HOME/plugins --worker-configurations $CONFLUENT_HOME/etc/kafka/connect-distributed.properties",
 			},
 		),

diff --git a/internal/cmd/kafka/command_broker_describe.go b/internal/cmd/kafka/command_broker_describe.go
@@ -29,7 +29,7 @@ func (c *brokerCommand) newDescribeCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "describe [id]",
 		Short: "Describe a Kafka broker.",
-		Long:  "Describe cluster-wide or per-broker configuration values using Confluent Kafka REST.",
+		Long:  "Describe cluster-wide or per-broker configuration values.",
 		Args:  cobra.MaximumNArgs(1),
 		RunE:  c.describe,
 		Example: examples.BuildExampleString(
@@ -45,7 +45,7 @@ func (c *brokerCommand) newDescribeCommand() *cobra.Command {
 	}
 
 	cmd.Flags().Bool("all", false, "Get cluster-wide broker configurations (non-default values only).")
-	cmd.Flags().String("config-name", "", "Get a specific configuration value (pair with --all to see a cluster-wide config.")
+	cmd.Flags().String("config-name", "", "Get a specific configuration value (pair with --all to see a cluster-wide configuration.")
 	cmd.Flags().AddFlagSet(pcmd.OnPremKafkaRestSet())
 	pcmd.AddOutputFlag(cmd)
 

diff --git a/internal/cmd/kafka/command_broker_list.go b/internal/cmd/kafka/command_broker_list.go
@@ -19,7 +19,6 @@ func (c *brokerCommand) newListCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "list",
 		Short: "List Kafka brokers.",
-		Long:  "List Kafka brokers using Confluent Kafka REST.",
 		Args:  cobra.NoArgs,
 		RunE:  c.list,
 	}

diff --git a/internal/cmd/kafka/command_broker_update.go b/internal/cmd/kafka/command_broker_update.go
@@ -33,7 +33,7 @@ func (c *brokerCommand) newUpdateCommand() *cobra.Command {
 	}
 
 	cmd.Flags().StringSlice("config", nil, `A comma-separated list of configuration overrides ("key=value") for the broker being updated.`)
-	cmd.Flags().Bool("all", false, "Apply config update to all brokers in the cluster.")
+	cmd.Flags().Bool("all", false, "Apply configuration update to all brokers in the cluster.")
 	cmd.Flags().AddFlagSet(pcmd.OnPremKafkaRestSet())
 	pcmd.AddOutputFlag(cmd)
 

diff --git a/internal/cmd/kafka/command_clientconfig_create.go b/internal/cmd/kafka/command_clientconfig_create.go
@@ -129,7 +129,7 @@ func (c *createCommand) addCommand(clientConfig *clientConfig) {
 				Code: contextExample,
 			},
 			examples.Example{
-				Text: clientConfigDescription + " with arguments passed via flags.",
+				Text: clientConfigDescription + " with arguments.",
 				Code: flagExample,
 			},
 			examples.Example{

diff --git a/internal/cmd/kafka/command_link_configuration_update.go b/internal/cmd/kafka/command_link_configuration_update.go
@@ -27,7 +27,7 @@ func (c *linkCommand) newConfigurationUpdateCommand() *cobra.Command {
 		),
 	}
 
-	cmd.Flags().String(configFileFlagName, "", "Name of the file containing link config overrides. Each property key-value pair should have the format of key=value. Properties are separated by new-line characters.")
+	cmd.Flags().String(configFileFlagName, "", "Name of the file containing link configuration overrides. Each property key-value pair should have the format of key=value. Properties are separated by new-line characters.")
 	pcmd.AddClusterFlag(cmd, c.AuthenticatedCLICommand)
 	pcmd.AddEnvironmentFlag(cmd, c.AuthenticatedCLICommand)
 	pcmd.AddContextFlag(cmd, c.CLICommand)

diff --git a/internal/cmd/kafka/command_link_configuration_update_onprem.go b/internal/cmd/kafka/command_link_configuration_update_onprem.go
@@ -28,7 +28,7 @@ func (c *linkCommand) newConfigurationUpdateCommandOnPrem() *cobra.Command {
 		),
 	}
 
-	cmd.Flags().String(configFileFlagName, "", "Name of the file containing link config overrides. Each property key-value pair should have the format of key=value. Properties are separated by new-line characters.")
+	cmd.Flags().String(configFileFlagName, "", "Name of the file containing link configuration overrides. Each property key-value pair should have the format of key=value. Properties are separated by new-line characters.")
 	cmd.Flags().AddFlagSet(pcmd.OnPremKafkaRestSet())
 	pcmd.AddContextFlag(cmd, c.CLICommand)
 

diff --git a/internal/cmd/kafka/command_link_create.go b/internal/cmd/kafka/command_link_create.go
@@ -37,8 +37,8 @@ const (
 	sourceClusterIdFlagName            = "source-cluster"
 
 	authHelperMsg = "If specified, the cluster will use SASL_SSL with PLAIN SASL as its mechanism for authentication. " +
-		"If you wish to use another authentication mechanism, please do NOT specify this flag, " +
-		"and add the security configs in the config file."
+		"If you wish to use another authentication mechanism, do not specify this flag, " +
+		"and add the security configurations in the configuration file."
 )
 
 const (
@@ -77,11 +77,11 @@ func (c *linkCommand) newCreateCommand() *cobra.Command {
 	}
 
 	cmd.Flags().String(sourceClusterIdFlagName, "", "Source cluster ID.")
-	cmd.Flags().String(sourceBootstrapServerFlagName, "", "Bootstrap server address of the source cluster. Can alternatively be set in the config file using key bootstrap.servers.")
+	cmd.Flags().String(sourceBootstrapServerFlagName, "", `Bootstrap server address of the source cluster. Can alternatively be set in the configuration file using key "bootstrap.servers".`)
 	cmd.Flags().String(destinationClusterIdFlagName, "", "Destination cluster ID for source initiated cluster links.")
-	cmd.Flags().String(destinationBootstrapServerFlagName, "", `Bootstrap server address of the destination cluster for source initiated cluster links. Can alternatively be set in the config file using key "bootstrap.servers".`)
-	cmd.Flags().String(sourceApiKeyFlagName, "", "An API key for the source cluster. For links at destination cluster this is used for remote cluster authentication. For links at source cluster this is used for local cluster authentication. "+authHelperMsg)
-	cmd.Flags().String(sourceApiSecretFlagName, "", "An API secret for the source cluster. For links at destination cluster this is used for remote cluster authentication. For links at source cluster this is used for local cluster authentication. "+authHelperMsg)
+	cmd.Flags().String(destinationBootstrapServerFlagName, "", `Bootstrap server address of the destination cluster for source initiated cluster links. Can alternatively be set in the configuration file using key "bootstrap.servers".`)
+	cmd.Flags().String(sourceApiKeyFlagName, "", "An API key for the source cluster. For links at destination cluster, this is used for remote cluster authentication. For links at source cluster, this is used for local cluster authentication. "+authHelperMsg)
+	cmd.Flags().String(sourceApiSecretFlagName, "", "An API secret for the source cluster. For links at destination cluster, this is used for remote cluster authentication. For links at source cluster, this is used for local cluster authentication. "+authHelperMsg)
 	cmd.Flags().String(destinationApiKeyFlagName, "", "An API key for the destination cluster. This is used for remote cluster authentication links at the source cluster. "+authHelperMsg)
 	cmd.Flags().String(destinationApiSecretFlagName, "", "An API secret for the destination cluster. This is used for remote cluster authentication for links at the source cluster. "+authHelperMsg)
 	cmd.Flags().String(configFileFlagName, "", "Name of the file containing link configuration. Each property key-value pair should have the format of key=value. Properties are separated by new-line characters.")

diff --git a/internal/cmd/kafka/command_link_create_onprem.go b/internal/cmd/kafka/command_link_create_onprem.go
@@ -35,9 +35,9 @@ func (c *linkCommand) newCreateCommandOnPrem() *cobra.Command {
 	}
 
 	cmd.Flags().String(destinationClusterIdFlagName, "", "Destination cluster ID.")
-	cmd.Flags().String(destinationBootstrapServerFlagName, "", "Bootstrap server address of the destination cluster. Can alternatively be set in the config file using key bootstrap.servers.")
-	cmd.Flags().String(sourceApiKeyFlagName, "", "An API key for the source cluster. For links at destination cluster this is used for remote cluster authentication. For links at source cluster this is used for local cluster authentication. "+authHelperMsg)
-	cmd.Flags().String(sourceApiSecretFlagName, "", "An API secret for the source cluster. For links at destination cluster this is used for remote cluster authentication. For links at source cluster this is used for local cluster authentication. "+authHelperMsg)
+	cmd.Flags().String(destinationBootstrapServerFlagName, "", `Bootstrap server address of the destination cluster. Can alternatively be set in the configuration file using key "bootstrap.servers".`)
+	cmd.Flags().String(sourceApiKeyFlagName, "", "An API key for the source cluster. For links at destination cluster, this is used for remote cluster authentication. For links at source cluster, this is used for local cluster authentication. "+authHelperMsg)
+	cmd.Flags().String(sourceApiSecretFlagName, "", "An API secret for the source cluster. For links at destination cluster, this is used for remote cluster authentication. For links at source cluster, this is used for local cluster authentication. "+authHelperMsg)
 	cmd.Flags().String(destinationApiKeyFlagName, "", "An API key for the destination cluster. This is used for remote cluster authentication links at the source cluster. "+authHelperMsg)
 	cmd.Flags().String(destinationApiSecretFlagName, "", "An API secret for the destination cluster. This is used for remote cluster authentication for links at the source cluster. "+authHelperMsg)
 	cmd.Flags().String(configFileFlagName, "", "Name of the file containing link configuration. Each property key-value pair should have the format of key=value. Properties are separated by new-line characters.")

diff --git a/internal/cmd/kafka/command_mirror_create.go b/internal/cmd/kafka/command_mirror_create.go
@@ -40,7 +40,7 @@ func (c *mirrorCommand) newCreateCommand() *cobra.Command {
 	pcmd.AddLinkFlag(cmd, c.AuthenticatedCLICommand)
 	cmd.Flags().Int32(replicationFactorFlagName, 3, "Replication factor.")
 	cmd.Flags().String(configFileFlagName, "", "Name of a file with additional topic configuration. Each property should be on its own line with the format: key=value.")
-	cmd.Flags().String(sourceTopicFlagName, "", "Name of the topic to be mirrored over the cluster link, i.e. the source topic's name. Only required when there is a prefix configured on the link.")
+	cmd.Flags().String(sourceTopicFlagName, "", "Name of the source topic to be mirrored over the cluster link. Only required when there is a prefix configured on the link.")
 	pcmd.AddClusterFlag(cmd, c.AuthenticatedCLICommand)
 	pcmd.AddContextFlag(cmd, c.CLICommand)
 	pcmd.AddEnvironmentFlag(cmd, c.AuthenticatedCLICommand)

diff --git a/internal/cmd/kafka/command_partition_describe.go b/internal/cmd/kafka/command_partition_describe.go
@@ -20,7 +20,6 @@ func (c *partitionCommand) newDescribeCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "describe <id>",
 		Short: "Describe a Kafka partition.",
-		Long:  "Describe a Kafka partition via Confluent Kafka REST.",
 		Args:  cobra.ExactArgs(1),
 		RunE:  c.describe,
 		Example: examples.BuildExampleString(

diff --git a/internal/cmd/kafka/command_partition_list.go b/internal/cmd/kafka/command_partition_list.go
@@ -13,7 +13,7 @@ func (c *partitionCommand) newListCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "list",
 		Short: "List Kafka partitions.",
-		Long:  "List the partitions that belong to a specified topic via Confluent Kafka REST.",
+		Long:  "List the partitions that belong to a specified topic.",
 		Args:  cobra.NoArgs,
 		RunE:  c.list,
 		Example: examples.BuildExampleString(

diff --git a/internal/cmd/kafka/command_partition_reassignment_list.go b/internal/cmd/kafka/command_partition_reassignment_list.go
@@ -26,7 +26,7 @@ func (c *partitionCommand) newReassignmentListCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "list [id]",
 		Short: "List ongoing partition reassignments.",
-		Long:  "List ongoing partition reassignments for a given cluster, topic, or partition via Confluent Kafka REST.",
+		Long:  "List ongoing partition reassignments for a given cluster, topic, or partition.",
 		Args:  cobra.MaximumNArgs(1),
 		RunE:  c.reassignmentList,
 		Example: examples.BuildExampleString(

diff --git a/internal/cmd/kafka/command_replica_list.go b/internal/cmd/kafka/command_replica_list.go
@@ -52,7 +52,7 @@ func (c *replicaCommand) newListCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "list",
 		Short: "List Kafka replica statuses.",
-		Long:  "List partition-replicas statuses filtered by topic and partition via Confluent Kafka REST.",
+		Long:  "List partition-replicas statuses filtered by topic and partition.",
 		Args:  cobra.NoArgs,
 		RunE:  c.list,
 		Example: examples.BuildExampleString(

diff --git a/internal/cmd/login/command.go b/internal/cmd/login/command.go
@@ -75,13 +75,13 @@ func New(cfg *v1.Config, prerunner pcmd.PreRunner, ccloudClientFactory pauth.CCl
 	}
 	cmd.RunE = c.login
 
-	cmd.Flags().String("url", "", "Metadata Service (MDS) URL, for on-prem deployments.")
+	cmd.Flags().String("url", "", "Metadata Service (MDS) URL, for on-premises deployments.")
 	cmd.Flags().Bool("us-gov", false, "Log in to the Confluent Cloud US Gov environment.")
-	cmd.Flags().String("ca-cert-path", "", "Self-signed certificate chain in PEM format, for on-prem deployments.")
-	cmd.Flags().Bool("no-browser", false, "Do not open a browser window when authenticating via Single Sign-On (SSO).")
+	cmd.Flags().String("ca-cert-path", "", "Self-signed certificate chain in PEM format, for on-premises deployments.")
+	cmd.Flags().Bool("no-browser", false, "Do not open a browser window when authenticating using Single Sign-On (SSO).")
 	cmd.Flags().String("organization-id", "", "The Confluent Cloud organization to log in to. If empty, log in to the default organization.")
 	cmd.Flags().Bool("prompt", false, "Bypass non-interactive login and prompt for login credentials.")
-	cmd.Flags().Bool("save", false, "Save username and encrypted password (non-SSO credentials) to the configuration file in your $HOME directory, and to macOS keychain if applicable. You will be automatically logged back in when your token expires, after one hour for Confluent Cloud or after six hours for Confluent Platform.")
+	cmd.Flags().Bool("save", false, "Save username and encrypted password (non-SSO credentials) to the configuration file in your $HOME directory, and to macOS keychain if applicable. You will be logged back in when your token expires, after one hour for Confluent Cloud, or after six hours for Confluent Platform.")
 
 	cobra.CheckErr(cmd.Flags().MarkHidden("us-gov"))
 	cmd.MarkFlagsMutuallyExclusive("url", "us-gov")

diff --git a/internal/cmd/pipeline/command_create.go b/internal/cmd/pipeline/command_create.go
@@ -37,7 +37,7 @@ func (c *command) newCreateCommand() *cobra.Command {
 	pcmd.AddKsqlClusterFlag(cmd, c.AuthenticatedCLICommand)
 	cmd.Flags().Bool("use-schema-registry", false, "Add the Schema Registry cluster to the pipeline.")
 	cmd.Flags().String("sql-file", "", "Path to a KSQL file containing the pipeline's source code.")
-	cmd.Flags().StringArray("secret", []string{}, "A named secret that can be referenced in pipeline source code, e.g. \"secret_name=secret_content\".\n"+
+	cmd.Flags().StringArray("secret", []string{}, "A named secret that can be referenced in pipeline source code, for example, \"secret_name=secret_content\".\n"+
 		"This flag can be supplied multiple times. The secret mapping must have the format <secret-name>=<secret-value>,\n"+
 		"where <secret-name> consists of 1-128 lowercase, uppercase, numeric or underscore characters but may not begin with a digit.\n"+
 		"The <secret-value> can be of any format but may not be empty.")