docs(cli): func comments and cmd style updates

Signed-off-by: Salim Afiune Maya <[email protected]>

README.md

@@ -27,7 +27,7 @@ C:\> iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubus
 
 Look at the [cli/](cli/) folder for more documentation.
 
-## API Client ([`api`](api/))
+## Lacework API Client ([`api`](api/))
 
 A Golang API client for interacting with the [Lacework API](https://support.lacework.com/hc/en-us/categories/360002496114-Lacework-API-).
 

cli/cmd/api.go

@@ -56,6 +56,7 @@ For a complete list of available API endpoints visit:
 )
 
 func init() {
+	// add the api command
 	rootCmd.AddCommand(apiCmd)
 
 	apiCmd.Flags().StringVarP(&apiData,

cli/cmd/cli_state.go

@@ -130,69 +130,73 @@ func (c *cliState) VerifySettings() error {
 
 // NonInteractive turns off interactive mode, that is, no progress bars and spinners
 func (c *cliState) NonInteractive() {
-	cli.Log.Info("turning off interactive mode")
+	c.Log.Info("turning off interactive mode")
 	c.nonInteractive = true
 }
 
 // StartProgress starts a new progress spinner with the provider suffix and stores it
 // into the cli state, make sure to run StopSpinner when you are done processing
 func (c *cliState) StartProgress(suffix string) {
 	if c.nonInteractive {
-		cli.Log.Debugw("skipping spinner",
+		c.Log.Debugw("skipping spinner",
 			"noninteractive", c.nonInteractive,
 			"action", "start_progress",
 		)
 		return
 	}
 
 	// humans like spinners (^.^)
-	if cli.HumanOutput() {
+	if c.HumanOutput() {
 		// make sure there is not a spinner already running
-		cli.StopProgress()
+		c.StopProgress()
 
-		cli.Log.Debug("starting spinner")
-		cli.spinner = spinner.New(spinner.CharSets[9], 100*time.Millisecond)
-		cli.spinner.Suffix = suffix
-		cli.spinner.Start()
+		c.Log.Debug("starting spinner")
+		c.spinner = spinner.New(spinner.CharSets[9], 100*time.Millisecond)
+		c.spinner.Suffix = suffix
+		c.spinner.Start()
 	}
 }
 
 // StopProgress stops the running progress spinner, if any
 func (c *cliState) StopProgress() {
 	if c.nonInteractive {
-		cli.Log.Debugw("skipping spinner",
+		c.Log.Debugw("skipping spinner",
 			"noninteractive", c.nonInteractive,
 			"action", "stop_progress",
 		)
 		return
 	}
 
 	// humans like spinners (^.^)
-	if cli.HumanOutput() {
-		if cli.spinner != nil {
-			cli.Log.Debug("stopping spinner")
-			cli.spinner.Stop()
-			cli.spinner = nil
+	if c.HumanOutput() {
+		if c.spinner != nil {
+			c.Log.Debug("stopping spinner")
+			c.spinner.Stop()
+			c.spinner = nil
 		}
 	}
 }
 
+// EnableJSONOutput enables the cli to display JSON output
 func (c *cliState) EnableJSONOutput() {
-	cli.Log.Info("switch output to json format")
-	cli.jsonOutput = true
+	c.Log.Info("switch output to json format")
+	c.jsonOutput = true
 }
 
+// EnableJSONOutput enables the cli to display human readable output
 func (c *cliState) EnableHumanOutput() {
-	cli.Log.Info("switch output to human format")
-	cli.jsonOutput = false
+	c.Log.Info("switch output to human format")
+	c.jsonOutput = false
 }
 
+// JSONOutput returns true if the cli is configured to display JSON output
 func (c *cliState) JSONOutput() bool {
-	return cli.jsonOutput
+	return c.jsonOutput
 }
 
+// HumanOutput returns true if the cli is configured to siplay human readable output
 func (c *cliState) HumanOutput() bool {
-	return !cli.jsonOutput
+	return !c.jsonOutput
 }
 
 // loadStateFromViper loads parameters and environment variables

cli/cmd/cli_update_cmd.go

@@ -19,6 +19,8 @@
 
 package cmd
 
+// UpdateCommand returns the command that a user should run to update the cli
+// to the latest available version (unix specific command)
 func (c *cliState) UpdateCommand() string {
 	return `
   $ curl https://raw.githubusercontent.com/lacework/go-sdk/master/cli/install.sh | sudo bash

cli/cmd/cli_update_cmd_windows.go

@@ -18,6 +18,8 @@
 
 package cmd
 
+// UpdateCommand returns the command that a user should run to update the cli
+// to the latest available version (windows specific command)
 func (c *cliState) UpdateCommand() string {
 	return `
   C:\> Set-ExecutionPolicy Bypass -Scope Process -Force

cli/cmd/event.go

@@ -41,8 +41,10 @@ var (
 	eventListCmd = &cobra.Command{
 		Use:   "list",
 		Short: "list all events from a date range (default last 7 days)",
-		Long: `List all events from a data range, by default it displays the last
-7 days, but you can specify a different time range.`,
+		Long: `
+List all events from a time range, by default this command displays the
+events from the last 7 days, but it is possible to specify a different
+time range.`,
 		Args: cobra.NoArgs,
 		RunE: func(_ *cobra.Command, _ []string) error {
 			lacework, err := api.NewClient(cli.Account,

cli/cmd/outputs.go

@@ -44,7 +44,7 @@ func (c *cliState) OutputHuman(format string, a ...interface{}) {
 	}
 }
 
-// OutputJSONString just like OutputJSON but passing a JSON string
+// OutputJSONString is just like OutputJSON but from a JSON string
 func (c *cliState) OutputJSONString(s string) error {
 	pretty, err := c.JsonF.Format([]byte(s))
 	if err != nil {

cli/cmd/version.go

@@ -44,8 +44,11 @@ var (
 	versionCmd = &cobra.Command{
 		Use:   "version",
 		Short: "print the Lacework CLI version",
-		Long: `Prints out the installed version of the Lacework CLI and checks for newer
-versions available for update.`,
+		Long: `
+Prints out the installed version of the Lacework CLI and checks for newer
+versions available for update.
+
+Set the environment variable 'LW_UPDATES_DISABLE=1' to avoid checking for updates.`,
 		Args: cobra.NoArgs,
 		Run: func(_ *cobra.Command, _ []string) {
 			if cli.JSONOutput() {

cli/cmd/vulnerability.go

@@ -69,7 +69,7 @@ Then navigate to Settings > Integrations > Container Registry.`,
 	// vulScanCmd represents the scan sub-command inside the vulnerability command
 	vulScanCmd = &cobra.Command{
 		Use:   "scan",
-		Short: "Manage on-demand vulnerability scans",
+		Short: "manage on-demand vulnerability scans",
 		Long: `Request on-demand vulnerability scans and view the generated report.
 
 NOTE: Scans can take up to 15 minutes to return results.`,
@@ -78,13 +78,13 @@ NOTE: Scans can take up to 15 minutes to return results.`,
 	// vulScanRunCmd represents the run sub-command inside the scan vulnerability command
 	vulScanRunCmd = &cobra.Command{
 		Use:   "run <registry> <repository> <tag|image_id>",
-		Short: "Request an on-demand vulnerability scan",
-		Long: `Request an on-demand vulnerability scan
+		Short: "request an on-demand vulnerability scan",
+		Long: `Request an on-demand vulnerability scan.
 
 Arguments:
-  <registry>      container registry where the container image is published
+  <registry>      container registry where the container image has been published
   <repository>    repository name that contains the container image
-  <tag|image_id>  either the tag or the image ID to scan (image_id format: sha256:1ee...1d3b)`,
+  <tag|image_id>  either a tag or an image ID to scan (image_id format: sha256:1ee...1d3b)`,
 		Args: cobra.ExactArgs(3),
 		RunE: func(_ *cobra.Command, args []string) error {
 			lacework, err := api.NewClient(cli.Account,
@@ -139,7 +139,8 @@ Arguments:
 	// vulScanShowCmd represents the show sub-command inside the scan vulnerability command
 	vulScanShowCmd = &cobra.Command{
 		Use:   "show <request_id>",
-		Short: "Return data about an on-demand vulnerability scan",
+		Short: "return results about an on-demand vulnerability scan",
+		Long:  "Return results about an on-demand vulnerability scan.",
 		Args:  cobra.ExactArgs(1),
 		RunE: func(_ *cobra.Command, args []string) error {
 			lacework, err := api.NewClient(cli.Account,
@@ -185,7 +186,7 @@ Arguments:
 	// vulReportCmd represents the report sub-command inside the vulnerability command
 	vulReportCmd = &cobra.Command{
 		Use:   "report <sha256:hash>",
-		Short: "Show vulnerability reports of a container image",
+		Short: "show vulnerability reports of a container image",
 		Long: `Review vulnerability reports from container image scans that run previously either
 by the preriodic scan mechanism that Lacework runs every hour, or a requested
 on-demand vulnerability scan.