Improve vespa auth documentation

4 files changed, 31 insertions, 17 deletions

diff --git a/client/go/internal/cli/cmd/api_key.go b/client/go/internal/cli/cmd/api_key.go
index e6e4307bb44..ef04532314c 100644
--- a/client/go/internal/cli/cmd/api_key.go
+++ b/client/go/internal/cli/cmd/api_key.go
@@ -18,14 +18,17 @@ func newAPIKeyCmd(cli *CLI) *cobra.Command {
 	var overwriteKey bool
 	cmd := &cobra.Command{
 		Use:   "api-key",
-		Short: "Create a new user API key for control-plane authentication with Vespa Cloud",
-		Long: `Create a new user API key for control-plane authentication with Vespa Cloud.
+		Short: "Create a new developer key for headless authentication with Vespa Cloud control plane",
+		Long: `Create a new developer key for headless authentication with Vespa Cloud control plane
 
-The API key will be stored in the Vespa CLI home directory
-(see 'vespa help config'). Other commands will then automatically load the API
+A developer key is intended for headless communication with the Vespa Cloud
+control plane. For example when deploying from a continuous integration system.
+
+The developer key will be stored in the Vespa CLI home directory
+(see 'vespa help config'). Other commands will then automatically load the developer
 key as necessary.
 
-It's possible to override the API key used through environment variables. This
+It's possible to override the developer key used through environment variables. This
 can be useful in continuous integration systems.
 
 Example of setting the key in-line:
@@ -36,8 +39,9 @@ Example of loading the key from a custom path:
 
     export VESPA_CLI_API_KEY_FILE=/path/to/api-key
 
-Note that when overriding API key through environment variables, that key will
-always be used. It's not possible to specify a tenant-specific key.
+Note that when overriding the developer key through environment variables,
+that key will always be used. It's not possible to specify a tenant-specific
+key through the environment.
 
 Read more in https://cloud.vespa.ai/en/security/guide`,
 		Example:           "$ vespa auth api-key -a my-tenant.my-app.my-instance",
@@ -48,7 +52,7 @@ Read more in https://cloud.vespa.ai/en/security/guide`,
 			return doApiKey(cli, overwriteKey, args)
 		},
 	}
-	cmd.Flags().BoolVarP(&overwriteKey, "force", "f", false, "Force overwrite of existing API key")
+	cmd.Flags().BoolVarP(&overwriteKey, "force", "f", false, "Force overwrite of existing developer key")
 	cmd.MarkPersistentFlagRequired(applicationFlag)
 	return cmd
 }
@@ -78,7 +82,7 @@ func doApiKey(cli *CLI, overwriteKey bool, args []string) error {
 		return fmt.Errorf("could not create api key: %w", err)
 	}
 	if err := os.WriteFile(apiKeyFile, apiKey, 0600); err == nil {
-		cli.printSuccess("API private key written to ", apiKeyFile)
+		cli.printSuccess("Developer private key written to ", apiKeyFile)
 		return printPublicKey(system, apiKeyFile, app.Tenant)
 	} else {
 		return fmt.Errorf("failed to write: %s: %w", apiKeyFile, err)
diff --git a/client/go/internal/cli/cmd/api_key_test.go b/client/go/internal/cli/cmd/api_key_test.go
index 9e6ee06c7fd..18baec91e0c 100644
--- a/client/go/internal/cli/cmd/api_key_test.go
+++ b/client/go/internal/cli/cmd/api_key_test.go
@@ -25,7 +25,7 @@ func testAPIKey(t *testing.T, subcommand []string) {
 	err = cli.Run(args...)
 	assert.Nil(t, err)
 	assert.Equal(t, "", stderr.String())
-	assert.Contains(t, stdout.String(), "Success: API private key written to")
+	assert.Contains(t, stdout.String(), "Success: Developer private key written to")
 
 	err = cli.Run(subcommand...)
 	assert.NotNil(t, err)
diff --git a/client/go/internal/cli/cmd/cert.go b/client/go/internal/cli/cmd/cert.go
index abcee5a4408..aca8de88fbe 100644
--- a/client/go/internal/cli/cmd/cert.go
+++ b/client/go/internal/cli/cmd/cert.go
@@ -21,8 +21,8 @@ func newCertCmd(cli *CLI) *cobra.Command {
 	)
 	cmd := &cobra.Command{
 		Use:   "cert",
-		Short: "Create a new private key and self-signed certificate for data-plane access with Vespa Cloud",
-		Long: `Create a new private key and self-signed certificate for data-plane access with Vespa Cloud.
+		Short: "Create a new self-signed certificate for authentication with Vespa Cloud data plane",
+		Long: `Create a new self-signed certificate for authentication with Vespa Cloud data plane.
 
 The private key and certificate will be stored in the Vespa CLI home directory
 (see 'vespa help config'). Other commands will then automatically load the
@@ -47,12 +47,18 @@ Example of loading CA certificate, certificate and key from custom paths:
     export VESPA_CLI_DATA_PLANE_CERT_FILE=/path/to/cert
     export VESPA_CLI_DATA_PLANE_KEY_FILE=/path/to/key
 
+Example of disabling verification of the server's certificate chain and
+hostname:
+
+    export VESPA_CLI_DATA_PLANE_TRUST_ALL=true
+
 Note that when overriding key pair through environment variables, that key pair
 will always be used for all applications. It's not possible to specify an
 application-specific key.
 
-Read more in https://cloud.vespa.ai/en/security/guide`,
-		Example: `$ vespa auth cert -a my-tenant.my-app.my-instance
+See https://cloud.vespa.ai/en/security/guide for more details.`,
+		Example: `$ vespa auth cert
+$ vespa auth cert -a my-tenant.my-app.my-instance
 $ vespa auth cert -a my-tenant.my-app.my-instance path/to/application/package`,
 		DisableAutoGenTag: true,
 		SilenceUsage:      true,
diff --git a/client/go/internal/cli/cmd/login.go b/client/go/internal/cli/cmd/login.go
index 0072c0033c8..b380e627203 100644
--- a/client/go/internal/cli/cmd/login.go
+++ b/client/go/internal/cli/cmd/login.go
@@ -19,9 +19,13 @@ import (
 // this will only affect the messages.
 func newLoginCmd(cli *CLI) *cobra.Command {
 	return &cobra.Command{
-		Use:               "login",
-		Args:              cobra.NoArgs,
-		Short:             "Authenticate Vespa CLI with Vespa Cloud",
+		Use:   "login",
+		Args:  cobra.NoArgs,
+		Short: "Authenticate Vespa CLI with Vespa Cloud control plane. This is preferred over api-key for interactive use",
+		Long: `Authenticate Vespa CLI with Vespa Cloud control plane. This is preferred over api-key for interactive use.
+
+This command runs a browser-based authentication flow for the Vespa Cloud control plane.
+`,
 		Example:           "$ vespa auth login",
 		DisableAutoGenTag: true,
 		SilenceUsage:      true,