Merge pull request #128 from cyberark/consistent-help

Make command help more consistent

CHANGELOG.md

@@ -15,6 +15,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 ### Fixed
 - Fixed piping input to `conjur init` confirmation prompts
   [cyberark/conjur-cli-go#127](https://github.com/cyberark/conjur-cli-go/pull/127)
+- Made command help text more consistent
+  [cyberark/conjur-cli-go#123](https://github.com/cyberark/conjur-cli-go/pull/123)
 
 ## [8.0.7] - 2023-04-18
 

pkg/cmd/authenticate.go

@@ -23,7 +23,7 @@ type authenticateClientFactoryFunc func(*cobra.Command) (authenticateClient, err
 func newAuthenticateCommand(clientFactory authenticateClientFactoryFunc) *cobra.Command {
 	authenticateCmd := &cobra.Command{
 		Use:          "authenticate",
-		Short:        "Obtains an access token for the currently logged-in user.",
+		Short:        "Obtain an access token for the currently logged-in user",
 		SilenceUsage: true,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			conjurClient, err := clientFactory(cmd)

pkg/cmd/hostfactory.go

@@ -201,7 +201,7 @@ Examples:
 	tokensCreateCmd.Flags().Lookup("duration-hours").Hidden = false
 	tokensCreateCmd.Flags().Lookup("duration-minutes").Hidden = false
 
-	tokensCreateCmd.Flags().StringP("hostfactory-id", "i", "", "Host factory id.")
+	tokensCreateCmd.Flags().StringP("hostfactory-id", "i", "", "Host factory id")
 
 	// BEGIN COMPATIBILITY WITH PYTHON CLI
 	// Adds support for 'hostfactoryid' flag to 'hostfactory tokens create' command

pkg/cmd/init.go

@@ -244,8 +244,8 @@ func writeFile(filePath string, fileContents []byte, forceFileOverwrite bool) er
 func newInitCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "init",
-		Short: "Use the init command to initialize the Conjur CLI with a Conjur endpoint.",
-		Long: `Use the init command to initialize the Conjur CLI with a Conjur endpoint.
+		Short: "Initialize the Conjur CLI with a Conjur server",
+		Long: `Initialize the Conjur CLI with a Conjur server.
 
 The init command creates a configuration file (.conjurrc) that contains the details for connecting to Conjur. This file is located under the user's root directory.`,
 		SilenceUsage: true,
@@ -269,7 +269,7 @@ The init command creates a configuration file (.conjurrc) that contains the deta
 	cmd.Flags().BoolP("self-signed", "s", false, "Allow self-signed certificates (insecure)")
 	cmd.Flags().BoolP("insecure", "i", false, "Allow non-HTTPS connections (insecure)")
 	cmd.Flags().Bool("force-netrc", false, "Use a file-based credential storage rather than OS-native keystore (for compatibility with Summon)")
-	cmd.Flags().Bool("force", false, "Force overwrite of existing file")
+	cmd.Flags().Bool("force", false, "Force overwrite of existing configuration file")
 
 	return cmd
 }

pkg/cmd/login.go

@@ -56,12 +56,12 @@ func getLoginCmdFlagValues(cmd *cobra.Command) (loginCmdFlagValues, error) {
 func newLoginCmd(funcs loginCmdFuncs) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "login",
-		Short: "Authenticate with Conjur using the provided identity and password.",
+		Short: "Authenticate with Conjur using the provided identity and password",
 		Long: `Authenticate with Conjur using the provided identity and password.
 
-The command will prompt for identity and password if they are not provided via flag.
+The command will prompt for identity and password if they are not provided via flags.
 
-On successful login, the password is exchanged for the user's API key, which is cached in the operating system user's .netrc file. Subsequent commands will authenticate using the cached credentials. To switch users, login again using new credentials. To erase credentials, use the 'logout' command.
+On successful login, the password is exchanged for the user's API key, which is cached in the operating system user's credential storage or .netrc file. Subsequent commands will authenticate using the cached credentials. To switch users, login again using new credentials. To erase credentials, use the 'logout' command.
 
 Examples:
 

pkg/cmd/logout.go

@@ -11,8 +11,8 @@ type configLoaderFn func() (conjurapi.Config, error)
 func newLogoutCmd(loadConfig configLoaderFn) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:          "logout",
-		Short:        "Logs out a user and deletes cached credentials.",
-		Long:         `Logs out a user and deletes the credentials cached in the operating system user's .netrc file.`,
+		Short:        "Log out the user and delete cached credentials.",
+		Long:         `Log out the user and delete the credentials cached in the operating system user's credential storage or .netrc file.`,
 		SilenceUsage: true,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			config, err := loadConfig()

pkg/cmd/policy.go

@@ -69,7 +69,7 @@ func loadPolicyCommandRunner(
 func newPolicyCommand(clientFactory policyClientFactoryFunc) *cobra.Command {
 	policyCmd := &cobra.Command{
 		Use:   "policy",
-		Short: "Use the policy command to manage Conjur policies",
+		Short: "Manage Conjur policies",
 	}
 
 	policyCmd.PersistentFlags().StringP("branch", "b", "", "The parent policy branch")

pkg/cmd/pubkeys.go

@@ -19,8 +19,8 @@ type pubKeysClientFactoryFunc func(*cobra.Command) (pubKeysClient, error)
 func newPubKeysCommand(clientFactory pubKeysClientFactoryFunc) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "pubkeys <username>",
-		Short: "Displays the public keys associated with a user",
-		Long: `Displays the public keys for a given [username].
+		Short: "Display the public keys associated with a user",
+		Long: `Display the public keys for a given [username].
 
 Examples:
 - conjur pubkeys alice`,

pkg/cmd/resource.go

@@ -30,8 +30,8 @@ var resourceCmd = &cobra.Command{
 func newResourceExistsCmd(clientFactory resourceClientFactoryFunc) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "exists",
-		Short: "Checks if a resource exists",
-		Long: `Checks if a resource exists, given a [resource-id].
+		Short: "Check if a resource exists",
+		Long: `Check if a resource exists, given a [resource-id].
 		
 Examples:
 

pkg/cmd/role.go

@@ -31,8 +31,8 @@ var roleCmd = &cobra.Command{
 func newRoleExistsCmd(clientFactory roleClientFactoryFunc) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "exists",
-		Short: "Checks if a role exists",
-		Long: `Checks if a role exists
+		Short: "Check if a role exists",
+		Long: `Check if a role exists
 		
 This command requires a [role-id] and includes an optional [--json] 
 flag to return a JSON-formatted result.

pkg/cmd/variable.go

@@ -15,7 +15,7 @@ func newVariableCmd(
 ) *cobra.Command {
 	variableCmd := &cobra.Command{
 		Use:   "variable",
-		Short: "Use the variable command to manage Conjur variables",
+		Short: "Manage Conjur variables",
 	}
 
 	variableGetCmd := newVariableGetCmd(getClientFactory)
@@ -84,8 +84,8 @@ func printMultilineResults(cmd *cobra.Command, secrets map[string][]byte) error
 func newVariableGetCmd(clientFactory variableGetClientFactoryFunc) *cobra.Command {
 	return &cobra.Command{
 		Use:   "get",
-		Short: "Use the get subcommand to get the value of one or more Conjur variables",
-		Long: `Use the get subcommand to get the value of one or more Conjur variables
+		Short: "Get the value of one or more Conjur variables",
+		Long: `Get the value of one or more Conjur variables.
 
 Examples:
 - conjur variable get -i secret
@@ -137,8 +137,13 @@ Examples:
 
 func newVariableSetCmd(clientFactory variableSetClientFactoryFunc) *cobra.Command {
 	return &cobra.Command{
-		Use:          "set",
-		Short:        "Use the set subcommand to set the value of a Conjur variable",
+		Use:   "set",
+		Short: "Set the value of a Conjur variable",
+		Long: `Set the value of a Conjur variable.
+
+Examples:
+- conjur variable set -i secret -v value
+		`,
 		SilenceUsage: true,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			id, err := cmd.Flags().GetString("id")

pkg/cmd/whoami.go

@@ -7,14 +7,6 @@ import (
 	"github.com/spf13/cobra"
 )
 
-type whoamiResponse struct {
-	ClientIP      string `json:"client_ip"`
-	UserAgent     string `json:"user_agent"`
-	Account       string `json:"account"`
-	Username      string `json:"username"`
-	TokenIssuedAt string `json:"token_issued_at"`
-}
-
 type whoamiClient interface {
 	WhoAmI() ([]byte, error)
 }
@@ -28,7 +20,7 @@ type whoamiClientFactoryFunc func(*cobra.Command) (whoamiClient, error)
 func newWhoamiCommand(clientFactory whoamiClientFactoryFunc) *cobra.Command {
 	return &cobra.Command{
 		Use:          "whoami",
-		Short:        "Displays info about the logged in user",
+		Short:        "Display info about the logged in user",
 		SilenceUsage: true,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			client, err := clientFactory(cmd)