help: update readme and provide command documentation (#18)

* help: update readme and provide command documentation

* fix newlines

* edit and expand

Co-authored-by: alexfornuto <alex@fornuto.com>

README.md

@@ -1,5 +1,30 @@
 # Pomerium Command Line Client
 
-Pomerium is capable of creating secure connections to services like SSH, Redis, and more by creating a TCP tunnel to the service with a local client.
+The Pomerium Command Line Client (CLI) is a client-side helper application for [Pomerium](https://pomerium.com). It's used to generate encrypted and authenticated connections for services that are not accessed through a web browser.
 
-See https://pomerium.com/docs/tcp/client.html for details.
+## Installation
+
+Installation instructions are available in the [Pomerium Docs](https://www.pomerium.com/docs/releases.html#pomerium-cli).
+
+## Usage
+
+The two CLI operations are:
+
+1. Establishing [TCP tunnels](https://www.pomerium.com/docs/tcp/client.html) through Pomerium.
+2. Generating `kubectl` credentials for [Kubernetes](https://www.pomerium.com/docs/k8s/).
+
+```text
+Usage:
+  pomerium-cli [command]
+
+Available Commands:
+  completion  generate the autocompletion script for the specified shell
+  help        Help about any command
+  k8s         commands for the kubernetes credential plugin
+  tcp         creates a TCP tunnel through Pomerium
+  version     version
+
+Flags:
+  -h, --help      help for pomerium-cli
+  -v, --version   version for pomerium-cli
+```

cmd/pomerium-cli/kubernetes.go

@@ -24,11 +24,13 @@ func init() {
 }
 
 var kubernetesCmd = &cobra.Command{
-	Use: "k8s",
+	Use:   "k8s",
+	Short: "commands for the kubernetes credential plugin",
 }
 
 var kubernetesFlushCredentialsCmd = &cobra.Command{
-	Use: "flush-credentials [API Server URL]",
+	Use:   "flush-credentials [API Server URL]",
+	Short: "clear the kubernetes credentials for the given URL to force a new login",
 	RunE: func(cmd *cobra.Command, args []string) error {
 		if len(args) == 0 {
 			return clearAllCachedCredentials()
@@ -39,7 +41,8 @@ var kubernetesFlushCredentialsCmd = &cobra.Command{
 }
 
 var kubernetesExecCredentialCmd = &cobra.Command{
-	Use: "exec-credential",
+	Use:   "exec-credential",
+	Short: "run the kubernetes credential plugin for use with kubectl",
 	RunE: func(cmd *cobra.Command, args []string) error {
 		if len(args) < 1 {
 			return fmt.Errorf("server url is required")

cmd/pomerium-cli/tcp.go

@@ -34,8 +34,9 @@ func init() {
 }
 
 var tcpCmd = &cobra.Command{
-	Use:  "tcp destination",
-	Args: cobra.ExactArgs(1),
+	Use:   "tcp destination",
+	Short: "creates a TCP tunnel through Pomerium",
+	Args:  cobra.ExactArgs(1),
 	RunE: func(cmd *cobra.Command, args []string) error {
 		dstHost := args[0]
 		dstHostname, _, err := net.SplitHostPort(dstHost)