From 84435d656264e82743eefdbce76e548d6963f71a Mon Sep 17 00:00:00 2001 From: "Jorge L. Fatta" Date: Wed, 27 Jan 2021 14:47:02 -0300 Subject: [PATCH] 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 | 40 +++++++++++++++++----------------- internal/cli/apis.go | 16 +++++++------- internal/cli/clients.go | 22 +++++++++---------- internal/cli/completion.go | 2 +- internal/cli/connections.go | 8 +++---- internal/cli/custom_domains.go | 14 ++++++------ internal/cli/login.go | 2 +- internal/cli/logs.go | 4 ++-- internal/cli/roles.go | 12 +++++----- internal/cli/root.go | 6 ++++- internal/cli/rules.go | 6 ++--- internal/cli/try_login.go | 4 ++-- 12 files changed, 70 insertions(+), 66 deletions(-) diff --git a/internal/cli/actions.go b/internal/cli/actions.go index e3d7c2058..686312656 100644 --- a/internal/cli/actions.go +++ b/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 --file `, + Long: `auth0 actions test --id --file `, 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 --version `, + Short: "Deploy the action version", + Long: `auth0 actions deploy --id --version `, 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 --version `, + Long: `auth0 actions download --id --version `, 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 `, + Short: "List the action versions", + Long: `auth0 actions versions --id `, 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 lodash@4.17.19 + auth0 actions create --name my-action --trigger post-login --file action.js --dependency lodash@4.17.19 `, 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 --file `, + Short: "Reorder actions by trigger", + Long: `auth0 actions triggers reorder --trigger --file `, 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 --action `, + Long: `auth0 actions triggers create --trigger --action `, PreRun: func(cmd *cobra.Command, args []string) { prepareInteractivity(cmd) }, diff --git a/internal/cli/apis.go b/internal/cli/apis.go index 919623cdf..821cebbeb 100644 --- a/internal/cli/apis.go +++ b/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 `, diff --git a/internal/cli/clients.go b/internal/cli/clients.go index 34fef721f..a65fa38d7 100644 --- a/internal/cli/clients.go +++ b/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://.") diff --git a/internal/cli/completion.go b/internal/cli/completion.go index f4a554b9f..4de0aabb2 100644 --- a/internal/cli/completion.go +++ b/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: diff --git a/internal/cli/connections.go b/internal/cli/connections.go index 44c405bc8..fe44dd34f 100644 --- a/internal/cli/connections.go +++ b/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 diff --git a/internal/cli/custom_domains.go b/internal/cli/custom_domains.go index 910dfdf1d..32881ffd6 100644 --- a/internal/cli/custom_domains.go +++ b/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 { diff --git a/internal/cli/login.go b/internal/cli/login.go index ae25c13f2..b3ead4cb2 100644 --- a/internal/cli/login.go +++ b/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() diff --git a/internal/cli/logs.go b/internal/cli/logs.go index 898d510cd..4a2f850eb 100644 --- a/internal/cli/logs.go +++ b/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 { diff --git a/internal/cli/roles.go b/internal/cli/roles.go index de3cebd47..d73f4e778 100644 --- a/internal/cli/roles.go +++ b/internal/cli/roles.go @@ -11,7 +11,7 @@ import ( func rolesCmd(cli *cli) *cobra.Command { cmd := &cobra.Command{ Use: "roles", - Short: "manage resources for roles.", + Short: "Manage resources for roles", } cmd.SetUsageTemplate(resourceUsageTemplate()) @@ -28,7 +28,7 @@ func rolesListCmd(cli *cli) *cobra.Command { cmd := &cobra.Command{ Use: "list", Short: "List all roles", - Long: `$ auth0 roles list + Long: `auth0 roles list Retrieve filtered list of roles that can be assigned to users or groups `, @@ -59,7 +59,7 @@ func rolesGetCmd(cli *cli) *cobra.Command { cmd := &cobra.Command{ Use: "get", Short: "Get a role", - Long: `$ auth0 roles get --role-id myRoleID + Long: `auth0 roles get --role-id myRoleID Get a role `, @@ -109,7 +109,7 @@ func rolesDeleteCmd(cli *cli) *cobra.Command { cmd := &cobra.Command{ Use: "delete", Short: "Delete a role", - Long: `$ auth0 roles delete --role-id myRoleID + Long: `auth0 roles delete --role-id myRoleID Delete a role. `, @@ -151,7 +151,7 @@ func rolesUpdateCmd(cli *cli) *cobra.Command { cmd := &cobra.Command{ Use: "update", Short: "Update a role", - Long: `$ auth0 roles update --role-id myRoleID --name myName --description myDescription + Long: `auth0 roles update --role-id myRoleID --name myName --description myDescription Update a role. `, @@ -210,7 +210,7 @@ func rolesCreateCmd(cli *cli) *cobra.Command { cmd := &cobra.Command{ Use: "create", Short: "Create a role", - Long: `$ auth0 roles create --name myName --description myDescription + Long: `auth0 roles create --name myName --description myDescription Create a new role. `, diff --git a/internal/cli/root.go b/internal/cli/root.go index c8487f78c..ce55ff283 100644 --- a/internal/cli/root.go +++ b/internal/cli/root.go @@ -56,6 +56,8 @@ func Execute() { rootCmd.PersistentFlags().BoolVar(&cli.noInput, "no-input", false, "Disable interactivity.") + // order of the comamnds here matters + // so add new commands in a place that reflect its relevance or relation with other commands: rootCmd.AddCommand(loginCmd(cli)) rootCmd.AddCommand(clientsCmd(cli)) rootCmd.AddCommand(apisCmd(cli)) @@ -64,11 +66,13 @@ func Execute() { rootCmd.AddCommand(rulesCmd(cli)) rootCmd.AddCommand(actionsCmd(cli)) rootCmd.AddCommand(connectionsCmd(cli)) - rootCmd.AddCommand(completionCmd(cli)) rootCmd.AddCommand(rolesCmd(cli)) rootCmd.AddCommand(customDomainsCmd(cli)) rootCmd.AddCommand(getTokenCmd(cli)) + // keep completion at the bottom: + rootCmd.AddCommand(completionCmd(cli)) + // TODO(cyx): backport this later on using latest auth0/v5. // rootCmd.AddCommand(actionsCmd(cli)) // rootCmd.AddCommand(triggersCmd(cli)) diff --git a/internal/cli/rules.go b/internal/cli/rules.go index 7906d8e63..41ddbfd54 100644 --- a/internal/cli/rules.go +++ b/internal/cli/rules.go @@ -22,7 +22,7 @@ const ( func rulesCmd(cli *cli) *cobra.Command { cmd := &cobra.Command{ Use: "rules", - Short: "manage rules for clients.", + Short: "Manage rules for clients", } cmd.SetUsageTemplate(resourceUsageTemplate()) @@ -39,8 +39,8 @@ func rulesCmd(cli *cli) *cobra.Command { func listRulesCmd(cli *cli) *cobra.Command { cmd := &cobra.Command{ Use: "list", - Short: "Lists your rules", - Long: `Lists the rules in your current tenant.`, + Short: "List your rules", + Long: `List the rules in your current tenant.`, RunE: func(cmd *cobra.Command, args []string) error { var rules *management.RuleList err := ansi.Spinner("Loading rules", func() error { diff --git a/internal/cli/try_login.go b/internal/cli/try_login.go index e6dc2e543..a955a0a4c 100644 --- a/internal/cli/try_login.go +++ b/internal/cli/try_login.go @@ -35,8 +35,8 @@ func tryLoginCmd(cli *cli) *cobra.Command { cmd := &cobra.Command{ Use: "try-login", - Short: "try out your universal login box.", - Long: `$ auth0 try-login + Short: "Try out your universal login box", + Long: `auth0 try-login Launch a browser to try out your universal login box for the given client. `, RunE: func(cmd *cobra.Command, args []string) error {