Clean up the help texts (#243)

internal/auth/authutil/exchange.go

@@ -17,7 +17,7 @@ type TokenResponse struct {
 	ExpiresIn    int64  `json:"expires_in,omitempty"`
 }
 
-// ExchangeCodeForToken fetches an access token for the given client using the provided code.
+// ExchangeCodeForToken fetches an access token for the given application using the provided code.
 func ExchangeCodeForToken(baseDomain, clientID, clientSecret, code, cbURL string) (*TokenResponse, error) {
 	data := url.Values{
 		"grant_type":    {"authorization_code"},

internal/cli/apis.go

@@ -43,6 +43,7 @@ func apisCmd(cli *cli) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:     "apis",
 		Short:   "Manage resources for APIs",
+		Long:    "Manage resources for APIs.",
 		Aliases: []string{"resource-servers"},
 	}
 
@@ -61,6 +62,7 @@ func scopesCmd(cli *cli) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "scopes",
 		Short: "Manage resources for API scopes",
+		Long:  "Manage resources for API scopes.",
 	}
 
 	cmd.SetUsageTemplate(resourceUsageTemplate())
@@ -75,10 +77,8 @@ func listApisCmd(cli *cli) *cobra.Command {
 		Aliases: []string{"ls"},
 		Args:    cobra.NoArgs,
 		Short:   "List your APIs",
-		Long: `auth0 apis list
-Lists your existing APIs. To create one try:
-    auth0 apis create
-`,
+		Long: `List your existing APIs. To create one try:
+auth0 apis create`,
 		Example: `auth0 apis list
 auth0 apis ls`,
 		RunE: func(cmd *cobra.Command, args []string) error {
@@ -109,7 +109,7 @@ func showApiCmd(cli *cli) *cobra.Command {
 		Use:   "show",
 		Args:  cobra.MaximumNArgs(1),
 		Short: "Show an API",
-		Long:  `Show an API:`,
+		Long:  "Show an API.",
 		Example: `auth0 apis show 
 auth0 apis show <id>`,
 		PreRun: func(cmd *cobra.Command, args []string) {
@@ -154,11 +154,10 @@ func createApiCmd(cli *cli) *cobra.Command {
 		Use:   "create",
 		Args:  cobra.NoArgs,
 		Short: "Create a new API",
-		Long:  `Create a new API`,
+		Long:  "Create a new API.",
 		Example: `auth0 apis create 
 auth0 apis create --name myapi 
-auth0 apis create -n myapi --identifier http://my-api
-`,
+auth0 apis create -n myapi --identifier http://my-api`,
 		PreRun: func(cmd *cobra.Command, args []string) {
 			prepareInteractivity(cmd)
 		},
@@ -213,7 +212,7 @@ func updateApiCmd(cli *cli) *cobra.Command {
 		Use:   "update",
 		Args:  cobra.MaximumNArgs(1),
 		Short: "Update an API",
-		Long:  `Update an API:`,
+		Long:  "Update an API.",
 		Example: `auth0 apis update 
 auth0 apis update <id> 
 auth0 apis update <id> --name myapi`,
@@ -288,7 +287,7 @@ func deleteApiCmd(cli *cli) *cobra.Command {
 		Use:   "delete",
 		Args:  cobra.MaximumNArgs(1),
 		Short: "Delete an API",
-		Long:  `Delete an API:`,
+		Long:  "Delete an API.",
 		Example: `auth0 apis delete 
 auth0 apis delete <id>`,
 		PreRun: func(cmd *cobra.Command, args []string) {
@@ -335,7 +334,7 @@ func listScopesCmd(cli *cli) *cobra.Command {
 		Aliases: []string{"ls"},
 		Args:    cobra.MaximumNArgs(1),
 		Short:   "List the scopes of an API",
-		Long:    `List the scopes of an API`,
+		Long:    "List the scopes of an API.",
 		Example: `auth0 apis scopes list 
 auth0 apis scopes ls <id>`,
 		PreRun: func(cmd *cobra.Command, args []string) {

internal/cli/apps.go

@@ -117,6 +117,7 @@ func appsCmd(cli *cli) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:     "apps",
 		Short:   "Manage resources for applications",
+		Long:    "Manage resources for applications.",
 		Aliases: []string{"clients"},
 	}
 
@@ -141,8 +142,8 @@ func useAppCmd(cli *cli) *cobra.Command {
 		Use:     "use",
 		Args:    cobra.MaximumNArgs(1),
 		Short:   "Choose a default application for the Auth0 CLI",
-		Long:    `Specify your preferred application for interaction with the Auth0 CLI`,
-		Example: `auth0 apps use <client-id>`,
+		Long:    "Specify your preferred application for interaction with the Auth0 CLI.",
+		Example: "auth0 apps use <client-id>",
 		PreRun: func(cmd *cobra.Command, args []string) {
 			prepareInteractivity(cmd)
 		},
@@ -186,7 +187,7 @@ func listAppsCmd(cli *cli) *cobra.Command {
 		Aliases: []string{"ls"},
 		Args:    cobra.NoArgs,
 		Short:   "List your applications",
-		Long: `Lists your existing applications. To create one try:
+		Long: `List your existing applications. To create one try:
 auth0 apps create`,
 		Example: `auth0 apps list
 auth0 apps ls`,
@@ -218,7 +219,7 @@ func showAppCmd(cli *cli) *cobra.Command {
 		Use:   "show",
 		Args:  cobra.MaximumNArgs(1),
 		Short: "Show an application",
-		Long:  `Show an application:`,
+		Long:  "Show an application.",
 		Example: `auth0 apps show 
 auth0 apps show <id>`,
 		PreRun: func(cmd *cobra.Command, args []string) {
@@ -262,7 +263,7 @@ func deleteAppCmd(cli *cli) *cobra.Command {
 		Use:   "delete",
 		Args:  cobra.MaximumNArgs(1),
 		Short: "Delete an application",
-		Long:  `Delete an application:`,
+		Long:  "Delete an application.",
 		Example: `auth0 apps delete 
 auth0 apps delete <id>`,
 		PreRun: func(cmd *cobra.Command, args []string) {
@@ -318,7 +319,7 @@ func createAppCmd(cli *cli) *cobra.Command {
 		Use:   "create",
 		Args:  cobra.NoArgs,
 		Short: "Create a new application",
-		Long:  `Create a new application:`,
+		Long:  "Create a new application.",
 		Example: `auth0 apps create 
 auth0 apps create --name myapp 
 auth0 apps create -n myapp --type [native|spa|regular|m2m]
@@ -468,7 +469,7 @@ func updateAppCmd(cli *cli) *cobra.Command {
 		Use:   "update",
 		Args:  cobra.MaximumNArgs(1),
 		Short: "Update an application",
-		Long:  `Update an application`,
+		Long:  "Update an application.",
 		Example: `auth0 apps update <id> 
 auth0 apps update <id> --name myapp 
 auth0 apps update <id> -n myapp --type [native|spa|regular|m2m]`,

internal/cli/login.go

@@ -17,7 +17,7 @@ func loginCmd(cli *cli) *cobra.Command {
 		Use:   "login",
 		Args:  cobra.NoArgs,
 		Short: "Authenticate the Auth0 CLI",
-		Long:  "sign in to your Auth0 account and authorize the CLI to access the API",
+		Long:  "Sign in to your Auth0 account and authorize the CLI to access the Management API.",
 		RunE: func(cmd *cobra.Command, args []string) error {
 			ctx := cmd.Context()
 			return RunLogin(ctx, cli, false)

internal/cli/logout.go

@@ -10,10 +10,11 @@ import (
 
 func logoutCmd(cli *cli) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   "logout",
-		Args:  cobra.MaximumNArgs(1),
-		Short: "Logout of a tenant's session",
-		Long:  `auth0 logout <tenant>`,
+		Use:     "logout",
+		Args:    cobra.MaximumNArgs(1),
+		Short:   "Log out of a tenant's session",
+		Long:    "Log out of a tenant's session.",
+		Example: "auth0 logout <tenant>",
 		RunE: func(cmd *cobra.Command, args []string) error {
 			// NOTE(cyx): This was mostly copy/pasted from tenants
 			// use command. Consider refactoring.

internal/cli/logs.go

@@ -36,6 +36,7 @@ func logsCmd(cli *cli) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "logs",
 		Short: "View tenant logs",
+		Long:  "View tenant logs.",
 	}
 
 	cmd.SetUsageTemplate(resourceUsageTemplate())
@@ -109,7 +110,7 @@ func tailLogsCmd(cli *cli) *cobra.Command {
 		Use:   "tail",
 		Args:  cobra.MaximumNArgs(1),
 		Short: "Tail the tenant logs",
-		Long:  "Tail the tenant logs allowing to filter by Client ID",
+		Long:  "Tail the tenant logs allowing to filter by Client ID.",
 		Example: `auth0 logs tail
 auth0 logs tail --client-id <id>
 auth0 logs tail -n 100`,

internal/cli/quickstarts.go

@@ -69,6 +69,7 @@ func quickstartsCmd(cli *cli) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:     "quickstarts",
 		Short:   "Quickstart support for getting bootstrapped",
+		Long:    "Quickstart support for getting bootstrapped.",
 		Aliases: []string{"qs"},
 	}
 
@@ -85,10 +86,11 @@ func downloadQuickstart(cli *cli) *cobra.Command {
 	}
 
 	cmd := &cobra.Command{
-		Use:   "download",
-		Args:  cobra.MaximumNArgs(1),
-		Short: "Download a quickstart sample app for a specific tech stack",
-		Long:  `auth0 quickstarts download --stack <stack>`,
+		Use:     "download",
+		Args:    cobra.MaximumNArgs(1),
+		Short:   "Download a quickstart sample app for a specific tech stack",
+		Long:    "Download a quickstart sample app for a specific tech stack.",
+		Example: "auth0 quickstarts download --stack <stack>",
 		PreRun: func(cmd *cobra.Command, args []string) {
 			prepareInteractivity(cmd)
 		},

internal/cli/rules.go

@@ -61,6 +61,7 @@ func rulesCmd(cli *cli) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "rules",
 		Short: "Manage resources for rules",
+		Long:  "Manage resources for rules.",
 	}
 
 	cmd.SetUsageTemplate(resourceUsageTemplate())
@@ -79,7 +80,8 @@ func listRulesCmd(cli *cli) *cobra.Command {
 		Aliases: []string{"ls"},
 		Args:    cobra.NoArgs,
 		Short:   "List your rules",
-		Long:    `List the rules in your current tenant.`,
+		Long: `List your existing rules. To create one try:
+auth0 rules create`,
 		Example: `auth0 rules list
 auth0 rules ls`,
 		RunE: func(cmd *cobra.Command, args []string) error {
@@ -117,7 +119,7 @@ func createRuleCmd(cli *cli) *cobra.Command {
 		Use:   "create",
 		Args:  cobra.NoArgs,
 		Short: "Create a new rule",
-		Long:  `Create a new rule:`,
+		Long:  "Create a new rule.",
 		Example: `auth0 rules create
 auth0 rules create --name "My Rule"
 auth0 rules create -n "My Rule" --template "Empty rule"
@@ -183,7 +185,7 @@ func showRuleCmd(cli *cli) *cobra.Command {
 		Use:   "show",
 		Args:  cobra.MaximumNArgs(1),
 		Short: "Show a rule",
-		Long:  `Show a rule:`,
+		Long:  "Show a rule.",
 		Example: `auth0 rules show 
 auth0 rules show <id>`,
 		PreRun: func(cmd *cobra.Command, args []string) {
@@ -228,7 +230,7 @@ func deleteRuleCmd(cli *cli) *cobra.Command {
 		Use:   "delete",
 		Args:  cobra.MaximumNArgs(1),
 		Short: "Delete a rule",
-		Long:  `Delete a rule`,
+		Long:  "Delete a rule.",
 		Example: `auth0 rules delete 
 auth0 rules delete <rule-id>`,
 		PreRun: func(cmd *cobra.Command, args []string) {
@@ -271,7 +273,7 @@ func updateRuleCmd(cli *cli) *cobra.Command {
 		Use:   "update",
 		Args:  cobra.MaximumNArgs(1),
 		Short: "Update a rule",
-		Long:  `Update a rule`,
+		Long:  "Update a rule.",
 		Example: `auth0 rules update <rule-id> 
 auth0 rules update <rule-id> --name "My Updated Rule"
 auth0 rules update <rule-id> -n "My Updated Rule" --enabled=false`,

internal/cli/tenants.go

@@ -11,6 +11,7 @@ func tenantsCmd(cli *cli) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "tenants",
 		Short: "Manage configured tenants",
+		Long:  "Manage configured tenants.",
 	}
 
 	cmd.SetUsageTemplate(resourceUsageTemplate())
@@ -25,7 +26,8 @@ func listTenantCmd(cli *cli) *cobra.Command {
 		Aliases: []string{"ls"},
 		Args:    cobra.NoArgs,
 		Short:   "List your tenants",
-		Long:    `auth0 tenants list`,
+		Long:    "List your tenants.",
+		Example: "auth0 tenants list",
 		RunE: func(cmd *cobra.Command, args []string) error {
 			tens, err := cli.listTenants()
 			if err != nil {
@@ -46,10 +48,11 @@ func listTenantCmd(cli *cli) *cobra.Command {
 
 func useTenantCmd(cli *cli) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   "use",
-		Args:  cobra.MaximumNArgs(1),
-		Short: "Set the active tenant",
-		Long:  `auth0 tenants use <tenant>`,
+		Use:     "use",
+		Args:    cobra.MaximumNArgs(1),
+		Short:   "Set the active tenant",
+		Long:    "Set the active tenant.",
+		Example: "auth0 tenants use <tenant>",
 		PreRun: func(cmd *cobra.Command, args []string) {
 			prepareInteractivity(cmd)
 		},

internal/cli/test.go

@@ -55,7 +55,8 @@ var (
 func testCmd(cli *cli) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "test",
-		Short: "Try your universal login box or get a token",
+		Short: "Try your Universal Login box or get a token",
+		Long:  "Try your Universal Login box or get a token.",
 	}
 
 	cmd.SetUsageTemplate(resourceUsageTemplate())
@@ -75,8 +76,8 @@ func testLoginCmd(cli *cli) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "login",
 		Args:  cobra.MaximumNArgs(1),
-		Short: "Try out your universal login box",
-		Long:  `Launch a browser to try out your universal login box.`,
+		Short: "Try out your Universal Login box",
+		Long:  "Launch a browser to try out your Universal Login box.",
 		Example: `auth0 test login
 auth0 test login <client-id>
 auth0 test login <client-id> --connection <connection>`,
@@ -184,8 +185,8 @@ func testTokenCmd(cli *cli) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "token",
 		Args:  cobra.NoArgs,
-		Short: "Fetch a token for the given client and API",
-		Long: `Fetch an access token for the given client.
+		Short: "Fetch a token for the given application and API",
+		Long: `Fetch an access token for the given application.
 If --client-id is not provided, the default client "CLI Login Testing" will be used (and created if not exists).
 Specify the API you want this token for with --audience (API Identifer). Additionally, you can also specify the --scope to use.`,
 		Example: `auth0 test token

internal/cli/utils_shared.go

@@ -207,7 +207,7 @@ func hasLocalCallbackURL(client *management.Client) bool {
 	return false
 }
 
-// adds the localhost callback URL to a given client
+// adds the localhost callback URL to a given application
 func addLocalCallbackURLToClient(clientManager auth0.ClientAPI, client *management.Client) (bool, error) {
 	for _, rawCallbackURL := range client.Callbacks {
 		callbackURL := rawCallbackURL.(string)