diff --git a/cmd/root.go b/cmd/root.go
index adeed59a417bd81bd893b4bc114afb6b4a062e6a..6d6cbb980647eeb0c3374ca1338e12dc50fba764 100644
--- a/cmd/root.go
+++ b/cmd/root.go
@@ -91,14 +91,20 @@ func bindJsonnetFlags(cmd *cobra.Command) {
 func bindClientGoFlags(cmd *cobra.Command) {
 	kflags := clientcmd.RecommendedConfigOverrideFlags("")
 	ep := &loadingRules.ExplicitPath
-	cmd.PersistentFlags().StringVar(ep, "kubeconfig", "", "Path to a kube config. Only required if out-of-cluster")
+	cmd.PersistentFlags().StringVar(ep, "kubeconfig", "", "Path to a kubeconfig file. Alternative to env var $KUBECONFIG.")
 	clientcmd.BindOverrideFlags(&overrides, cmd.PersistentFlags(), kflags)
 }
 
 // RootCmd is the root of cobra subcommand tree
 var RootCmd = &cobra.Command{
 	Use:           "ks",
-	Short:         "Synchronise Kubernetes resources with config files",
+	Short:         `Configure your application to deploy to a Kubernetes cluster`,
+	Long: `
+You can use the ` + "`ks`" + ` commands to write, share, and deploy your Kubernetes
+application configuration to remote clusters.
+
+----
+`,
 	SilenceErrors: true,
 	SilenceUsage:  true,
 	PersistentPreRunE: func(cmd *cobra.Command, args []string) error {
diff --git a/docs/cli-reference/ks.md b/docs/cli-reference/ks.md
index 44d108cf970ba721d520935e25eea85ecfaef421..6a0c4e56b1ca8eab8aa95d0369ebb45afd3b1a93 100644
--- a/docs/cli-reference/ks.md
+++ b/docs/cli-reference/ks.md
@@ -1,11 +1,16 @@
 ## ks
 
-Synchronise Kubernetes resources with config files
+Configure your application to deploy to a Kubernetes cluster
 
 ### Synopsis
 
 
-Synchronise Kubernetes resources with config files
+
+You can use the `ks` commands to write, share, and deploy your Kubernetes
+application configuration to remote clusters.
+
+----
+
 
 ### Options
 
diff --git a/docs/cli-reference/ks_apply.md b/docs/cli-reference/ks_apply.md
index f168444c6355fc72184291f95c8d2d5954c44718..5de917c5e5a2b11df568017c03fb0d627cf3f54e 100644
--- a/docs/cli-reference/ks_apply.md
+++ b/docs/cli-reference/ks_apply.md
@@ -79,7 +79,7 @@ ks apply dev -c guestbook-ui -c nginx-depl --create false
       --gc-tag string                  A tag that's (1) added to all updated objects (2) used to garbage collect existing objects that are no longer in the manifest
       --insecure-skip-tls-verify       If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure
   -J, --jpath stringSlice              Additional jsonnet library search path
-      --kubeconfig string              Path to a kube config. Only required if out-of-cluster
+      --kubeconfig string              Path to a kubeconfig file. Alternative to env var $KUBECONFIG.
   -n, --namespace string               If present, the namespace scope for this CLI request
       --password string                Password for basic authentication to the API server
       --request-timeout string         The length of time to wait before giving up on a single server request. Non-zero values should contain a corresponding time unit (e.g. 1s, 2m, 3h). A value of zero means don't timeout requests. (default "0")
@@ -101,5 +101,5 @@ ks apply dev -c guestbook-ui -c nginx-depl --create false
 ```
 
 ### SEE ALSO
-* [ks](ks.md)	 - Synchronise Kubernetes resources with config files
+* [ks](ks.md)	 - Configure your application to deploy to a Kubernetes cluster
 
diff --git a/docs/cli-reference/ks_delete.md b/docs/cli-reference/ks_delete.md
index 117c9b26b0bb3536f04d7feae0b807ac761e30b5..e7f8d71ea0f7055682dc542c2cb3e01ae65df5f7 100644
--- a/docs/cli-reference/ks_delete.md
+++ b/docs/cli-reference/ks_delete.md
@@ -56,7 +56,7 @@ ks delete --kubeconfig=./kubeconfig -c nginx
       --grace-period int               Number of seconds given to resources to terminate gracefully. A negative value is ignored (default -1)
       --insecure-skip-tls-verify       If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure
   -J, --jpath stringSlice              Additional jsonnet library search path
-      --kubeconfig string              Path to a kube config. Only required if out-of-cluster
+      --kubeconfig string              Path to a kubeconfig file. Alternative to env var $KUBECONFIG.
   -n, --namespace string               If present, the namespace scope for this CLI request
       --password string                Password for basic authentication to the API server
       --request-timeout string         The length of time to wait before giving up on a single server request. Non-zero values should contain a corresponding time unit (e.g. 1s, 2m, 3h). A value of zero means don't timeout requests. (default "0")
@@ -77,5 +77,5 @@ ks delete --kubeconfig=./kubeconfig -c nginx
 ```
 
 ### SEE ALSO
-* [ks](ks.md)	 - Synchronise Kubernetes resources with config files
+* [ks](ks.md)	 - Configure your application to deploy to a Kubernetes cluster
 
diff --git a/docs/cli-reference/ks_diff.md b/docs/cli-reference/ks_diff.md
index c64fc0033e42b708351ac41b244ccaa1f9d6f302..e8ae98581885cd918ca07e325c515a2f5bf8cc7e 100644
--- a/docs/cli-reference/ks_diff.md
+++ b/docs/cli-reference/ks_diff.md
@@ -70,5 +70,5 @@ ks diff --kubeconfig=./kubeconfig -f ./pod.yaml
 ```
 
 ### SEE ALSO
-* [ks](ks.md)	 - Synchronise Kubernetes resources with config files
+* [ks](ks.md)	 - Configure your application to deploy to a Kubernetes cluster
 
diff --git a/docs/cli-reference/ks_env.md b/docs/cli-reference/ks_env.md
index 69b152cf9b0f7082b5508f7c3114ef1178547cb1..176763dcb48c635406131a34cbf6ba000e40d17a 100644
--- a/docs/cli-reference/ks_env.md
+++ b/docs/cli-reference/ks_env.md
@@ -56,7 +56,7 @@ ks env
       --cluster string                 The name of the kubeconfig cluster to use
       --context string                 The name of the kubeconfig context to use
       --insecure-skip-tls-verify       If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure
-      --kubeconfig string              Path to a kube config. Only required if out-of-cluster
+      --kubeconfig string              Path to a kubeconfig file. Alternative to env var $KUBECONFIG.
   -n, --namespace string               If present, the namespace scope for this CLI request
       --password string                Password for basic authentication to the API server
       --request-timeout string         The length of time to wait before giving up on a single server request. Non-zero values should contain a corresponding time unit (e.g. 1s, 2m, 3h). A value of zero means don't timeout requests. (default "0")
@@ -73,7 +73,7 @@ ks env
 ```
 
 ### SEE ALSO
-* [ks](ks.md)	 - Synchronise Kubernetes resources with config files
+* [ks](ks.md)	 - Configure your application to deploy to a Kubernetes cluster
 * [ks env add](ks_env_add.md)	 - Add a new environment to a ksonnet application
 * [ks env list](ks_env_list.md)	 - List all environments in a ksonnet application
 * [ks env rm](ks_env_rm.md)	 - Delete an environment from a ksonnet application
diff --git a/docs/cli-reference/ks_env_add.md b/docs/cli-reference/ks_env_add.md
index bc2351e4f27e8ae57b36a82c53621e93de2f746e..ca29fda9d9c0ba485a8533b8313f49c7e15c945e 100644
--- a/docs/cli-reference/ks_env_add.md
+++ b/docs/cli-reference/ks_env_add.md
@@ -76,7 +76,7 @@ ks env add prod --server=https://ksonnet-1.us-west.elb.amazonaws.com
       --cluster string                 The name of the kubeconfig cluster to use
       --context string                 The name of the kubeconfig context to use
       --insecure-skip-tls-verify       If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure
-      --kubeconfig string              Path to a kube config. Only required if out-of-cluster
+      --kubeconfig string              Path to a kubeconfig file. Alternative to env var $KUBECONFIG.
   -n, --namespace string               If present, the namespace scope for this CLI request
       --password string                Password for basic authentication to the API server
       --request-timeout string         The length of time to wait before giving up on a single server request. Non-zero values should contain a corresponding time unit (e.g. 1s, 2m, 3h). A value of zero means don't timeout requests. (default "0")
diff --git a/docs/cli-reference/ks_env_list.md b/docs/cli-reference/ks_env_list.md
index 52ac3eae62999114e48eba21b86454a132b45e9a..bd4db1cb87a8792c855cfe6b261dbc5cfa0df7e4 100644
--- a/docs/cli-reference/ks_env_list.md
+++ b/docs/cli-reference/ks_env_list.md
@@ -32,7 +32,7 @@ ks env list
       --cluster string                 The name of the kubeconfig cluster to use
       --context string                 The name of the kubeconfig context to use
       --insecure-skip-tls-verify       If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure
-      --kubeconfig string              Path to a kube config. Only required if out-of-cluster
+      --kubeconfig string              Path to a kubeconfig file. Alternative to env var $KUBECONFIG.
   -n, --namespace string               If present, the namespace scope for this CLI request
       --password string                Password for basic authentication to the API server
       --request-timeout string         The length of time to wait before giving up on a single server request. Non-zero values should contain a corresponding time unit (e.g. 1s, 2m, 3h). A value of zero means don't timeout requests. (default "0")
diff --git a/docs/cli-reference/ks_env_rm.md b/docs/cli-reference/ks_env_rm.md
index 1b28fc38f192408a065af6d322b4baee52cf89fa..734811beb07b9dc1e54d27b4bf1a48c011ce308d 100644
--- a/docs/cli-reference/ks_env_rm.md
+++ b/docs/cli-reference/ks_env_rm.md
@@ -43,7 +43,7 @@ ks env rm us-west/staging
       --cluster string                 The name of the kubeconfig cluster to use
       --context string                 The name of the kubeconfig context to use
       --insecure-skip-tls-verify       If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure
-      --kubeconfig string              Path to a kube config. Only required if out-of-cluster
+      --kubeconfig string              Path to a kubeconfig file. Alternative to env var $KUBECONFIG.
   -n, --namespace string               If present, the namespace scope for this CLI request
       --password string                Password for basic authentication to the API server
       --request-timeout string         The length of time to wait before giving up on a single server request. Non-zero values should contain a corresponding time unit (e.g. 1s, 2m, 3h). A value of zero means don't timeout requests. (default "0")
diff --git a/docs/cli-reference/ks_env_set.md b/docs/cli-reference/ks_env_set.md
index 6d36cc04b20803ef8c71c881d6c15a9292220e6e..9999cc1a67e668a8528d37a4058918a71af410d1 100644
--- a/docs/cli-reference/ks_env_set.md
+++ b/docs/cli-reference/ks_env_set.md
@@ -58,7 +58,7 @@ ks env set us-west/staging --context=staging-west
       --cluster string                 The name of the kubeconfig cluster to use
       --context string                 The name of the kubeconfig context to use
       --insecure-skip-tls-verify       If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure
-      --kubeconfig string              Path to a kube config. Only required if out-of-cluster
+      --kubeconfig string              Path to a kubeconfig file. Alternative to env var $KUBECONFIG.
   -n, --namespace string               If present, the namespace scope for this CLI request
       --password string                Password for basic authentication to the API server
       --request-timeout string         The length of time to wait before giving up on a single server request. Non-zero values should contain a corresponding time unit (e.g. 1s, 2m, 3h). A value of zero means don't timeout requests. (default "0")
diff --git a/docs/cli-reference/ks_generate.md b/docs/cli-reference/ks_generate.md
index a3ad4142e6f9f709fc9d42acad0d911e8803d78e..a34988e5a502fd907c814eb3842a404d47ae2006 100644
--- a/docs/cli-reference/ks_generate.md
+++ b/docs/cli-reference/ks_generate.md
@@ -50,5 +50,5 @@ ks generate <prototype-name> <component-name> [type] [parameter-flags]
 ```
 
 ### SEE ALSO
-* [ks](ks.md)	 - Synchronise Kubernetes resources with config files
+* [ks](ks.md)	 - Configure your application to deploy to a Kubernetes cluster
 
diff --git a/docs/cli-reference/ks_init.md b/docs/cli-reference/ks_init.md
index 3f1a2597b6f7e9404dc8fdc72ba947300c354a81..285af118637c790ef94c7dd354d12faf894c5f20 100644
--- a/docs/cli-reference/ks_init.md
+++ b/docs/cli-reference/ks_init.md
@@ -83,7 +83,7 @@ ks init app-name --dir=custom-location
       --context string                 The name of the kubeconfig context to use
       --dir string                     Ksonnet application directory
       --insecure-skip-tls-verify       If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure
-      --kubeconfig string              Path to a kube config. Only required if out-of-cluster
+      --kubeconfig string              Path to a kubeconfig file. Alternative to env var $KUBECONFIG.
   -n, --namespace string               If present, the namespace scope for this CLI request
       --password string                Password for basic authentication to the API server
       --request-timeout string         The length of time to wait before giving up on a single server request. Non-zero values should contain a corresponding time unit (e.g. 1s, 2m, 3h). A value of zero means don't timeout requests. (default "0")
@@ -100,5 +100,5 @@ ks init app-name --dir=custom-location
 ```
 
 ### SEE ALSO
-* [ks](ks.md)	 - Synchronise Kubernetes resources with config files
+* [ks](ks.md)	 - Configure your application to deploy to a Kubernetes cluster
 
diff --git a/docs/cli-reference/ks_param.md b/docs/cli-reference/ks_param.md
index 242a1108b081fd71bdda89b2e7f88983f95edaba..ed0ff6e3a3a7781ae47b4d0a7558014465268b4f 100644
--- a/docs/cli-reference/ks_param.md
+++ b/docs/cli-reference/ks_param.md
@@ -31,7 +31,7 @@ ks param
 ```
 
 ### SEE ALSO
-* [ks](ks.md)	 - Synchronise Kubernetes resources with config files
+* [ks](ks.md)	 - Configure your application to deploy to a Kubernetes cluster
 * [ks param diff](ks_param_diff.md)	 - Display differences between the component parameters of two environments
 * [ks param list](ks_param_list.md)	 - List all parameters for a component(s)
 * [ks param set](ks_param_set.md)	 - Set component or environment parameters such as replica count or name
diff --git a/docs/cli-reference/ks_pkg.md b/docs/cli-reference/ks_pkg.md
index c2831f488926baef29a229f910256c94f8384ffd..856baa059089e618209f23dbbec826bd67d3e035 100644
--- a/docs/cli-reference/ks_pkg.md
+++ b/docs/cli-reference/ks_pkg.md
@@ -18,7 +18,7 @@ ks pkg
 ```
 
 ### SEE ALSO
-* [ks](ks.md)	 - Synchronise Kubernetes resources with config files
+* [ks](ks.md)	 - Configure your application to deploy to a Kubernetes cluster
 * [ks pkg describe](ks_pkg_describe.md)	 - Describe a ksonnet package
 * [ks pkg install](ks_pkg_install.md)	 - Install a package as a dependency in the current ksonnet application
 * [ks pkg list](ks_pkg_list.md)	 - Lists information about all dependencies known to the current ksonnet app
diff --git a/docs/cli-reference/ks_prototype.md b/docs/cli-reference/ks_prototype.md
index c7f5d94130a9b2f4e671429e24c5007e289f7332..ff42110e9c320a91bdcd4b4de6b63684f6dd6300 100644
--- a/docs/cli-reference/ks_prototype.md
+++ b/docs/cli-reference/ks_prototype.md
@@ -33,7 +33,7 @@ ks prototype
 ```
 
 ### SEE ALSO
-* [ks](ks.md)	 - Synchronise Kubernetes resources with config files
+* [ks](ks.md)	 - Configure your application to deploy to a Kubernetes cluster
 * [ks prototype describe](ks_prototype_describe.md)	 - See more info about a prototype's output and usage
 * [ks prototype list](ks_prototype_list.md)	 - List all locally available ksonnet prototypes
 * [ks prototype preview](ks_prototype_preview.md)	 - Preview a prototype's output without creating a component (stdout)
diff --git a/docs/cli-reference/ks_registry.md b/docs/cli-reference/ks_registry.md
index 58a1a241a0badd4c89709adc0335bcf9dd2ef7cd..e62448aa99ddf36026880cbfd6aaf5562ca869ae 100644
--- a/docs/cli-reference/ks_registry.md
+++ b/docs/cli-reference/ks_registry.md
@@ -30,7 +30,7 @@ ks registry
 ```
 
 ### SEE ALSO
-* [ks](ks.md)	 - Synchronise Kubernetes resources with config files
+* [ks](ks.md)	 - Configure your application to deploy to a Kubernetes cluster
 * [ks registry describe](ks_registry_describe.md)	 - Describe a ksonnet registry
 * [ks registry list](ks_registry_list.md)	 - List all registries known to the current ksonnet app.
 
diff --git a/docs/cli-reference/ks_show.md b/docs/cli-reference/ks_show.md
index 2dface307fb44173e2ee123f5ffdc1c476a00874..0c3c01fc7496d52218aff9aa4e41b35878e3d67f 100644
--- a/docs/cli-reference/ks_show.md
+++ b/docs/cli-reference/ks_show.md
@@ -67,5 +67,5 @@ ks show dev -c redis -c nginx-server
 ```
 
 ### SEE ALSO
-* [ks](ks.md)	 - Synchronise Kubernetes resources with config files
+* [ks](ks.md)	 - Configure your application to deploy to a Kubernetes cluster
 
diff --git a/docs/cli-reference/ks_validate.md b/docs/cli-reference/ks_validate.md
index bdc9cf63a02917b89c4b2906859a1b503ff4080e..2d67e05f94fbce3165f7357e1463c2d0ae58d8f3 100644
--- a/docs/cli-reference/ks_validate.md
+++ b/docs/cli-reference/ks_validate.md
@@ -49,7 +49,7 @@ ksonnet validate -f ./pod.jsonnet
       --ext-str-file stringSlice       Read external variable from a file
       --insecure-skip-tls-verify       If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure
   -J, --jpath stringSlice              Additional jsonnet library search path
-      --kubeconfig string              Path to a kube config. Only required if out-of-cluster
+      --kubeconfig string              Path to a kubeconfig file. Alternative to env var $KUBECONFIG.
   -n, --namespace string               If present, the namespace scope for this CLI request
       --password string                Password for basic authentication to the API server
       --request-timeout string         The length of time to wait before giving up on a single server request. Non-zero values should contain a corresponding time unit (e.g. 1s, 2m, 3h). A value of zero means don't timeout requests. (default "0")
@@ -70,5 +70,5 @@ ksonnet validate -f ./pod.jsonnet
 ```
 
 ### SEE ALSO
-* [ks](ks.md)	 - Synchronise Kubernetes resources with config files
+* [ks](ks.md)	 - Configure your application to deploy to a Kubernetes cluster
 
diff --git a/docs/cli-reference/ks_version.md b/docs/cli-reference/ks_version.md
index c7dbb600dbed9df5a81891d5a942173addc3552d..aeff6ab4735b4c08a13362f17e58ff72471cc3ec 100644
--- a/docs/cli-reference/ks_version.md
+++ b/docs/cli-reference/ks_version.md
@@ -18,5 +18,5 @@ ks version
 ```
 
 ### SEE ALSO
-* [ks](ks.md)	 - Synchronise Kubernetes resources with config files
+* [ks](ks.md)	 - Configure your application to deploy to a Kubernetes cluster