Merge pull request #31558 from vespa-engine/mpolden/cli-doc

Improve CLI documentation

6 files changed, 33 insertions, 30 deletions

diff --git a/client/go/internal/cli/cmd/config.go b/client/go/internal/cli/cmd/config.go
index 032abfd598a..dfe48118340 100644
--- a/client/go/internal/cli/cmd/config.go
+++ b/client/go/internal/cli/cmd/config.go
@@ -35,7 +35,7 @@ func newConfigCmd() *cobra.Command {
 
 This command allows setting persistent values for the global flags found in
 Vespa CLI. On future invocations the flag can then be omitted as it is read
- from the config file instead.
+from the config file instead.
 
 Configuration is written to $HOME/.vespa by default. This path can be
 overridden by setting the VESPA_CLI_HOME environment variable.
@@ -114,8 +114,7 @@ zone
 Specifies a custom zone to use when connecting to a Vespa Cloud application.
 This is only relevant for cloud and hosted targets and defaults to a dev zone.
 See https://cloud.vespa.ai/en/reference/zones for available zones. Examples:
-dev.aws-us-east-1c, dev.gcp-us-central1-f, perf.aws-us-east-1c
-`,
+dev.aws-us-east-1c, dev.gcp-us-central1-f, perf.aws-us-east-1c`,
 		DisableAutoGenTag: true,
 		SilenceUsage:      false,
 		Args:              cobra.MinimumNArgs(1),
@@ -143,8 +142,7 @@ $ vespa config set application my-tenant.my-application.my-instance
 $ vespa config set instance other-instance
 
 # Set an option in local configuration, for the current application only
-$ vespa config set --local wait 600
-`,
+$ vespa config set --local zone perf.us-north-1`,
 		DisableAutoGenTag: true,
 		SilenceUsage:      true,
 		Args:              cobra.ExactArgs(2),
@@ -180,8 +178,7 @@ Unsetting a configuration option will reset it to its default value, which may b
 $ vespa config unset target
 
 # Stop overriding application option in local config
-$ vespa config unset --local application
-`,
+$ vespa config unset --local application`,
 		DisableAutoGenTag: true,
 		SilenceUsage:      true,
 		Args:              cobra.ExactArgs(1),
@@ -216,8 +213,7 @@ application, i.e. it takes into account any local configuration located in
 `,
 		Example: `$ vespa config get
 $ vespa config get target
-$ vespa config get --local
-`,
+$ vespa config get --local`,
 		Args:              cobra.MaximumNArgs(1),
 		DisableAutoGenTag: true,
 		SilenceUsage:      true,
diff --git a/client/go/internal/cli/cmd/deploy.go b/client/go/internal/cli/cmd/deploy.go
index c9f08655759..4792088a915 100644
--- a/client/go/internal/cli/cmd/deploy.go
+++ b/client/go/internal/cli/cmd/deploy.go
@@ -29,19 +29,22 @@ func newDeployCmd(cli *CLI) *cobra.Command {
 		Short: "Deploy (prepare and activate) an application package",
 		Long: `Deploy (prepare and activate) an application package.
 
-When this returns successfully the application package has been validated
-and activated on config servers. The process of applying it on individual nodes
-has started but may not have completed.
+An application package defines a deployable Vespa application. See
+https://docs.vespa.ai/en/reference/application-packages-reference.html for
+details about the files contained in this package.
 
-If application directory is not specified, it defaults to working directory.
+To get started, 'vespa clone' can be used to download a sample application.
+
+This command deploys an application package. When deploy returns successfully
+the application package has been validated and activated on config servers. The
+process of applying it on individual nodes has started but may not have
+completed.
 
-When deploying to Vespa Cloud the system can be overridden by setting the
-environment variable VESPA_CLI_CLOUD_SYSTEM. This is intended for internal use
-only.
+If application directory is not specified, it defaults to working directory.
 
-In Vespa Cloud you may override the Vespa runtime version for your deployment.
-This option should only be used if you have a reason for using a specific
-version. By default Vespa Cloud chooses a suitable version for you.
+In Vespa Cloud you may override the Vespa runtime version (--version) for your
+deployment. This option should only be used if you have a reason for using a
+specific version. By default Vespa Cloud chooses a suitable version for you.
 `,
 		Example: `$ vespa deploy .
 $ vespa deploy -t cloud
diff --git a/client/go/internal/cli/cmd/destroy.go b/client/go/internal/cli/cmd/destroy.go
index a7beff2e4b4..51040c0af8b 100644
--- a/client/go/internal/cli/cmd/destroy.go
+++ b/client/go/internal/cli/cmd/destroy.go
@@ -23,14 +23,13 @@ When run interactively, the command will prompt for confirmation before
 removing the application. When run non-interactively, the command will refuse
 to remove the application unless the --force option is given.
 
-This command can only be used to remove non-production deployments. See
-https://cloud.vespa.ai/en/deleting-applications for how to remove
-production deployments. This command can only be used for deployments to
-Vespa Cloud, for other systems destroy an application by cleaning up
-containers in use by the application, see e.g
-https://github.com/vespa-engine/sample-apps/tree/master/examples/operations/multinode-HA#clean-up-after-testing
+This command can only be used to remove non-production deployments, in Vespa
+Cloud. See https://cloud.vespa.ai/en/deleting-applications for how to remove
+production deployments.
 
-`,
+For other systems, destroy the application by removing the
+containers in use by the application. For example:
+https://github.com/vespa-engine/sample-apps/tree/master/examples/operations/multinode-HA#clean-up-after-testing`,
 		Example: `$ vespa destroy
 $ vespa destroy -a mytenant.myapp.myinstance
 $ vespa destroy --force`,
diff --git a/client/go/internal/cli/cmd/fetch.go b/client/go/internal/cli/cmd/fetch.go
index b2e7d11ba7b..786fe75f9c2 100644
--- a/client/go/internal/cli/cmd/fetch.go
+++ b/client/go/internal/cli/cmd/fetch.go
@@ -13,8 +13,7 @@ func newFetchCmd(cli *CLI) *cobra.Command {
 
 This command can be used to download an already deployed Vespa application
 package. The package is written as a ZIP file to the given path, or current
-directory if no path is given.
-`,
+directory if no path is given.`,
 		Example: `$ vespa fetch
 $ vespa fetch mydir/
 $ vespa fetch -t cloud mycloudapp.zip
diff --git a/client/go/internal/cli/cmd/root.go b/client/go/internal/cli/cmd/root.go
index 26e84773b9f..5d5314d694f 100644
--- a/client/go/internal/cli/cmd/root.go
+++ b/client/go/internal/cli/cmd/root.go
@@ -142,7 +142,12 @@ func New(stdout, stderr io.Writer, environment []string) (*CLI, error) {
 
 Use it on Vespa instances running locally, remotely or in Vespa Cloud.
 
-Vespa documentation: https://docs.vespa.ai
+To get started, see the following quick start guides:
+
+- Local Vespa instance: https://docs.vespa.ai/en/vespa-quick-start.html
+- Vespa Cloud: https://cloud.vespa.ai/en/getting-started
+
+The complete Vespa documentation is available at https://docs.vespa.ai.
 
 For detailed description of flags and configuration, see 'vespa help config'.
 `,
@@ -154,6 +159,7 @@ For detailed description of flags and configuration, see 'vespa help config'.
 			return fmt.Errorf("invalid command: %s", args[0])
 		},
 	}
+	cmd.CompletionOptions.HiddenDefaultCmd = true // Do not show the 'completion' command in help output
 	env := make(map[string]string)
 	for _, entry := range environment {
 		parts := strings.SplitN(entry, "=", 2)
diff --git a/client/go/internal/cli/cmd/status.go b/client/go/internal/cli/cmd/status.go
index d660e71abf9..dff0c2d24c6 100644
--- a/client/go/internal/cli/cmd/status.go
+++ b/client/go/internal/cli/cmd/status.go
@@ -150,7 +150,7 @@ func newStatusDeploymentCmd(cli *CLI) *cobra.Command {
 		Long: `Show status of a Vespa deployment.
 
 This commands shows whether a Vespa deployment has converged on the latest run
- (Vespa Cloud) or config generation (self-hosted). If an argument is given,
+(Vespa Cloud) or config generation (self-hosted). If an argument is given,
 show the convergence status of that particular run or generation.
 `,
 		Example: `$ vespa status deployment