In CLI docs, examples updates (#39)

* in-cli docs, examples updates

* fix typo

* fix capital letter

* http docs info on 2 formats

* remove docs link about magic

* update ping long description

* extend ping long help

* text improvements

* move latency flag to global

---------

Co-authored-by: Dmitriy Akulov <dakulovgr@gmail.com>

cmd/dns.go

@@ -12,7 +12,7 @@ import (
 var dnsCmd = &cobra.Command{
 	Use:     "dns [target] from [location]",
 	GroupID: "Measurements",
-	Short:   "Use the native dig command",
+	Short:   "Resolve a DNS record similarly to dig",
 	Long: `Performs DNS lookups and displays the answers that are returned from the name server(s) that were queried.
 The default nameserver depends on the probe and is defined by the user's local settings or DHCP.
 
@@ -23,11 +23,17 @@ Examples:
   # Resolve google.com from 2 probes from London or Belgium with trace enabled
   dns google.com from London,Belgium --limit 2 --trace
 
+  # Resolve google.com from a probe in Paris using the TCP protocol
+  dns google.com from Paris --protocol tcp
+
+  # Resolve jsdelivr.com from a probe in Berlin using the type MX and the resolver 1.1.1.1 in CI mode
+  dns jsdelivr.com from Berlin --type MX --resolver 1.1.1.1 --ci
+
   # Resolve jsdelivr.com from a probe that is from the AWS network and is located in Montreal with latency output
   dns jsdelivr.com from aws+montreal --latency
 
-  # Resolve jsdelivr.com with ASN 12345 with json output
-  dns jsdelivr.com from 12345 --json`,
+  # Resolve jsdelivr.com from a probe in ASN 123 with json output
+  dns jsdelivr.com from 123 --json`,
 	Args: checkCommandFormat(),
 	RunE: func(cmd *cobra.Command, args []string) error {
 		// Create context
@@ -75,10 +81,7 @@ func init() {
 	// dns specific flags
 	dnsCmd.Flags().StringVar(&protocol, "protocol", "", "Specifies the protocol to use for the DNS query (TCP or UDP) (default \"udp\")")
 	dnsCmd.Flags().IntVar(&port, "port", 0, "Send the query to a non-standard port on the server (default 53)")
-	dnsCmd.Flags().StringVar(&resolver, "resolver", "", "Resolver is the name or IP address of the name server to query (default empty)")
+	dnsCmd.Flags().StringVar(&resolver, "resolver", "", "Resolver is the hostname or IP address of the name server to use (default empty)")
 	dnsCmd.Flags().StringVar(&queryType, "type", "", "Specifies the type of DNS query to perform (default \"A\")")
 	dnsCmd.Flags().BoolVar(&trace, "trace", false, "Toggle tracing of the delegation path from the root name servers (default false)")
-
-	// Extra flags
-	dnsCmd.Flags().BoolVar(&ctx.Latency, "latency", false, "Output only stats of a measurement (default false)")
 }

cmd/http.go

@@ -83,20 +83,31 @@ var httpCmd = &cobra.Command{
 	Use:     "http [target] from [location]",
 	GroupID: "Measurements",
 	Short:   "Perform a HEAD or GET request to a host",
-	Long: `The http command sends an HTTP request to a host and can perform HEAD or GET operations. GET is limited to 10KB responses, everything above will be cut by the API.
+	Long: `The http command sends an HTTP request to a host and can perform HEAD or GET operations. GET is limited to 10KB responses, everything above will be cut by the API. Detailed performance stats as available for every request.
+The tool supports 2 formats for this command:
+When the full url is supplied, the tool autoparses the scheme, host, port, domain, path and query. For example:
+  http https://www.jsdelivr.com:443/package/npm/test?nav=stats
+As an alternative that can be useful for scripting, the scheme, host, port, domain, path and query can be provided as separate command line flags. For example:
+  http jsdelivr.com --host www.jsdelivr.com --protocol https --port 443 --path "/package/npm/test" --query "nav=stats"
 
 Examples:
   # HTTP HEAD request to jsdelivr.com from 2 probes in New York (protocol, port and path are inferred from the URL)
   http https://www.jsdelivr.com:443/package/npm/test?nav=stats from New York --limit 2
 
-  # HTTP GET request to google.com from 2 probes from London or Belgium
-  http google.com from London,Belgium --limit 2 --method get
+  # HTTP GET request to google.com from 2 probes from London or Belgium in CI mode
+  http google.com from London,Belgium --limit 2 --method get --ci
 
   # HTTP HEAD request to jsdelivr.com from a probe that is from the AWS network and is located in Montreal using HTTP2
   http jsdelivr.com from aws+montreal --protocol http2
 
-  # HTTP GET request google.com with ASN 12345 with json output
-  http google.com from 12345 --json`,
+  # HTTP HEAD request to jsdelivr.com from a probe that is located in Paris, using the /robots.txt path with "test=1" query string
+  http jsdelivr.com from Paris --path /robots.txt --query "test=1"
+
+  # HTTP HEAD request to example.com from a probe that is located in Berlin, specifying a different host example.org in the request headers
+  http example.com from Berlin --host example.org
+
+  # HTTP GET request google.com from a probe in ASN 123 with a dns resolver 1.1.1.1 and json output
+  http google.com from 123 --resolver 1.1.1.1 --json`,
 	Args: checkCommandFormat(),
 	RunE: httpCmdRun,
 }
@@ -186,8 +197,5 @@ func init() {
 	httpCmd.Flags().StringVar(&httpCmdOpts.Method, "method", "", "Specifies the HTTP method to use (HEAD or GET) (default \"HEAD\")")
 	httpCmd.Flags().StringVar(&httpCmdOpts.Protocol, "protocol", "", "Specifies the query protocol (HTTP, HTTPS, HTTP2) (default \"HTTP\")")
 	httpCmd.Flags().IntVar(&httpCmdOpts.Port, "port", 0, "Specifies the port to use (default 80 for HTTP, 443 for HTTPS and HTTP2)")
-	httpCmd.Flags().StringVar(&httpCmdOpts.Resolver, "resolver", "", "Specifies the resolver server used for DNS lookup")
-
-	// Extra flags
-	httpCmd.Flags().BoolVar(&ctx.Latency, "latency", false, "Output only stats of a measurement (default false)")
+	httpCmd.Flags().StringVar(&httpCmdOpts.Resolver, "resolver", "", "Specifies the resolver server used for DNS lookup (default is defined by the probe's network)")
 }

cmd/mtr.go

@@ -12,21 +12,21 @@ import (
 var mtrCmd = &cobra.Command{
 	Use:     "mtr [target] from [location]",
 	GroupID: "Measurements",
-	Short:   "Use the native mtr command",
+	Short:   "Run an MTR test, similar to traceroute",
 	Long: `mtr combines the functionality of the traceroute and ping programs in a single network diagnostic tool.
 
 Examples:
   # MTR google.com from 2 probes in New York
   mtr google.com from New York --limit 2
 
-  # MTR 1.1.1.1 from 2 probes from North America or Belgium with 10 packets
-  mtr 1.1.1.1 from North America,Belgium --limit 2 --packets 10
+  # MTR 1.1.1.1 from 2 probes from USA or Belgium with 10 packets in CI mode
+  mtr 1.1.1.1 from USA,Belgium --limit 2 --packets 10 --ci
 
-  # MTR jsdelivr.com from a probe that is from the AWS network and is located in Montreal using the TCP protocol
-  mtr jsdelivr.com from aws+montreal --protocol tcp
+  # MTR jsdelivr.com from a probe that is from the AWS network and is located in Montreal using the TCP protocol and port 453
+  mtr jsdelivr.com from aws+montreal --protocol tcp --port 453
 
-  # MTR jsdelivr.com with ASN 12345 with json output
-  mtr jsdelivr.com from 12345 --json`,
+  # MTR jsdelivr.com from a probe in ASN 123 with json output
+  mtr jsdelivr.com from 123 --json`,
 	Args: checkCommandFormat(),
 	RunE: func(cmd *cobra.Command, args []string) error {
 		// Create context
@@ -35,6 +35,10 @@ Examples:
 			return err
 		}
 
+		if ctx.Latency {
+			return fmt.Errorf("the latency flag is not supported by the mtr command")
+		}
+
 		// Make post struct
 		opts = model.PostMeasurement{
 			Type:              "mtr",
@@ -67,10 +71,7 @@ func init() {
 	rootCmd.AddCommand(mtrCmd)
 
 	// mtr specific flags
-	mtrCmd.Flags().StringVar(&protocol, "protocol", "", "Specifies the protocol used for tracerouting (ICMP, TCP or UDP) (default \"icmp\")")
-	mtrCmd.Flags().IntVar(&port, "port", 0, "Specifies the port to use for the traceroute. Only applicable for TCP protocol (default 53)")
+	mtrCmd.Flags().StringVar(&protocol, "protocol", "", "Specifies the protocol used (ICMP, TCP or UDP) (default \"icmp\")")
+	mtrCmd.Flags().IntVar(&port, "port", 0, "Specifies the port to use. Only applicable for TCP protocol (default 53)")
 	mtrCmd.Flags().IntVar(&packets, "packets", 0, "Specifies the number of packets to send to each hop (default 3)")
-
-	// Extra flags
-	// mtrCmd.Flags().BoolVar(&ctx.Latency, "latency", false, "Output only stats of a measurement (default false)")
 }

cmd/ping.go

@@ -12,21 +12,21 @@ import (
 var pingCmd = &cobra.Command{
 	Use:     "ping [target] from [location]",
 	GroupID: "Measurements",
-	Short:   "Use the native ping command",
-	Long: `The ping command sends an ICMP ECHO_REQUEST to obtain an ICMP ECHO_RESPONSE from a host or gateway.
+	Short:   "Run a ping test",
+	Long: `The ping command allows sending ping requests to a target. Often used to test the network latency and stability.
 
 Examples:
   # Ping google.com from 2 probes in New York
   ping google.com from New York --limit 2
 
-  # Ping 1.1.1.1 from 2 probes from North America or Belgium with 10 packets
-  ping 1.1.1.1 from North America,Belgium --limit 2 --packets 10
+  # Ping 1.1.1.1 from 2 probes from USA or Belgium with 10 packets in CI mode
+  ping 1.1.1.1 from USA,Belgium --limit 2 --packets 10 --ci
 
   # Ping jsdelivr.com from a probe that is from the AWS network and is located in Montreal with latency output
   ping jsdelivr.com from aws+montreal --latency
 
-  # Ping jsdelivr.com with ASN 12345 with json output
-  ping jsdelivr.com from 12345 --json`,
+  # Ping jsdelivr.com from a probe in ASN 123 with json output
+  ping jsdelivr.com from 123 --json`,
 	Args: checkCommandFormat(),
 	RunE: func(cmd *cobra.Command, args []string) error {
 		// Create context
@@ -66,7 +66,4 @@ func init() {
 
 	// ping specific flags
 	pingCmd.Flags().IntVar(&packets, "packets", 0, "Specifies the desired amount of ECHO_REQUEST packets to be sent (default 3)")
-
-	// Extra flags
-	pingCmd.Flags().BoolVar(&ctx.Latency, "latency", false, "Output only the stats of a measurement (default false)")
 }

cmd/root.go

@@ -35,7 +35,7 @@ var rootCmd = &cobra.Command{
 	Use:   "globalping",
 	Short: "A global network of probes to run network tests like ping, traceroute and DNS resolve.",
 	Long: `Globalping is a platform that allows anyone to run networking commands such as ping, traceroute, dig and mtr on probes distributed all around the world.
-	The CLI tool allows you to interact with the API in a simple and human-friendly way to debug networking issues like anycast routing and script automated tests and benchmarks.`,
+The CLI tool allows you to interact with the API in a simple and human-friendly way to debug networking issues like anycast routing and script automated tests and benchmarks.`,
 }
 
 // Execute adds all child commands to the root command and sets flags appropriately.
@@ -52,10 +52,11 @@ func Execute(ver string) {
 
 func init() {
 	// Global flags
-	rootCmd.PersistentFlags().StringVarP(&ctx.From, "from", "F", "", "A continent, region (e.g eastern europe), country, US state or city (default \"world\")")
+	rootCmd.PersistentFlags().StringVarP(&ctx.From, "from", "F", "", `Comma-separated list of location values to match against. For example the partial or full name of a continent, region (e.g eastern europe), country, US state, city or network (default "world").`)
 	rootCmd.PersistentFlags().IntVarP(&ctx.Limit, "limit", "L", 1, "Limit the number of probes to use")
 	rootCmd.PersistentFlags().BoolVarP(&ctx.JsonOutput, "json", "J", false, "Output results in JSON format (default false)")
-	rootCmd.PersistentFlags().BoolVarP(&ctx.CI, "ci", "C", false, "Disable realtime terminal updates and color suitable for CI (default false)")
+	rootCmd.PersistentFlags().BoolVarP(&ctx.CI, "ci", "C", false, "Disable realtime terminal updates and color suitable for CI and scripting (default false)")
+	rootCmd.PersistentFlags().BoolVar(&ctx.Latency, "latency", false, "Output only the stats of a measurement (default false). Only applies to the dns, http and ping commands")
 }
 
 // checkCommandFormat checks if the command is in the correct format if using the from arg

cmd/traceroute.go

@@ -12,21 +12,24 @@ import (
 var tracerouteCmd = &cobra.Command{
 	Use:     "traceroute [target] from [location]",
 	GroupID: "Measurements",
-	Short:   "Use the native traceroute command",
-	Long: `traceroute tracks the route packets taken from an IP network on their way to a given host. It utilizes the IP protocol's time to live (TTL) field and attempts to elicit an ICMP TIME_EXCEEDED response from each gateway along the path to the host.
+	Short:   "Run a traceroute test",
+	Long: `traceroute tracks the route packets take from an IP network on their way to a given host.
 
 Examples:
   # Traceroute google.com from 2 probes in New York
   traceroute google.com from New York --limit 2
 
-  # Traceroute 1.1.1.1 from 2 probes from North America or Belgium
-  traceroute 1.1.1.1 from North America,Belgium --limit 2
+  # Traceroute 1.1.1.1 from 2 probes from USA or Belgium in CI mode
+  traceroute 1.1.1.1 from USA,Belgium --limit 2 --ci
 
   # Traceroute jsdelivr.com from a probe that is from the AWS network and is located in Montreal using the UDP protocol
   traceroute jsdelivr.com from aws+montreal --protocol udp
 
-  # Traceroute jsdelivr.com with ASN 12345 with json output
-  traceroute jsdelivr.com from 12345 --json`,
+  # Traceroute jsdelivr.com from a probe that is located in Paris to port 453
+  traceroute jsdelivr.com from Paris --port 453
+
+  # Traceroute jsdelivr.com from a probe in ASN 123 with json output
+  traceroute jsdelivr.com from 123 --json`,
 	Args: checkCommandFormat(),
 	RunE: func(cmd *cobra.Command, args []string) error {
 		// Create context
@@ -35,6 +38,10 @@ Examples:
 			return err
 		}
 
+		if ctx.Latency {
+			return fmt.Errorf("the latency flag is not supported by the traceroute command")
+		}
+
 		// Make post struct
 		opts = model.PostMeasurement{
 			Type:              "traceroute",