standardize commands help wording and conventions (#74)

* fix clients wording

* apis wording

* fix try wording

* logs doc

* rules wording

* actions wording

* connections wording

* more minor changes in favor of consistency

* fix merge

* solve merge conflicts

internal/cli/actions.go

@@ -29,7 +29,7 @@ const (
 func actionsCmd(cli *cli) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "actions",
-		Short: "manage resources for actions.",
+		Short: "Manage resources for actions",
 	}
 
 	cmd.SetUsageTemplate(resourceUsageTemplate())
@@ -47,7 +47,7 @@ func actionsCmd(cli *cli) *cobra.Command {
 func triggersCmd(cli *cli) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "triggers",
-		Short: "manage resources for action triggers.",
+		Short: "Manage resources for action triggers",
 	}
 
 	cmd.SetUsageTemplate(resourceUsageTemplate())
@@ -61,11 +61,11 @@ func triggersCmd(cli *cli) *cobra.Command {
 func listActionsCmd(cli *cli) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "list",
-		Short: "Lists your existing actions",
-		Long: `$ auth0 actions list
-Lists your existing actions. To create one try:
+		Short: "List existing actions",
+		Long: `auth0 actions list
+List existing actions. To create one try:
 
-    $ auth0 actions create
+    auth0 actions create
 `,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			list, err := cli.api.Action.List()
@@ -115,7 +115,7 @@ func testActionCmd(cli *cli) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "test",
 		Short: "Test an action draft against a payload",
-		Long:  `$ auth0 actions test --id <actionid> --file <payload.json>`,
+		Long:  `auth0 actions test --id <actionid> --file <payload.json>`,
 		PreRun: func(cmd *cobra.Command, args []string) {
 			prepareInteractivity(cmd)
 		},
@@ -180,8 +180,8 @@ func deployActionCmd(cli *cli) *cobra.Command {
 
 	cmd := &cobra.Command{
 		Use:   "deploy",
-		Short: "Deploys the action version",
-		Long:  `$ auth0 actions deploy --id <actionid> --version <versionid>`,
+		Short: "Deploy the action version",
+		Long:  `auth0 actions deploy --id <actionid> --version <versionid>`,
 		PreRun: func(cmd *cobra.Command, args []string) {
 			prepareInteractivity(cmd)
 		},
@@ -235,7 +235,7 @@ func downloadActionCmd(cli *cli) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "download",
 		Short: "Download the action version",
-		Long:  `$ auth0 actions download --id <actionid> --version <versionid | draft>`,
+		Long:  `auth0 actions download --id <actionid> --version <versionid | draft>`,
 		PreRun: func(cmd *cobra.Command, args []string) {
 			prepareInteractivity(cmd)
 		},
@@ -320,8 +320,8 @@ func listActionVersionsCmd(cli *cli) *cobra.Command {
 
 	cmd := &cobra.Command{
 		Use:   "versions",
-		Short: "Lists the action versions",
-		Long:  `$ auth0 actions versions --id <actionid>`,
+		Short: "List the action versions",
+		Long:  `auth0 actions versions --id <actionid>`,
 		PreRun: func(cmd *cobra.Command, args []string) {
 			prepareInteractivity(cmd)
 		},
@@ -368,11 +368,11 @@ func createActionCmd(cli *cli) *cobra.Command {
 
 	cmd := &cobra.Command{
 		Use:   "create",
-		Short: "Creates a new action",
-		Long: `$ auth0 actions create
-Creates a new action:
+		Short: "Create a new action",
+		Long: `auth0 actions create
+Create a new action:
 
-    $ auth0 actions create --name my-action --trigger post-login --file action.js --dependency [email protected]
+    auth0 actions create --name my-action --trigger post-login --file action.js --dependency [email protected]
 `,
 		PreRun: func(cmd *cobra.Command, args []string) {
 			prepareInteractivity(cmd)
@@ -511,7 +511,7 @@ func showTriggerCmd(cli *cli) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "show",
 		Short: "Show actions by trigger",
-		Long:  `$ auth0 actions triggers show --trigger post-login`,
+		Long:  `auth0 actions triggers show --trigger post-login`,
 		PreRun: func(cmd *cobra.Command, args []string) {
 			prepareInteractivity(cmd)
 		},
@@ -563,8 +563,8 @@ func reorderTriggerCmd(cli *cli) *cobra.Command {
 
 	cmd := &cobra.Command{
 		Use:   "reorder",
-		Short: "Reorders actions by trigger",
-		Long:  `$ auth0 actions triggers reorder --trigger <post-login> --file <bindings.json>`,
+		Short: "Reorder actions by trigger",
+		Long:  `auth0 actions triggers reorder --trigger <post-login> --file <bindings.json>`,
 		PreRun: func(cmd *cobra.Command, args []string) {
 			prepareInteractivity(cmd)
 		},
@@ -637,7 +637,7 @@ func createTriggerCmd(cli *cli) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "create",
 		Short: "Bind an action to a trigger",
-		Long:  `$ auth0 actions triggers create --trigger <post-login> --action <action_id>`,
+		Long:  `auth0 actions triggers create --trigger <post-login> --action <action_id>`,
 		PreRun: func(cmd *cobra.Command, args []string) {
 			prepareInteractivity(cmd)
 		},

internal/cli/apis.go

@@ -16,7 +16,7 @@ const (
 func apisCmd(cli *cli) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:     "apis",
-		Short:   "manage resources for APIs.",
+		Short:   "Manage resources for APIs",
 		Aliases: []string{"resource-servers"},
 	}
 
@@ -33,11 +33,11 @@ func apisCmd(cli *cli) *cobra.Command {
 func listApisCmd(cli *cli) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "list",
-		Short: "Lists your existing APIs",
-		Long: `$ auth0 apis list
+		Short: "List your existing APIs",
+		Long: `auth0 apis list
 Lists your existing APIs. To create one try:
 
-    $ auth0 apis create
+    auth0 apis create
 `,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			var list *management.ResourceServerList
@@ -68,7 +68,7 @@ func showApiCmd(cli *cli) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "show",
 		Short: "Show an API",
-		Long: `Shows an API:
+		Long: `Show an API:
 
 auth0 apis show --id id
 `,
@@ -116,7 +116,7 @@ func createApiCmd(cli *cli) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "create",
 		Short: "Create a new API",
-		Long: `Creates a new API:
+		Long: `Create a new API:
 
 auth0 apis create --name myapi --identifier http://my-api
 `,
@@ -180,7 +180,7 @@ func updateApiCmd(cli *cli) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "update",
 		Short: "Update an API",
-		Long: `Updates an API:
+		Long: `Update an API:
 
 auth0 apis update --id id --name myapi
 `,
@@ -234,7 +234,7 @@ func deleteApiCmd(cli *cli) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "delete",
 		Short: "Delete an API",
-		Long: `Deletes an API:
+		Long: `Delete an API:
 
 auth0 apis delete --id id
 `,

internal/cli/clients.go

@@ -13,7 +13,7 @@ import (
 func clientsCmd(cli *cli) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "clients",
-		Short: "manage resources for clients.",
+		Short: "Manage resources for clients",
 	}
 
 	cmd.SetUsageTemplate(resourceUsageTemplate())
@@ -26,11 +26,11 @@ func clientsCmd(cli *cli) *cobra.Command {
 func clientsListCmd(cli *cli) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "list",
-		Short: "Lists your existing clients",
-		Long: `$ auth0 client list
+		Short: "List your existing clients",
+		Long: `auth0 client list
 Lists your existing clients. To create one try:
 
-    $ auth0 clients create
+    auth0 clients create
 `,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			var list *management.ClientList
@@ -63,16 +63,12 @@ func clientsCreateCmd(cli *cli) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "create",
 		Short: "Create a new client (also know as application)",
-		Long: `Creates a new client (or application):
+		Long: `Create a new client (or application):
 
 auth0 clients create --name myapp --type [native|spa|regular|m2m]
 
 - supported application type:
-	- native: mobile, desktop, CLI and smart device apps running natively.
-	- spa (single page application): a JavaScript front-end app that uses an API.
-	- regular: Traditional web app using redirects.
-	- m2m (machine to machine): CLIs, daemons or services running on your backend.
-`,
+	`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			// todo(jfatta) on non-interactive the cmd should fail on missing mandatory args (name, type)
 			if !cmd.Flags().Changed("name") {
@@ -152,7 +148,11 @@ auth0 clients create --name myapp --type [native|spa|regular|m2m]
 		},
 	}
 	cmd.Flags().StringVarP(&flags.Name, "name", "n", "", "Name of the client.")
-	cmd.Flags().StringVarP(&flags.AppType, "type", "t", "", "Type of the client: native, spa, regular, or m2m.")
+	cmd.Flags().StringVarP(&flags.AppType, "type", "t", "", "Type of the client:\n"+
+		"- native: mobile, desktop, CLI and smart device apps running natively.\n"+
+		"- spa (single page application): a JavaScript front-end app that uses an API.\n"+
+		"- regular: Traditional web app using redirects.\n"+
+		"- m2m (machine to machine): CLIs, daemons or services running on your backend.")
 	cmd.Flags().StringVarP(&flags.Description, "description", "d", "", "A free text description of the application. Max character count is 140.")
 	cmd.Flags().StringSliceVarP(&flags.Callbacks, "callbacks", "c", nil, "After the user authenticates we will only call back to any of these URLs. You can specify multiple valid URLs by comma-separating them (typically to handle different environments like QA or testing). Make sure to specify the protocol (https://) otherwise the callback may fail in some cases. With the exception of custom URI schemes for native clients, all callbacks should use protocol https://.")
 

internal/cli/completion.go

@@ -9,7 +9,7 @@ import (
 func completionCmd(cli *cli) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "completion [bash|zsh|fish|powershell]",
-		Short: "generate completion script",
+		Short: "Setup autocomplete features for this CLI on your terminal",
 		Long: `To load completions:
 
 Bash:

internal/cli/connections.go

@@ -9,7 +9,7 @@ import (
 func connectionsCmd(cli *cli) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "connections",
-		Short: "manage resources for connections.",
+		Short: "Manage resources for connections",
 	}
 
 	cmd.SetUsageTemplate(resourceUsageTemplate())
@@ -21,11 +21,11 @@ func connectionsCmd(cli *cli) *cobra.Command {
 func listConnectionsCmd(cli *cli) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "list",
-		Short: "Lists your existing connections",
-		Long: `$ auth0 connections list
+		Short: "List existing connections",
+		Long: `auth0 connections list
 Lists your existing connections. To create one try:
 
-    $ auth0 connections create
+    auth0 connections create
 `,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			var list *management.ConnectionList

internal/cli/custom_domains.go

@@ -11,7 +11,7 @@ import (
 func customDomainsCmd(cli *cli) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "custom-domains",
-		Short: "manage resources for custom-domains.",
+		Short: "Manage resources for custom-domains",
 	}
 
 	cmd.SetUsageTemplate(resourceUsageTemplate())
@@ -27,11 +27,11 @@ func customDomainsCmd(cli *cli) *cobra.Command {
 func customDomainsListCmd(cli *cli) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "list",
-		Short: "Get custom domains configurations",
+		Short: "List custom domains configurations",
 		Long: `
 Retrieve details on custom domains.
 
-  $ auth0 custom-domains list
+  auth0 custom-domains list
 
 `,
 		RunE: func(cmd *cobra.Command, args []string) error {
@@ -68,7 +68,7 @@ Create a new custom domain.
 
 Note: The custom domain will need to be verified before it will accept requests.
 
-  $ auth0 custom-domain create --domain example.org --type auth0_managed_certs --type txt
+  auth0 custom-domain create --domain example.org --type auth0_managed_certs --type txt
 
 `,
 		RunE: func(cmd *cobra.Command, args []string) error {
@@ -124,7 +124,7 @@ func customDomainsDeleteCmd(cli *cli) *cobra.Command {
 		Long: `
 Delete a custom domain and stop serving requests for it.
 
-  $ auth0 custom-domains delete --custom-domain-id myCustomDomainID
+  auth0 custom-domains delete --custom-domain-id myCustomDomainID
 `,
 		RunE: func(cmd *cobra.Command, args []string) error {
 
@@ -165,7 +165,7 @@ func customDomainsGetCmd(cli *cli) *cobra.Command {
 		Long: `
 Retrieve a custom domain configuration and status.
 
-  $ auth0 custom-domain get --custom-domain-id myCustomDomainID
+  auth0 custom-domain get --custom-domain-id myCustomDomainID
 `,
 		RunE: func(cmd *cobra.Command, args []string) error {
 
@@ -225,7 +225,7 @@ Learn more about verifying custom domains that use Auth0 Managed certificates:
 Learn more about verifying custom domains that use Self Managed certificates:
   - https://auth0.com/docs/custom-domains/self-managed-certificates#step-2-verify-ownership
 
-  $ auth0 custom-domain verify --custom-domain-id myCustomDomainID
+  auth0 custom-domain verify --custom-domain-id myCustomDomainID
 `,
 		RunE: func(cmd *cobra.Command, args []string) error {
 

internal/cli/login.go

@@ -13,7 +13,7 @@ import (
 func loginCmd(cli *cli) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "login",
-		Short: "authenticate the Auth0 CLI.",
+		Short: "Authenticate the Auth0 CLI",
 		Long:  "sign in to your Auth0 account and authorize the CLI to access the API",
 		RunE: func(cmd *cobra.Command, args []string) error {
 			ctx := cmd.Context()

internal/cli/logs.go

@@ -32,8 +32,8 @@ func logsCmd(cli *cli) *cobra.Command {
 	var noColor bool
 	cmd := &cobra.Command{
 		Use:   "logs",
-		Short: "show the tenant logs",
-		Long: `$ auth0 logs
+		Short: "Show the tenant logs",
+		Long: `auth0 logs
 Show the tenant logs.
 `,
 		RunE: func(cmd *cobra.Command, args []string) error {