Tweak command documentation and argument validation

8 files changed, 33 insertions, 51 deletions

diff --git a/client/go/cmd/cert.go b/client/go/cmd/cert.go
index c47b991881f..530981d08cd 100644
--- a/client/go/cmd/cert.go
+++ b/client/go/cmd/cert.go
@@ -24,12 +24,10 @@ func init() {
 }
 
 var certCmd = &cobra.Command{
-	Use:   "cert",
-	Short: "Creates a new private key and self-signed certificate",
-	Long: "Applications in Vespa Cloud are required to secure their data plane with mutual TLS.\n\n" +
-		"This command creates a self-signed certificate suitable for development purposes.\n" +
-		"See https://cloud.vespa.ai/en/security-model for more information on the Vespa\n" +
-		"Cloud security model.",
+	Use:     "cert",
+	Short:   "Create a new private key and self-signed certificate for a cloud deployment",
+	Example: "$ vespa cert -a my-tenant.my-app.my-instance",
+	Args:    cobra.MaximumNArgs(1),
 	Run: func(cmd *cobra.Command, args []string) {
 		var path string
 		if len(args) > 0 {
diff --git a/client/go/cmd/clone.go b/client/go/cmd/clone.go
index bfc25655e68..5bd6b147ffa 100644
--- a/client/go/cmd/clone.go
+++ b/client/go/cmd/clone.go
@@ -6,7 +6,6 @@ package cmd
 
 import (
 	"archive/zip"
-	"errors"
 	"io"
 	"io/ioutil"
 	"log"
@@ -31,15 +30,10 @@ func init() {
 
 var cloneCmd = &cobra.Command{
 	// TODO: "application" and "list" subcommands?
-	Use:   "clone",
-	Short: "Creates the files and directory structure for a new Vespa application",
-	Long:  `TODO: vespa clone source applicationName`,
-	Args: func(cmd *cobra.Command, args []string) error {
-		if len(args) != 2 {
-			return errors.New("vespa clone requires an application source and name")
-		}
-		return nil
-	},
+	Use:     "clone",
+	Short:   "Create files and directory structure for a new Vespa application from a template",
+	Example: "$ vespa clone vespa-cloud/album-recommendation my-app",
+	Args:    cobra.ExactArgs(2),
 	Run: func(cmd *cobra.Command, args []string) {
 		cloneApplication(args[0], args[1])
 	},
diff --git a/client/go/cmd/config.go b/client/go/cmd/config.go
index 6a0b11545e5..87619deb3a5 100644
--- a/client/go/cmd/config.go
+++ b/client/go/cmd/config.go
@@ -29,8 +29,7 @@ func init() {
 
 var configCmd = &cobra.Command{
 	Use:   "config",
-	Short: "Configure the Vespa command",
-	Long:  "Get and set options for Vespa commands. This is an alternative to always specifying flags",
+	Short: "Configure default values for flags",
 	Run: func(cmd *cobra.Command, args []string) {
 		// Root command does nothing
 		cmd.Help()
@@ -41,7 +40,7 @@ var configCmd = &cobra.Command{
 var setConfigCmd = &cobra.Command{
 	Use:     "set option value",
 	Short:   "Set a configuration option.",
-	Example: "vespa config set target cloud",
+	Example: "$ vespa config set target cloud",
 	Args:    cobra.ExactArgs(2),
 	Run: func(cmd *cobra.Command, args []string) {
 		if err := setOption(args[0], args[1]); err != nil {
@@ -55,7 +54,7 @@ var setConfigCmd = &cobra.Command{
 var getConfigCmd = &cobra.Command{
 	Use:     "get option",
 	Short:   "Get a configuration option",
-	Example: "vespa config get target",
+	Example: "$ vespa config get target",
 	Args:    cobra.ExactArgs(1),
 	Run: func(cmd *cobra.Command, args []string) {
 		option := args[0]
diff --git a/client/go/cmd/deploy.go b/client/go/cmd/deploy.go
index a3f209ef5df..9428d7ca6b3 100644
--- a/client/go/cmd/deploy.go
+++ b/client/go/cmd/deploy.go
@@ -37,8 +37,8 @@ func init() {
 
 var deployCmd = &cobra.Command{
 	Use:   "deploy",
-	Short: "Deploys (prepares and activates) an application package",
-	Long:  `TODO`,
+	Short: "Deploy (prepare and activate) an application package",
+	Args:  cobra.MaximumNArgs(1),
 	Run: func(cmd *cobra.Command, args []string) {
 		d := vespa.Deployment{
 			ApplicationSource: applicationSource(args),
@@ -74,8 +74,8 @@ var deployCmd = &cobra.Command{
 
 var prepareCmd = &cobra.Command{
 	Use:   "prepare",
-	Short: "Prepares an application package for activation",
-	Long:  `TODO`,
+	Short: "Prepare an application package for activation",
+	Args:  cobra.MaximumNArgs(1),
 	Run: func(cmd *cobra.Command, args []string) {
 		resolvedSrc, err := vespa.Prepare(vespa.Deployment{ApplicationSource: applicationSource(args)})
 		if err == nil {
@@ -88,8 +88,8 @@ var prepareCmd = &cobra.Command{
 
 var activateCmd = &cobra.Command{
 	Use:   "activate",
-	Short: "Activates (deploys) the previously prepared application package",
-	Long:  `TODO`,
+	Short: "Activate (deploy) a previously prepared application package",
+	Args:  cobra.MaximumNArgs(1),
 	Run: func(cmd *cobra.Command, args []string) {
 		resolvedSrc, err := vespa.Activate(vespa.Deployment{ApplicationSource: applicationSource(args)})
 		if err == nil {
diff --git a/client/go/cmd/document.go b/client/go/cmd/document.go
index 71114fc8df6..6af6e36fa52 100644
--- a/client/go/cmd/document.go
+++ b/client/go/cmd/document.go
@@ -29,8 +29,9 @@ func init() {
 var documentCmd = &cobra.Command{
 	Use:   "document",
 	Short: "Issue document operations",
-	Long:  `TODO: Example vespa document mynamespace/mydocumenttype/myid document.json`,
-	// TODO: Check args
+	Example: `$ vespa document src/test/resources/A-Head-Full-of-Dreams.json
+# (short-hand for vespa document post)`,
+	Args: cobra.ExactArgs(1),
 	Run: func(cmd *cobra.Command, args []string) {
 		post("", args[0])
 	},
@@ -39,8 +40,9 @@ var documentCmd = &cobra.Command{
 var documentPostCmd = &cobra.Command{
 	Use:   "post",
 	Short: "Posts the document in the given file",
-	Long:  `TODO`,
-	// TODO: Check args
+	Args:  cobra.RangeArgs(1, 2),
+	Example: `$ vespa document post src/test/resources/A-Head-Full-of-Dreams.json
+$ vespa document post id:mynamespace:music::a-head-full-of-dreams src/test/resources/A-Head-Full-of-Dreams.json`,
 	Run: func(cmd *cobra.Command, args []string) {
 		if len(args) == 1 {
 			post("", args[0])
@@ -53,8 +55,7 @@ var documentPostCmd = &cobra.Command{
 var documentGetCmd = &cobra.Command{
 	Use:   "get",
 	Short: "Gets a document",
-	Long:  `TODO`,
-	// TODO: Check args
+	Args:  cobra.ExactArgs(1),
 	Run: func(cmd *cobra.Command, args []string) {
 		get(args[0])
 	},
diff --git a/client/go/cmd/query.go b/client/go/cmd/query.go
index 97ae416196d..75aa7a255b9 100644
--- a/client/go/cmd/query.go
+++ b/client/go/cmd/query.go
@@ -5,7 +5,6 @@
 package cmd
 
 import (
-	"errors"
 	"log"
 	"net/http"
 	"net/url"
@@ -26,12 +25,7 @@ var queryCmd = &cobra.Command{
 	Short: "Issue a query to Vespa",
 	Long:  `TODO, example  \"yql=select from sources * where title contains 'foo'\" hits=5`,
 	// TODO: Support referencing a query json file
-	Args: func(cmd *cobra.Command, args []string) error {
-		if len(args) < 1 {
-			return errors.New("vespa query requires at least one argument containing the query string")
-		}
-		return nil
-	},
+	Args: cobra.MinimumNArgs(1),
 	Run: func(cmd *cobra.Command, args []string) {
 		query(args)
 	},
diff --git a/client/go/cmd/root.go b/client/go/cmd/root.go
index 89dff2ccf85..336e1d64ea1 100644
--- a/client/go/cmd/root.go
+++ b/client/go/cmd/root.go
@@ -18,14 +18,10 @@ var (
 	// global flags
 	// TODO: add timeout flag
 	// TODO: add flag to show http request made
-
 	rootCmd = &cobra.Command{
 		Use:   "vespa",
 		Short: "A command-line tool for working with Vespa instances",
-		Long: `TO
-DO`,
 	}
-
 	color aurora.Aurora
 )
 
diff --git a/client/go/cmd/status.go b/client/go/cmd/status.go
index 800536bef76..8ae6656c114 100644
--- a/client/go/cmd/status.go
+++ b/client/go/cmd/status.go
@@ -21,8 +21,8 @@ func init() {
 
 var statusCmd = &cobra.Command{
 	Use:   "status",
-	Short: "Verifies that a vespa target is ready to use (query by default)",
-	Long:  `TODO`,
+	Short: "Verify that a Vespa target is ready to use (query by default)",
+	Args:  cobra.MaximumNArgs(1),
 	Run: func(cmd *cobra.Command, args []string) {
 		status(queryTarget(), "Query API")
 	},
@@ -30,8 +30,8 @@ var statusCmd = &cobra.Command{
 
 var statusQueryCmd = &cobra.Command{
 	Use:   "query",
-	Short: "Verifies that your Vespa query API container endpoint is ready [Default]",
-	Long:  `TODO`,
+	Short: "Verify that your Vespa query API container endpoint is ready [Default]",
+	Args:  cobra.ExactArgs(0),
 	Run: func(cmd *cobra.Command, args []string) {
 		status(queryTarget(), "Query API")
 	},
@@ -39,8 +39,8 @@ var statusQueryCmd = &cobra.Command{
 
 var statusDocumentCmd = &cobra.Command{
 	Use:   "document",
-	Short: "Verifies that your Vespa document API container endpoint is ready [Default]",
-	Long:  `TODO`,
+	Short: "Verify that your Vespa document API container endpoint is ready [Default]",
+	Args:  cobra.ExactArgs(0),
 	Run: func(cmd *cobra.Command, args []string) {
 		status(documentTarget(), "Document API")
 	},
@@ -48,8 +48,8 @@ var statusDocumentCmd = &cobra.Command{
 
 var statusDeployCmd = &cobra.Command{
 	Use:   "deploy",
-	Short: "Verifies that your Vespa deploy API config server endpoint is ready",
-	Long:  `TODO`,
+	Short: "Verify that your Vespa deploy API config server endpoint is ready",
+	Args:  cobra.ExactArgs(0),
 	Run: func(cmd *cobra.Command, args []string) {
 		status(deployTarget(), "Deploy API")
 	},