📄 Add long-form CLI help for a bunch of providers (#4724)

* Add long-form help for a bunch of providers * Change per @tas50 review * Change per @tas50 review
mondoohq · Oct 8, 2024 · 42afb51 · 42afb51 · github-actions · Oct 8, 2024
1 parent d5fb223
commit 42afb51
Show file tree

Hide file tree

Showing 5 changed files with 48 additions and 18 deletions.
diff --git a/providers/ipmi/config/config.go b/providers/ipmi/config/config.go
@@ -17,11 +17,16 @@ var Config = plugin.Provider{
 	Connectors: []plugin.Connector{
 		{
 			Name:  "ipmi",
-			Use:   "ipmi user@host",
+			Use:   "ipmi USER@HOST",
 			Short: "an IPMI interface",
-			Long: `ipmi is designed for querying resources via the Intelligent Platform Management Interface (IPMI).
-IPMI provides management and monitoring capabilities  independently of the host system's CPU,
+			Long: `Use the ipmi provider to query resources using the Intelligent Platform Management Interface (IPMI).
+
+IPMI provides management and monitoring capabilities independently of the host system's CPU,
 firmware (BIOS or UEFI), and operating system.
+
+Examples:
+  cnquery shell ipmi <user@host>
+	cnspec scan ipmi <user@host>
 `,
 			MinArgs:   1,
 			MaxArgs:   1,

diff --git a/providers/mondoo/config/config.go b/providers/mondoo/config/config.go
@@ -15,9 +15,17 @@ var Config = plugin.Provider{
 	ConnectionTypes: []string{provider.DefaultConnectionType},
 	Connectors: []plugin.Connector{
 		{
-			Name:      "mondoo",
-			Use:       "mondoo",
-			Short:     "Mondoo Platform",
+			Name:  "mondoo",
+			Use:   "mondoo",
+			Short: "Mondoo Platform",
+			Long: `Use the mondoo provider to query resources in Mondoo Platform.
+
+To query Mondoo Platform from a workstation, the workstation must be registered with Mondoo Platform. To learn how to register a workstation, read https://mondoo.com/docs/cnspec/cnspec-adv-install/registration/. 
+
+Examples:
+  cnquery shell mondoo
+	cnspec scan mondoo
+`,
 			MinArgs:   0,
 			MaxArgs:   4,
 			Discovery: []string{},

diff --git a/providers/okta/config/config.go b/providers/okta/config/config.go
@@ -16,22 +16,30 @@ var Config = plugin.Provider{
 	ConnectionTypes: []string{provider.ConnectionType},
 	Connectors: []plugin.Connector{
 		{
-			Name:      "okta",
-			Use:       "okta",
-			Short:     "an Okta organization",
+			Name:  "okta",
+			Use:   "okta",
+			Short: "an Okta organization",
+			Long: `Use the okta provider to query resources in an Okta organization.
+
+To query an Okta organization, you need the organization's domain and an API token to access that domain. To learn how, read https://mondoo.com/docs/cnquery/saas/okta/.
+
+Examples:
+  cnquery shell okta -organization <okta-domain> -token <api-token>
+	cnspec scan okta -organization <okta-domain> -token <api-token>
+`,
 			Discovery: []string{},
 			Flags: []plugin.Flag{
 				{
 					Long:    "organization",
 					Type:    plugin.FlagType_String,
 					Default: "",
-					Desc:    "The Okta organization to scan",
+					Desc:    "The domain of the Okta organization to scan",
 				},
 				{
 					Long:    "token",
 					Type:    plugin.FlagType_String,
 					Default: "",
-					Desc:    "Okta access token",
+					Desc:    "Access token for the Okta organization",
 				},
 			},
 		},

diff --git a/providers/opcua/config/config.go b/providers/opcua/config/config.go
@@ -18,11 +18,12 @@ var Config = plugin.Provider{
 			Name:  "opcua",
 			Use:   "opcua [--endpoint <endpoint>]",
 			Short: "an OPC UA device",
-			Long: `opcua is designed for querying resources on an OPC UA (Open Platform 
-Communications Unified Architecture) server, a protocol facilitating machine-to-machine communications within 
-the realm of industrial automation.
-`,
+			Long: `Use the opcua provider to query resources on an Open Platform 
+Communications Unified Architecture (OPC UA) server or device. OPC UA is a protocol facilitating machine-to-machine communications within the realm of industrial automation.
 
+Example:
+  cnquery shell opcua --endpoint opc.tcp://<host>:<port>
+`,
 			Discovery: []string{},
 			Flags: []plugin.Flag{
 				{

diff --git a/providers/shodan/config/config.go b/providers/shodan/config/config.go
@@ -17,9 +17,17 @@ var Config = plugin.Provider{
 	ConnectionTypes: []string{provider.DefaultConnectionType},
 	Connectors: []plugin.Connector{
 		{
-			Name:    "shodan",
-			Use:     "shodan",
-			Short:   "a Shodan account",
+			Name:  "shodan",
+			Use:   "shodan",
+			Short: "a Shodan account",
+			Long: `Use the shodan provider to query domain and IP security information in the Shodan search engine. 
+
+If you set the SHODAN_TOKEN environment variable, you can omit the token flag.
+
+Examples:
+  cnquery shell shodan --token <api-token>
+	cnquery shell shodan --networks <ip-range> --discover hosts
+`,
 			MinArgs: 0,
 			MaxArgs: 2,
 			Discovery: []string{