agent: extend cli help information

cli/agent/command.go

@@ -30,14 +30,16 @@ func NewCommand() *cobra.Command {
 The Pico agent is a CLI that runs alongside your upstream service that
 registers one or more listeners.
 
-The agent will connect to a Pico server, register the configured listeners,
-then forwards incoming requests to your upstream service.
+The agent will open an outbound connection to a Pico server for each of the
+configured listener. This connection is kept open and is used to receive
+proxied requets from the server which are then forwarded to the configured
+address, then the response is sent back to the Pico server.
 
 Such as if you have a service running at 'localhost:3000', you can register
 endpoint 'my-endpoint' that forwards requests to that local service.
 
 Examples:
-  # Register a listener with endpoint ID 'my-endpoing-123' that forwards
+  # Register a listener with endpoint ID 'my-endpoint-123' that forwards
   # requests to 'localhost:3000'.
   pico agent --listener my-endpoint-123/localhost:3000
 
@@ -53,16 +55,102 @@ Examples:
 
 	var conf config.Config
 
-	cmd.Flags().StringSliceVar(&conf.Listeners, "listeners", nil, "command separated listeners to register, with format '<endpoint ID>/<forward addr>'")
+	cmd.Flags().StringSliceVar(
+		&conf.Listeners,
+		"listeners",
+		nil,
+		`
+The listeners to register with the Pico server.
+
+Each listener registers with an endpoint ID and forward address. The agent
+will open a outbound connection to the server for each listener and register
+that listener for the endpoint ID. Pico will then forward requests for that
+endpoint ID to the agent via the outbound connection, then the agent forwards
+the request on to the registered forward address.
+
+'--listeners' is a comma separated list of listeners with format:
+'<endpoint ID>/<forward addr>'. Such as '--listeners 6ae6db60/localhost:3000'
+will register the listener for endpoint '6ae6db60' then forward incoming
+requests to 'localhost:3000'.
+
+You may register multiple listeners which have their own connection to Pico,
+such as '--listeners 6ae6db60/localhost:3000,941c3c2e/localhost:4000'.`,
+	)
+
+	cmd.Flags().StringVar(
+		&conf.Server.URL,
+		"server.url",
+		"http://localhost:8080",
+		`
+Pico server URL.
+
+The listener will add path /pico/v1/listener/:endpoint_id to the given URL,
+so if you include a path it will be used as a prefix.
+
+Note Pico connects to the server with WebSockets, so will replace http/https
+with ws/wss (you can configure either).
+`,
+	)
+	cmd.Flags().IntVar(
+		&conf.Server.HeartbeatIntervalSeconds,
+		"server.heartbeat-interval-seconds",
+		10,
+		`
+Heartbeat interval in seconds.
 
-	cmd.Flags().StringVar(&conf.Server.URL, "server.url", "http://localhost:8080", "Pico server URL")
-	cmd.Flags().IntVar(&conf.Server.HeartbeatIntervalSeconds, "server.heartbeat-interval-seconds", 10, "Heartbeat interval in seconds")
-	cmd.Flags().IntVar(&conf.Server.HeartbeatTimeoutSeconds, "server.heartbeat-timeout-seconds", 10, "Heartbeat timeout in seconds")
+To verify the connection to the server is ok, the listener sends a
+heartbeat to the upstream at the '--server.heartbeat-interval-seconds'
+interval, with a timeout of '--server.heartbeat-timeout-seconds'.`,
 
-	cmd.Flags().IntVar(&conf.Forwarder.TimeoutSeconds, "forwarder.timeout", 10, "Forwarder timeout in seconds")
+	)
+	cmd.Flags().IntVar(
+		&conf.Server.HeartbeatTimeoutSeconds,
+		"server.heartbeat-timeout-seconds",
+		10,
+		`
+Heartbeat timeout in seconds.,
+
+To verify the connection to the server is ok, the listener sends a
+heartbeat to the upstream at the '--server.heartbeat-interval-seconds'
+interval, with a timeout of '--server.heartbeat-timeout-seconds'.`,
+	)
 
-	cmd.Flags().StringVar(&conf.Log.Level, "log.level", "info", "log level")
-	cmd.Flags().StringSliceVar(&conf.Log.Subsystems, "log.subsystems", nil, "enable debug logs for logs the the given subsystems")
+	cmd.Flags().IntVar(
+		&conf.Forwarder.TimeoutSeconds,
+		"forwarder.timeout",
+		10,
+		`
+Forwarder timeout in seconds.
+
+This is the timeout between a listener receiving a request from Pico then
+forwarding it to the configured forward address, and receiving a response.
+
+If the upstream does not respond within the given timeout a
+'504 Gateway Timeout' is returned to the client.`,
+	)
+
+	cmd.Flags().StringVar(
+		&conf.Log.Level,
+		"log.level",
+		"info",
+		`
+Minimum log level to output.
+
+The available levels are 'debug', 'info', 'warn' and 'error'.`,
+	)
+	cmd.Flags().StringSliceVar(
+		&conf.Log.Subsystems,
+		"log.subsystems",
+		nil,
+		`
+Each log has a 'subsystem' field where the log occured. 
+
+'--log.subsystems' enables all log levels for those given subsystems. This
+can be useful to debug a particular subsystem without having to enable all
+debug logs.
+
+Such as you can enable 'gossip' logs with '--log.subsystems gossip'.`,
+	)
 
 	cmd.Run = func(cmd *cobra.Command, args []string) {
 		if err := conf.Validate(); err != nil {

cli/server/command.go

@@ -87,7 +87,7 @@ If the upstream does not respond within the given timeout a
 		`
 Heartbeat interval in seconds.
 
-To verify each upstream listener is still connected the server sends a
+To verify each upstream listener is still connected, the server sends a
 heartbeat to the upstream at the '--upstream.heartbeat-interval-seconds'
 interval, with a timeout of '--upstream.heartbeat-timeout-seconds'.`)
 	cmd.Flags().IntVar(
@@ -97,7 +97,7 @@ interval, with a timeout of '--upstream.heartbeat-timeout-seconds'.`)
 		`
 Heartbeat timeout in seconds.
 
-To verify each upstream listener is still connected the server sends a
+To verify each upstream listener is still connected, the server sends a
 heartbeat to the upstream at the '--upstream.heartbeat-interval-seconds'
 interval, with a timeout of '--upstream.heartbeat-timeout-seconds'.`)