Merge pull request #23 from abiogenesis-now/jyao/autogenerated-cli-docs

[docs] Add autogenerated CLI reference

.gitignore

@@ -8,6 +8,7 @@
 # Folders
 _obj
 _test
+_output
 
 # Architecture specific extensions/prefixes
 *.[568vq]

.travis.yml

@@ -24,9 +24,6 @@ matrix:
     - env: TARGET=x86_64-linux-musl EXTRA_GO_FLAGS_TEST=""
       go: 1.8.x
     - env: DO_INTEGRATION_TEST=1 INT_KVERS=v1.7.0
-    # cgo requires golang >= 1.8.1 (or other workarounds) on recent
-    # osx/xcode - see https://github.com/golang/go/issues/19734
-    # 'go test' also hangs repeatably on go-1.8.3/MacOS ?
     - os: osx
       go: 1.8.x
   fast_finish: true
@@ -56,6 +53,7 @@ addons:
       - libgmp-dev
       - libmpfr-dev
       - libmpc-dev
+      - realpath
 
 before_install:
   - set -e

Makefile

@@ -24,6 +24,8 @@ GINKGO = ginkgo
 
 KCFG_TEST_FILE = lib/kubecfg_test.jsonnet
 GUESTBOOK_FILE = examples/guestbook.jsonnet
+DOC_GEN_FILE = ./docs/generate/update-generated-docs.sh
+DOC_TEST_FILE = ./docs/generate/verify-generated-docs.sh
 JSONNET_FILES = $(KCFG_TEST_FILE) $(GUESTBOOK_FILE)
 # TODO: Simplify this once ./... ignores ./vendor
 GO_PACKAGES = ./cmd/... ./utils/... ./pkg/... ./metadata/... ./prototype/...
@@ -31,12 +33,15 @@ GO_PACKAGES = ./cmd/... ./utils/... ./pkg/... ./metadata/... ./prototype/...
 # Default cluster from this config is used for integration tests
 KUBECONFIG = $(HOME)/.kube/config
 
-all: ks
+all: ks docs
 
 ks:
 	$(GO) build -o ks $(GO_FLAGS) .
 
-test: gotest jsonnettest
+docs:
+	$(DOC_GEN_FILE)
+
+test: gotest jsonnettest docstest
 
 gotest:
 	$(GO) test $(GO_FLAGS) $(GO_PACKAGES)
@@ -45,6 +50,9 @@ jsonnettest: ks $(JSONNET_FILES)
 #	TODO: use `ks check` once implemented
 	./ks -J lib show -f $(KCFG_TEST_FILE) -f $(GUESTBOOK_FILE) >/dev/null
 
+docstest:
+	$(DOC_TEST_FILE)
+
 integrationtest: ks
 	$(GINKGO) -tags 'integration' integration -- -kubeconfig $(KUBECONFIG) -kubecfg-bin $(abspath $<)
 
@@ -55,7 +63,7 @@ fmt:
 	$(GOFMT) -s -w $(shell $(GO) list -f '{{.Dir}}' $(GO_PACKAGES))
 
 clean:
-	$(RM) ./ks
+	$(RM) ./ks ./docs/cli-reference/ks*.md
 
-.PHONY: all test clean vet fmt
+.PHONY: all test clean vet fmt docs
 .PHONY: ks

docs/cli-reference/README.md

+# Command line reference
+
+Ksonnet provides a CLI (invoked with `ks`) that allows you to generate Kubernetes resource manifests locally (in `jsonnet`, `JSON`, or `YAML` format) and synchronize them with your remote cluster(s).
+
+*The files in this directory enumerate each of the possible `ks` commands and their flags. Note that you can also find this info with the CLI itself, using the `--help` flag.*

docs/cli-reference/ks.md

+## ks
+
+Synchronise Kubernetes resources with config files
+
+### Synopsis
+
+
+Synchronise Kubernetes resources with config files
+
+### Options
+
+```
+  -v, --verbose count[=-1]   Increase verbosity. May be given multiple times.
+```
+
+### SEE ALSO
+* [ks apply](ks_apply.md)	 - Apply local configuration to remote cluster
+* [ks delete](ks_delete.md)	 - Delete Kubernetes resources described in local config
+* [ks diff](ks_diff.md)	 - Display differences between server and local config, or server and server config
+* [ks env](ks_env.md)	 - Manage ksonnet environments
+* [ks generate](ks_generate.md)	 - Expand prototype, place in components/ directory of ksonnet app
+* [ks init](ks_init.md)	 - Initialize a ksonnet project
+* [ks param](ks_param.md)	 - Manage ksonnet component parameters
+* [ks pkg](ks_pkg.md)	 - Manage packages and dependencies for the current ksonnet project
+* [ks prototype](ks_prototype.md)	 - Instantiate, inspect, and get examples for ksonnet prototypes
+* [ks registry](ks_registry.md)	 - Manage registries for current project
+* [ks show](ks_show.md)	 - Show expanded resource definitions
+* [ks validate](ks_validate.md)	 - Compare generated manifest against server OpenAPI spec
+* [ks version](ks_version.md)	 - Print version information
+

docs/cli-reference/ks_apply.md

+## ks apply
+
+Apply local configuration to remote cluster
+
+### Synopsis
+
+
+Update (or optionally create) Kubernetes resources on the cluster using the
+local configuration. Use the '--create' flag to control whether we create them
+if they do not exist (default: true).
+
+ksonnet applications are accepted, as well as normal JSON, YAML, and Jsonnet
+files.
+
+```
+ks apply [env-name] [-f <file-or-dir>]
+```
+
+### Examples
+
+```
+  # Create or update all resources described in a ksonnet application, and
+  # running in the 'dev' environment. Can be used in any subdirectory of the
+  # application.
+  ks apply dev
+
+  # Create or update resources described in a YAML file. Automatically picks up
+  # the cluster's location from '$KUBECONFIG'.
+  ks appy -f ./pod.yaml
+
+  # Create or update resources described in the JSON file. Changes are deployed
+  # to the cluster pointed at the 'dev' environment.
+  ks apply dev -f ./pod.json
+
+  # Update resources described in a YAML file, and running in cluster referred
+  # to by './kubeconfig'.
+  ks apply --kubeconfig=./kubeconfig -f ./pod.yaml
+
+  # Display set of actions we will execute when we run 'apply'.
+  ks apply dev --dry-run
+```
+
+### Options
+
+```
+      --as string                      Username to impersonate for the operation
+      --certificate-authority string   Path to a cert. file for the certificate authority
+      --client-certificate string      Path to a client certificate file for TLS
+      --client-key string              Path to a client key file for TLS
+      --cluster string                 The name of the kubeconfig cluster to use
+      --context string                 The name of the kubeconfig context to use
+      --create                         Create missing resources (default true)
+      --dry-run                        Perform only read-only operations
+  -V, --ext-str stringSlice            Values of external variables
+      --ext-str-file stringSlice       Read external variable from a file
+  -f, --file stringArray               Filename or directory that contains the configuration to apply (accepts YAML, JSON, and Jsonnet)
+      --gc-tag string                  Add this tag to updated objects, and garbage collect existing objects with this tag and not in config
+      --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
+  -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")
+      --resolve-images string          Change implementation of resolveImage native function. One of: noop, registry (default "noop")
+      --resolve-images-error string    Action when resolveImage fails. One of ignore,warn,error (default "warn")
+      --server string                  The address and port of the Kubernetes API server
+      --skip-gc                        Don't perform garbage collection, even with --gc-tag
+  -A, --tla-str stringSlice            Values of top level arguments
+      --tla-str-file stringSlice       Read top level argument from a file
+      --token string                   Bearer token for authentication to the API server
+      --user string                    The name of the kubeconfig user to use
+      --username string                Username for basic authentication to the API server
+```
+
+### Options inherited from parent commands
+
+```
+  -v, --verbose count[=-1]   Increase verbosity. May be given multiple times.
+```
+
+### SEE ALSO
+* [ks](ks.md)	 - Synchronise Kubernetes resources with config files
+

docs/cli-reference/ks_delete.md

+## ks delete
+
+Delete Kubernetes resources described in local config
+
+### Synopsis
+
+
+Delete Kubernetes resources from a cluster, as described in the local
+configuration.
+
+ksonnet applications are accepted, as well as normal JSON, YAML, and Jsonnet
+files.
+
+```
+ks delete [env-name] [-f <file-or-dir>]
+```
+
+### Examples
+
+```
+  # Delete all resources described in a ksonnet application, from the 'dev'
+  # environment. Can be used in any subdirectory of the application.
+  ks delete dev
+
+  # Delete resources described in a YAML file. Automatically picks up the
+  # cluster's location from '$KUBECONFIG'.
+  ks delete -f ./pod.yaml
+
+  # Delete resources described in the JSON file from the 'dev' environment. Can
+  # be used in any subdirectory of the application.
+  ks delete dev -f ./pod.json
+
+  # Delete resources described in a YAML file, and running in the cluster
+  # specified by the current context in specified kubeconfig file.
+  ks delete --kubeconfig=./kubeconfig -f ./pod.yaml
+```
+
+### Options
+
+```
+      --as string                      Username to impersonate for the operation
+      --certificate-authority string   Path to a cert. file for the certificate authority
+      --client-certificate string      Path to a client certificate file for TLS
+      --client-key string              Path to a client key file for TLS
+      --cluster string                 The name of the kubeconfig cluster to use
+      --context string                 The name of the kubeconfig context to use
+  -V, --ext-str stringSlice            Values of external variables
+      --ext-str-file stringSlice       Read external variable from a file
+  -f, --file stringArray               Filename or directory that contains the configuration to apply (accepts YAML, JSON, and Jsonnet)
+      --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
+  -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")
+      --resolve-images string          Change implementation of resolveImage native function. One of: noop, registry (default "noop")
+      --resolve-images-error string    Action when resolveImage fails. One of ignore,warn,error (default "warn")
+      --server string                  The address and port of the Kubernetes API server
+  -A, --tla-str stringSlice            Values of top level arguments
+      --tla-str-file stringSlice       Read top level argument from a file
+      --token string                   Bearer token for authentication to the API server
+      --user string                    The name of the kubeconfig user to use
+      --username string                Username for basic authentication to the API server
+```
+
+### Options inherited from parent commands
+
+```
+  -v, --verbose count[=-1]   Increase verbosity. May be given multiple times.
+```
+
+### SEE ALSO
+* [ks](ks.md)	 - Synchronise Kubernetes resources with config files
+

docs/cli-reference/ks_diff.md

+## ks diff
+
+Display differences between server and local config, or server and server config
+
+### Synopsis
+
+
+Display differences between server and local configuration, or server and server
+configurations.
+
+ksonnet applications are accepted, as well as normal JSON, YAML, and Jsonnet
+files.
+
+```
+ks diff [<env1> [<env2>]] [-f <file-or-dir>]
+```
+
+### Examples
+
+```
+  # Show diff between resources described in a the local 'dev' environment
+  # specified by the ksonnet application and the remote cluster referenced by
+  # the same 'dev' environment. Can be used in any subdirectory of the application.
+  ksonnet diff dev
+
+  # Show diff between resources at remote clusters. This requires ksonnet
+  # application defined environments. Diff between the cluster defined at the
+  # 'us-west/dev' environment, and the cluster defined at the 'us-west/prod'
+  # environment. Can be used in any subdirectory of the application.
+  ksonnet diff remote:us-west/dev remote:us-west/prod
+
+  # Show diff between resources at a remote and a local cluster. This requires
+  # ksonnet application defined environments. Diff between the cluster defined
+  # at the 'us-west/dev' environment, and the cluster defined at the
+  # 'us-west/prod' environment. Can be used in any subdirectory of the
+  # application.
+  ksonnet diff local:us-west/dev remote:us-west/prod
+
+  # Show diff between resources described in a YAML file and the cluster
+  # referenced in '$KUBECONFIG'.
+  ks diff -f ./pod.yaml
+
+  # Show diff between resources described in a JSON file and the cluster
+  # referenced by the environment 'dev'.
+  ks diff dev -f ./pod.json
+
+  # Show diff between resources described in a YAML file and the cluster
+  # referred to by './kubeconfig'.
+  ks diff --kubeconfig=./kubeconfig -f ./pod.yaml
+```
+
+### Options
+
+```
+      --diff-strategy string          Diff strategy, all or subset. (default "all")
+  -V, --ext-str stringSlice           Values of external variables
+      --ext-str-file stringSlice      Read external variable from a file
+  -f, --file stringArray              Filename or directory that contains the configuration to apply (accepts YAML, JSON, and Jsonnet)
+  -J, --jpath stringSlice             Additional jsonnet library search path
+      --resolve-images string         Change implementation of resolveImage native function. One of: noop, registry (default "noop")
+      --resolve-images-error string   Action when resolveImage fails. One of ignore,warn,error (default "warn")
+  -A, --tla-str stringSlice           Values of top level arguments
+      --tla-str-file stringSlice      Read top level argument from a file
+```
+
+### Options inherited from parent commands
+
+```
+  -v, --verbose count[=-1]   Increase verbosity. May be given multiple times.
+```
+
+### SEE ALSO
+* [ks](ks.md)	 - Synchronise Kubernetes resources with config files
+

docs/cli-reference/ks_env.md

+## ks env
+
+Manage ksonnet environments
+
+### Synopsis
+
+
+An environment acts as a sort of "named cluster", allowing for commands like
+'ks apply dev', which applies the ksonnet application to the "dev cluster".
+Additionally, environments allow users to cache data about the cluster it points
+to, including data needed to run 'verify', and a version of ksonnet-lib that is
+generated based on the flags the API server was started with (e.g., RBAC enabled
+or not).
+
+An environment contains no user-specific data (such as the private key
+often contained in a kubeconfig file), and
+
+Environments are represented as a hierarchy in the 'environments' directory of a
+ksonnet application. For example, in the example below, there are two
+environments: 'default' and 'us-west/staging'. Each contains a cached version of
+ksonnet-lib, and a 'spec.json' that contains the server and server cert that
+uniquely identifies the cluster.
+
+environments/
+  default/           [Default generated environment]
+    .metadata/
+      k.libsonnet
+      k8s.libsonnet
+      swagger.json
+    spec.json
+    default.jsonnet
+  us-west/
+    staging/         [Example of user-generated env]
+      .metadata/
+        k.libsonnet
+        k8s.libsonnet
+        swagger.json
+      spec.json      [This will contain the API server address of the environment and other environment metadata]
+      staging.jsonnet
+
+```
+ks env
+```
+
+### Options
+
+```
+      --as string                      Username to impersonate for the operation
+      --certificate-authority string   Path to a cert. file for the certificate authority
+      --client-certificate string      Path to a client certificate file for TLS
+      --client-key string              Path to a client key file for TLS
+      --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
+  -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")
+      --server string                  The address and port of the Kubernetes API server
+      --token string                   Bearer token for authentication to the API server
+      --user string                    The name of the kubeconfig user to use
+      --username string                Username for basic authentication to the API server
+```
+
+### Options inherited from parent commands
+
+```
+  -v, --verbose count[=-1]   Increase verbosity. May be given multiple times.
+```
+
+### SEE ALSO
+* [ks](ks.md)	 - Synchronise Kubernetes resources with config files
+* [ks env add](ks_env_add.md)	 - Add a new environment to a ksonnet project
+* [ks env list](ks_env_list.md)	 - List all environments in a ksonnet project
+* [ks env rm](ks_env_rm.md)	 - Delete an environment from a ksonnet project
+* [ks env set](ks_env_set.md)	 - Set environment fields such as the name, server, and namespace.
+

docs/cli-reference/ks_env_add.md

+## ks env add
+
+Add a new environment to a ksonnet project
+
+### Synopsis
+
+
+Add a new environment to a ksonnet project. Names are restricted to not
+include punctuation, so names like '../foo' are not allowed.
+
+An environment acts as a sort of "named cluster", allowing for commands like
+'ks apply dev', which applies the ksonnet application to the "dev cluster".
+For more information on what an environment is and how they work, run 'help
+env'.
+
+Environments are represented as a hierarchy in the 'environments' directory of a
+ksonnet application, and hence 'env add' will add to this directory structure.
+For example, in the example below, there are two environments: 'default' and
+'us-west/staging'. 'env add' will add a similar directory to this environment.
+
+environments/
+  default/           [Default generated environment]
+    .metadata/
+      k.libsonnet
+      k8s.libsonnet
+      swagger.json
+    spec.json
+    default.jsonnet
+  us-west/
+    staging/         [Example of user-generated env]
+      .metadata/
+        k.libsonnet
+        k8s.libsonnet
+        swagger.json
+      spec.json      [This will contain the API server address of the environment and other environment metadata],
+      staging.jsonnet
+
+```
+ks env add <env-name>
+```
+
+### Examples
+
+```
+  # Initialize a new staging environment at 'us-west'.
+	# The environment will be setup using the current context in your kubecfg file. The directory
+	# structure rooted at 'us-west' in the documentation above will be generated.
+  ks env add us-west/staging
+
+  # Initialize a new staging environment at 'us-west' with the namespace 'staging', using
+  # the OpenAPI specification generated in the Kubernetes v1.7.1 build to generate 'ksonnet-lib'.
+  ks env add us-west/staging --api-spec=version:v1.7.1 --namespace=staging
+
+  # Initialize a new environment using the 'dev' context in your kubeconfig file.
+  ks env add my-env --context=dev
+
+  # Initialize a new environment using a server address.
+  ks env add my-env --server=https://ksonnet-1.us-west.elb.amazonaws.com
+```
+
+### Options
+
+```
+      --api-spec string   Manually specify API version from OpenAPI schema, cluster, or Kubernetes version (default "version:v1.7.0")
+```
+
+### Options inherited from parent commands
+
+```
+      --as string                      Username to impersonate for the operation
+      --certificate-authority string   Path to a cert. file for the certificate authority
+      --client-certificate string      Path to a client certificate file for TLS
+      --client-key string              Path to a client key file for TLS
+      --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
+  -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")
+      --server string                  The address and port of the Kubernetes API server
+      --token string                   Bearer token for authentication to the API server
+      --user string                    The name of the kubeconfig user to use
+      --username string                Username for basic authentication to the API server
+  -v, --verbose count[=-1]             Increase verbosity. May be given multiple times.
+```
+
+### SEE ALSO
+* [ks env](ks_env.md)	 - Manage ksonnet environments
+

docs/cli-reference/ks_env_list.md

+## ks env list
+
+List all environments in a ksonnet project
+
+### Synopsis
+
+
+List all environments in a ksonnet project. This will
+display the name, server, and namespace of each environment within the ksonnet project.
+
+```
+ks env list
+```
+
+### Options inherited from parent commands
+
+```
+      --as string                      Username to impersonate for the operation
+      --certificate-authority string   Path to a cert. file for the certificate authority
+      --client-certificate string      Path to a client certificate file for TLS
+      --client-key string              Path to a client key file for TLS
+      --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
+  -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")
+      --server string                  The address and port of the Kubernetes API server
+      --token string                   Bearer token for authentication to the API server
+      --user string                    The name of the kubeconfig user to use
+      --username string                Username for basic authentication to the API server
+  -v, --verbose count[=-1]             Increase verbosity. May be given multiple times.
+```
+
+### SEE ALSO
+* [ks env](ks_env.md)	 - Manage ksonnet environments
+

docs/cli-reference/ks_env_rm.md

+## ks env rm
+
+Delete an environment from a ksonnet project
+
+### Synopsis
+
+
+Delete an environment from a ksonnet project. This is the same
+as removing the <env-name> environment directory and all files contained. If the
+project exists in a hierarchy (e.g., 'us-east/staging') and deleting the
+environment results in an empty environments directory (e.g., if deleting
+'us-east/staging' resulted in an empty 'us-east/' directory), then all empty
+parent directories are subsequently deleted.
+
+```
+ks env rm <env-name>
+```
+
+### Examples
+
+```
+  # Remove the directory 'us-west/staging' and all contents
+  #	in the 'environments' directory. This will also remove the parent directory
+  # 'us-west' if it is empty.
+  ks env rm us-west/staging
+```
+
+### Options inherited from parent commands
+
+```
+      --as string                      Username to impersonate for the operation
+      --certificate-authority string   Path to a cert. file for the certificate authority
+      --client-certificate string      Path to a client certificate file for TLS
+      --client-key string              Path to a client key file for TLS
+      --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
+  -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")
+      --server string                  The address and port of the Kubernetes API server
+      --token string                   Bearer token for authentication to the API server
+      --user string                    The name of the kubeconfig user to use
+      --username string                Username for basic authentication to the API server
+  -v, --verbose count[=-1]             Increase verbosity. May be given multiple times.
+```
+
+### SEE ALSO
+* [ks env](ks_env.md)	 - Manage ksonnet environments
+

docs/cli-reference/ks_env_set.md

+## ks env set
+
+Set environment fields such as the name, server, and namespace.
+
+### Synopsis
+
+
+Set environment fields such as the name, and server. Changing
+the name of an environment will also update the directory structure in
+'environments'.
+
+```
+ks env set <env-name>
+```
+
+### Examples
+
+```
+  # Updates the API server address of the environment 'us-west/staging'.
+  ks env set us-west/staging --server=http://example.com
+
+  # Updates the namespace of the environment 'us-west/staging'.
+  ks env set us-west/staging --namespace=staging
+
+  # Updates both the name and the server of the environment 'us-west/staging'.
+  # Updating the name will update the directory structure in 'environments'.
+  ks env set us-west/staging --server=http://example.com --name=us-east/staging
+  
+  # Updates API server address of the environment 'us-west/staging' based on the
+  # server in the context 'staging-west' in your kubeconfig file.
+  ks env set us-west/staging --context=staging-west
+```
+
+### Options
+
+```
+      --name string   Specify name to rename environment to. Name must not already exist
+```
+
+### Options inherited from parent commands
+
+```
+      --as string                      Username to impersonate for the operation
+      --certificate-authority string   Path to a cert. file for the certificate authority
+      --client-certificate string      Path to a client certificate file for TLS
+      --client-key string              Path to a client key file for TLS
+      --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
+  -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")
+      --server string                  The address and port of the Kubernetes API server
+      --token string                   Bearer token for authentication to the API server
+      --user string                    The name of the kubeconfig user to use
+      --username string                Username for basic authentication to the API server
+  -v, --verbose count[=-1]             Increase verbosity. May be given multiple times.
+```
+
+### SEE ALSO
+* [ks env](ks_env.md)	 - Manage ksonnet environments
+

docs/cli-reference/ks_generate.md

+## ks generate
+
+Expand prototype, place in components/ directory of ksonnet app
+
+### Synopsis
+
+
+Expand prototype uniquely identified by (possibly partial) 'prototype-name',
+filling in parameters from flags, and placing it into the file
+'components/componentName', with the appropriate extension set. For example, the
+following command will expand template 'io.ksonnet.pkg.single-port-deployment'
+and place it in the file 'components/nginx-depl.jsonnet' (since by default
+ksonnet will expand templates as Jsonnet).
+
+  ks prototype use io.ksonnet.pkg.single-port-deployment nginx-depl \
+    --name=nginx                                                         \
+    --image=nginx
+
+Note that if we were to specify to expand the template as JSON or YAML, we would
+generate a file with a '.json' or '.yaml' extension, respectively. See examples
+below for an example of how to do this.
+
+Note also that 'prototype-name' need only contain enough of the suffix of a name
+to uniquely disambiguate it among known names. For example, 'deployment' may
+resolve ambiguously, in which case 'use' will fail, while 'deployment' might be
+unique enough to resolve to 'io.ksonnet.pkg.single-port-deployment'.
+
+```
+ks generate <prototype-name> <component-name> [type] [parameter-flags]
+```
+
+### Options inherited from parent commands
+
+```
+  -v, --verbose count[=-1]   Increase verbosity. May be given multiple times.
+```
+
+### SEE ALSO
+* [ks](ks.md)	 - Synchronise Kubernetes resources with config files
+

docs/cli-reference/ks_init.md

+## ks init
+
+Initialize a ksonnet project
+
+### Synopsis
+
+
+Initialize a ksonnet project in a new directory, 'app-name'. This process
+consists of two steps:
+
+1. Generating ksonnet-lib. Users can set flags to generate the library based on
+   a variety of data, including server configuration and an OpenAPI
+   specification of a Kubernetes build. By default, this is generated from the
+   capabilities of the cluster specified in the cluster of the current context
+   specified in $KUBECONFIG.
+2. Generating the following tree in the current directory.
+
+   app-name/
+     .gitignore     Default .gitignore; can customize VCS
+     .ksonnet/      Metadata for ksonnet
+     envs/
+       default/     Default generated environment]
+         k.libsonnet
+         k8s.libsonnet
+         swagger.json
+         spec.json
+     components/    Top-level Kubernetes objects defining application
+     lib/           user-written .libsonnet files
+     vendor/        mixin libraries, prototypes
+
+
+```
+ks init <app-name>
+```
+
+### Examples
+
+```
+  # Initialize ksonnet application, using the capabilities of live cluster
+  # specified in the $KUBECONFIG environment variable (specifically: the
+  # current context) to generate 'ksonnet-lib'.
+  ks init app-name
+
+  # Initialize ksonnet application, using the OpenAPI specification generated
+  # in the Kubenetes v1.7.1 build to generate 'ksonnet-lib'.
+  ks init app-name --api-spec=version:v1.7.1
+
+  # Initialize ksonnet application, using an OpenAPI specification file
+  # generated by a build of Kubernetes to generate 'ksonnet-lib'.
+  ks init app-name --api-spec=file:swagger.json
+
+  # Initialize ksonnet application, using the context 'dev' from the kubeconfig
+  # file.
+  ks init app-name --context=dev
+```
+
+### Options
+
+```
+      --api-spec string                Manually specify API version from OpenAPI schema, cluster, or Kubernetes version (default "version:v1.7.0")
+      --as string                      Username to impersonate for the operation
+      --certificate-authority string   Path to a cert. file for the certificate authority
+      --client-certificate string      Path to a client certificate file for TLS
+      --client-key string              Path to a client key file for TLS
+      --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
+  -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")
+      --server string                  The address and port of the Kubernetes API server
+      --token string                   Bearer token for authentication to the API server
+      --user string                    The name of the kubeconfig user to use
+      --username string                Username for basic authentication to the API server
+```
+
+### Options inherited from parent commands
+
+```
+  -v, --verbose count[=-1]   Increase verbosity. May be given multiple times.
+```
+
+### SEE ALSO
+* [ks](ks.md)	 - Synchronise Kubernetes resources with config files
+

docs/cli-reference/ks_param.md

+## ks param
+
+Manage ksonnet component parameters
+
+### Synopsis
+
+
+Parameters are the customizable fields defining ksonnet components. For
+example, replica count, component name, or deployment image.
+
+Parameters are also able to be defined separately across environments. Meaning,
+this supports features to allow a "development" environment to only run a
+single replication instance for it's components, whereas allowing a "production"
+environment to run more replication instances to meet heavier production load
+demands.
+
+Environments are ksonnet "named clusters". For more information on environments,
+run:
+  ks env --help
+
+
+```
+ks param
+```
+
+### Options inherited from parent commands
+
+```
+  -v, --verbose count[=-1]   Increase verbosity. May be given multiple times.
+```
+
+### SEE ALSO
+* [ks](ks.md)	 - Synchronise Kubernetes resources with config files
+* [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
+

docs/cli-reference/ks_param_diff.md

+## ks param diff
+
+Display differences between the component parameters of two environments
+
+### Synopsis
+
+
+"Pretty prints differences between the component parameters of two environments.
+
+A component flag is accepted to diff against a single component. By default, the
+diff is performed against all components.
+
+
+```
+ks param diff <env1> <env2>
+```
+
+### Examples
+
+```
+  # Diff between the component parameters on environments 'dev' and 'prod'
+  ks param diff dev prod
+
+  # Diff between the component 'guestbook' on environments 'dev' and 'prod'
+  ks param diff dev prod --component=guestbook
+```
+
+### Options
+
+```
+      --component string   Specify the component to diff against
+```
+
+### Options inherited from parent commands
+
+```
+  -v, --verbose count[=-1]   Increase verbosity. May be given multiple times.
+```
+
+### SEE ALSO
+* [ks param](ks_param.md)	 - Manage ksonnet component parameters
+

docs/cli-reference/ks_param_list.md

+## ks param list
+
+List all parameters for a component(s)
+
+### Synopsis
+
+
+"List all component parameters or environment parameters.
+
+This command will display all parameters for the component specified. If a
+component is not specified, parameters for all components will be listed.
+
+Furthermore, parameters can be listed on a per-environment basis.
+
+
+```
+ks param list <component-name>
+```
+
+### Examples
+
+```
+  # List all component parameters
+  ks param list
+
+  # List all parameters for the component "guestbook"
+  ks param list guestbook
+
+  # List all parameters for the environment "dev"
+  ks param list --env=dev
+
+  # List all parameters for the component "guestbook" in the environment "dev"
+  ks param list guestbook --env=dev
+```
+
+### Options
+
+```
+      --env string   Specify environment to list parameters for
+```
+
+### Options inherited from parent commands
+
+```
+  -v, --verbose count[=-1]   Increase verbosity. May be given multiple times.
+```
+
+### SEE ALSO
+* [ks param](ks_param.md)	 - Manage ksonnet component parameters
+

docs/cli-reference/ks_param_set.md

+## ks param set
+
+Set component or environment parameters such as replica count or name
+
+### Synopsis
+
+
+"Set component or environment parameters such as replica count or name.
+
+Parameters are set individually, one at a time. If you require customization of
+more fields, we suggest that you modify your ksonnet project's
+'components/params.libsonnet' file directly. Likewise, for greater customization
+of environment parameters, we suggest modifying the
+'environments/:name/params.libsonnet' file.
+
+
+```
+ks param set <component-name> <param-key> <param-value>
+```
+
+### Examples
+
+```
+  # Updates the replica count of the 'guestbook' component to 4.
+  ks param set guestbook replicas 4
+
+  # Updates the replica count of the 'guestbook' component to 2 for the environment
+  # 'dev'
+  ks param set guestbook replicas 2 --env=dev
+```
+
+### Options
+
+```
+      --env string   Specify environment to set parameters for
+```
+
+### Options inherited from parent commands
+
+```
+  -v, --verbose count[=-1]   Increase verbosity. May be given multiple times.
+```
+
+### SEE ALSO
+* [ks param](ks_param.md)	 - Manage ksonnet component parameters
+

docs/cli-reference/ks_pkg.md

+## ks pkg
+
+Manage packages and dependencies for the current ksonnet project
+
+### Synopsis
+
+
+Manage packages and dependencies for the current ksonnet project
+
+```
+ks pkg
+```
+
+### Options inherited from parent commands
+
+```
+  -v, --verbose count[=-1]   Increase verbosity. May be given multiple times.
+```
+
+### SEE ALSO
+* [ks](ks.md)	 - Synchronise Kubernetes resources with config files
+* [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
+