improve cli documentation

cmd/addDevice.go

@@ -40,7 +40,10 @@ import (
 var addDeviceCmd = &cobra.Command{
 	Use:   "add-device",
 	Short: "adds a device to the controller",
-	Long:  ``,
+	Long: `Adds a device to the controller. 
+	
+	Device address and user credentials need to be provided
+	if they diverge from the default credentials.`,
 	RunE: func(cmd *cobra.Command, args []string) error {
 		return cli.HTTPGet(
 			apiEndpoint,

cmd/capabilities.go

@@ -41,7 +41,7 @@ var capabilitiesCmd = &cobra.Command{
 	Use:   "capabilities",
 	Short: "capabilities request",
 	Long: `Sends a gNMI Capabilities request to the specified target
-// and prints the supported models to stdout.`,
+	and prints the supported models to stdout.`,
 	RunE: func(cmd *cobra.Command, args []string) error {
 		return cli.Capabilities(username, password, address)
 	},

cmd/cli.go

@@ -42,8 +42,9 @@ var apiEndpoint string
 // cliCmd represents the cli command
 var cliCmd = &cobra.Command{
 	Use:   "cli",
-	Short: "",
-	Long:  ``,
+	Short: "initialises the cli",
+	Long: `Initialises the CLI. The first PND UUID and SBI UUID 
+	are written to the config file for subsequent requests.`,
 	RunE: func(cmd *cobra.Command, args []string) error {
 		return cli.HTTPGet(apiEndpoint, "init")
 	},
@@ -52,7 +53,6 @@ var cliCmd = &cobra.Command{
 func init() {
 	rootCmd.AddCommand(cliCmd)
 
-	cliCmd.PersistentFlags().StringVar(&uuid, "uuid", "", "uuid of the requested device")
 	cliCmd.PersistentFlags().StringVar(&apiEndpoint, "api-endpoint", "http://gosdn-develop.apps.ocp.fbi.h-da.de/api", "address of the target")
 
 }

cmd/cliSet.go

@@ -39,8 +39,10 @@ import (
 // cliSetCmd represents the cliSet command
 var cliSetCmd = &cobra.Command{
 	Use:   "set",
+	Args:  cobra.ExactArgs(2),
 	Short: "set a value on a device",
-	Long:  ``,
+	Long: `Set a path value for a given device. Only one path and
+	only one value supported for now`,
 	RunE: func(cmd *cobra.Command, args []string) error {
 		return cli.HTTPGet(
 			apiEndpoint,
@@ -57,4 +59,6 @@ var cliSetCmd = &cobra.Command{
 
 func init() {
 	cliCmd.AddCommand(cliSetCmd)
+
+	cliCmd.Flags().StringVar(&uuid, "uuid", "", "uuid of the requested device")
 }

cmd/get.go

@@ -40,7 +40,8 @@ import (
 var getCmd = &cobra.Command{
 	Use:   "gosdn get",
 	Short: "get request",
-	Long:  `Sends a gNMI Get request to the specified target and prints the response to stdout`,
+	Long: `Sends a gNMI Get request to the specified target and
+	prints the response to stdout`,
 	RunE: func(cmd *cobra.Command, args []string) error {
 		_, err := cli.Get(address, username, password, args...)
 		return err

cmd/getDevice.go

@@ -39,13 +39,16 @@ import (
 // getDeviceCmd represents the getDevice command
 var getDeviceCmd = &cobra.Command{
 	Use:   "get-device",
+	Args:  cobra.ExactArgs(1),
 	Short: "gets device information from the controller",
-	Long:  ``,
+	Long: `Gets device information from the controller.
+	
+	Device UUID needs to be specified as positional argument.`,
 	RunE: func(cmd *cobra.Command, args []string) error {
 		return cli.HTTPGet(
 			apiEndpoint,
 			"getDevice",
-			"uuid="+uuid,
+			"uuid="+args[0],
 			"sbi="+cliSbi,
 			"pnd="+cliPnd,
 		)

cmd/getIds.go

@@ -40,7 +40,7 @@ import (
 var getIdsCmd = &cobra.Command{
 	Use:   "get-ids",
 	Short: "gets device IDs from the controller",
-	Long:  ``,
+	Long:  `Gets device IDs from the controller and lists them.`,
 	RunE: func(cmd *cobra.Command, args []string) error {
 		return cli.HTTPGet(apiEndpoint, "getIDs")
 	},

cmd/init.go

@@ -40,7 +40,9 @@ import (
 var initCmd = &cobra.Command{
 	Use:   "init",
 	Short: "initialise SBI and PND",
-	Long:  ``,
+	Long: `Initialise SBI and PND and saves values to config file.
+	
+	Same as invoking "gosdn cli" without any arguments`,
 	RunE: func(cmd *cobra.Command, args []string) error {
 		return cli.HTTPGet(apiEndpoint, "init")
 	},

cmd/request.go

@@ -39,8 +39,11 @@ import (
 // requestCmd represents the request command
 var requestCmd = &cobra.Command{
 	Use:   "request",
+	Args:  cobra.ExactArgs(1),
 	Short: "requests a path from a specified device on the controller",
-	Long:  ``,
+	Long: `Requests a path from a specified device on the controller.
+	
+	The request path is passed as positional argument.`,
 	RunE: func(cmd *cobra.Command, args []string) error {
 		return cli.HTTPGet(
 			apiEndpoint,
@@ -55,4 +58,6 @@ var requestCmd = &cobra.Command{
 
 func init() {
 	cliCmd.AddCommand(requestCmd)
+
+	cliCmd.Flags().StringVar(&uuid, "uuid", "", "uuid of the requested device")
 }

cmd/requestAll.go

@@ -39,8 +39,12 @@ import (
 // requestAllCmd represents the requestAll command
 var requestAllCmd = &cobra.Command{
 	Use:   "request-all",
+	Args:  cobra.ExactArgs(1),
 	Short: "requests specified path from all devices on the controller",
-	Long:  ``,
+	Long: `Requests a path from all devices on the controller known by
+	the controller.
+	
+	The request path is passed as positional argument.`,
 	RunE: func(cmd *cobra.Command, args []string) error {
 		return cli.HTTPGet(
 			apiEndpoint,

cmd/root.go

@@ -32,11 +32,12 @@ POSSIBILITY OF SUCH DAMAGE.
 package cmd
 
 import (
-	"code.fbi.h-da.de/cocsn/gosdn/nucleus"
 	"context"
+	"os"
+
+	"code.fbi.h-da.de/cocsn/gosdn/nucleus"
 	log "github.com/sirupsen/logrus"
 	"github.com/spf13/cobra"
-	"os"
 
 	"github.com/spf13/viper"
 )
@@ -54,7 +55,8 @@ var cliSbi string
 var rootCmd = &cobra.Command{
 	Use:   "gosdn",
 	Short: "starts the gosdn controller",
-	Long:  `Set GOSDN_DEBUG environment variable to enable debug logging.`,
+	Long: `Starts the gosdn controller and listens on port 8080
+	for REST API calls.`,
 	RunE: func(cmd *cobra.Command, args []string) error {
 		ctx, cancel := context.WithCancel(context.Background())
 		defer cancel()
@@ -74,10 +76,6 @@ func Execute() {
 func init() {
 	cobra.OnInitialize(initConfig)
 
-	// Here you will define your flags and configuration settings.
-	// Cobra supports persistent flags, which, if defined here,
-	// will be global for your application.
-
 	rootCmd.PersistentFlags().StringVar(&cfgFile, "config", "", "config file (default is ./configs/gosdn.toml)")
 	rootCmd.PersistentFlags().StringVarP(&username, "username", "u", "admin", "username for a gnmi resource")
 	rootCmd.PersistentFlags().StringVarP(&password, "password", "p", "arista", "password for a gnmi resource")