diff --git a/cmd/prototype.go b/cmd/prototype.go
index eb629ba9de0ce07a69f8f258ebc785effb579bc4..9ab227ef14bf98fd2e840be93a51b80477310129 100644
--- a/cmd/prototype.go
+++ b/cmd/prototype.go
@@ -40,6 +40,14 @@ func init() {
prototypeCmd.AddCommand(prototypePreviewCmd)
}
+var cmdShortDesc = map[string]string{
+ "list": `List all locally available ksonnet prototypes`,
+ "describe": `See more info about a prototype's output and usage`,
+ "preview": `Preview a prototype's output without creating a component (stdout)`,
+ "search": `Search for a prototype`,
+ "use": `Use the specified prototype to generate a component manifest`,
+}
+
var prototypeCmd = &cobra.Command{
Use: "prototype",
Short: `Instantiate, inspect, and get examples for ksonnet prototypes`,
@@ -49,49 +57,25 @@ var prototypeCmd = &cobra.Command{
}
return fmt.Errorf("Command 'prototype' requires a subcommand\n\n%s", cmd.UsageString())
},
- Long: `Manage, inspect, instantiate, and get examples for ksonnet prototypes.
-
-Prototypes are Kubernetes app configuration templates with "holes" that can be
-filled in by (e.g.) the ksonnet CLI tool or a language server. For example, a
-prototype for a` + " `apps.v1beta1.Deployment` " + `might require a name and image, and
-the ksonnet CLI could expand this to a fully-formed 'Deployment' object.
-
-Commands:
- use Instantiate prototype, filling in parameters from flags, and
- emitting the generated code to stdout.
- describe Display documentation and details about a prototype
- search Search for a prototype`,
-
- Example: `# Display documentation about prototype
-# 'io.ksonnet.pkg.prototype.simple-deployment', including:
-#
-# (1) a description of what gets generated during instantiation
-# (2) a list of parameters that are required to be passed in with CLI flags
-#
-# NOTE: Many subcommands only require the user to specify enough of the
-# identifier to disambiguate it among other known prototypes, which is why
-# 'simple-deployment' is given as argument instead of the fully-qualified
-# name.
-ks prototype describe simple-deployment
-
-# Instantiate prototype 'io.ksonnet.pkg.prototype.simple-deployment', using
-# the 'nginx' image, and port 80 exposed.
-#
-# SEE ALSO: Note above for a description of why this subcommand can take
-# 'simple-deployment' instead of the fully-qualified prototype name.
-ks prototype use simple-deployment \
- --name=nginx \
- --image=nginx \
- --port=80 \
- --portName=http
-
-# Search known prototype metadata for the string 'deployment'.
-ks prototype search deployment`,
+ Long: `
+Use the` + " `prototype` " + `subcommands to manage, inspect, instantiate, and get
+examples for ksonnet prototypes.
+
+Prototypes are pre-written but incomplete Kubernetes manifests, with "holes"
+(parameters) that can be filled in with the ksonnet CLI or manually. For example,
+the prototype` + " `io.ksonnet.pkg.single-port-deployment` " + `requires a name and image,
+and the ksonnet CLI can expand this into a fully-formed 'Deployment' object.
+
+These complete manifests are output into your ` + "`components/`" + ` directory. In other
+words, prototypes provide the basis for the **components** of your app. You can
+use prototypes to autogenerate boilerplate code and focus on customizing them
+for your use case.
+`,
}
var prototypeListCmd = &cobra.Command{
- Use: "list <name-substring>",
- Short: `List all known ksonnet prototypes`,
+ Use: "list",
+ Short: cmdShortDesc["list"],
RunE: func(cmd *cobra.Command, args []string) error {
if len(args) != 0 {
return fmt.Errorf("Command 'prototype list' does not take any arguments")
@@ -125,12 +109,29 @@ var prototypeListCmd = &cobra.Command{
return nil
},
- Long: `List all known ksonnet prototypes.`,
+ Long: `
+The ` + "`list`" + ` command displays all prototypes that are available locally, as
+well as brief descriptions of what they generate.
+
+ksonnet comes with a set of system prototypes that you can use out-of-the-box
+(e.g.` + " `io.ksonnet.pkg.configMap`" + `). However, you can use more advanced
+prototypes like ` + "`io.ksonnet.pkg.redis-stateless`" + ` by downloading extra packages
+from the *incubator* registry.
+
+### Related Commands
+
+* ` + "`ks prototype describe` " + `— ` + cmdShortDesc["describe"] + `
+* ` + "`ks prototype preview` " + `— ` + cmdShortDesc["preview"] + `
+* ` + "`ks prototype use` " + `— ` + cmdShortDesc["use"] + `
+* ` + "`ks pkg install` " + `— Install more prototypes (from external packages)
+
+### Syntax
+`,
}
var prototypeDescribeCmd = &cobra.Command{
Use: "describe <prototype-name>",
- Short: `Describe a ksonnet prototype`,
+ Short: cmdShortDesc["describe"],
RunE: func(cmd *cobra.Command, args []string) error {
if len(args) != 1 {
return fmt.Errorf("Command 'prototype describe' requires a prototype name\n\n%s", cmd.UsageString())
@@ -175,33 +176,31 @@ var prototypeDescribeCmd = &cobra.Command{
return nil
},
- Long: `Output documentation, examples, and other information for some ksonnet
-prototype uniquely identified by some (possibly partial)` + " `prototype-name`" + `. This
-includes:
-
- 1. a description of what gets generated during instantiation
- 2. a list of parameters that are required to be passed in with CLI flags
-
-` + "`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 'simple-deployment' might be
-unique enough to resolve to 'io.ksonnet.pkg.prototype.simple-deployment'.`,
-
- Example: `# Display documentation about prototype, including:
-ks prototype describe io.ksonnet.pkg.prototype.simple-deployment
-
-# Display documentation about prototype using a unique suffix of an
-# identifier. That is, this command only requires a long enough suffix to
-# uniquely identify a ksonnet prototype. In this example, the suffix
-# 'simple-deployment' is enough to uniquely identify
-# 'io.ksonnet.pkg.prototype.simple-deployment', but 'deployment' might not
-# be, as several names end with that suffix.
-ks prototype describe simple-deployment`,
+ Long: `
+This command outputs documentation, examples, and other information for
+the specified prototype (identified by name). Specifically, this describes:
+
+ 1. What sort of component is generated
+ 2. Which parameters (required and optional) can be passed in via CLI flags
+ to customize the component
+ 3. The file format of the generated component manifest (currently, Jsonnet only)
+
+### Related Commands
+
+* ` + "`ks prototype preview` " + `— ` + cmdShortDesc["preview"] + `
+* ` + "`ks prototype use` " + `— ` + cmdShortDesc["use"] + `
+
+### Syntax
+`,
+
+ Example: `
+# Display documentation about the prototype 'io.ksonnet.pkg.single-port-deployment'
+ks prototype describe deployment`,
}
var prototypeSearchCmd = &cobra.Command{
Use: "search <name-substring>",
- Short: `Search for a ksonnet prototype`,
+ Short: cmdShortDesc["search"],
RunE: func(cmd *cobra.Command, args []string) error {
if len(args) != 1 {
return fmt.Errorf("Command 'prototype search' requires a prototype name\n\n%s", cmd.UsageString())
@@ -221,16 +220,31 @@ var prototypeSearchCmd = &cobra.Command{
return nil
},
- Long: `Search ksonnet for prototypes whose names contain` + " `name-substring` " + `.`,
- Example: `# Search known prototype metadata for the string 'deployment'.
-ks prototype search deployment`,
+ Long: `
+The ` + "`prototype search`" + ` command allows you to search for specific prototypes by name.
+Specifically, it matches any prototypes with names that contain the string <name-substring>.
+
+### Related Commands
+
+* ` + "`ks prototype describe` " + `— ` + cmdShortDesc["describe"] + `
+* ` + "`ks prototype list` " + `— ` + cmdShortDesc["list"] + `
+
+### Syntax
+`,
+ Example: `
+# Search for prototypes with names that contain the string 'service'.
+ks prototype search service`,
}
var prototypePreviewCmd = &cobra.Command{
- Use: "preview <prototype-name> [type] [parameter-flags]",
- Short: `Expand prototype, emitting the generated code to stdout`,
+ Use: "preview <prototype-name> [parameter-flags]",
+ Short: cmdShortDesc["preview"],
DisableFlagParsing: true,
RunE: func(cmd *cobra.Command, rawArgs []string) error {
+ if len(rawArgs) == 1 && (rawArgs[0] == "--help" || rawArgs[0] == "-h") {
+ return cmd.Help()
+ }
+
if len(rawArgs) < 1 {
return fmt.Errorf("Command 'prototype preview' requires a prototype name\n\n%s", cmd.UsageString())
}
@@ -294,26 +308,27 @@ var prototypePreviewCmd = &cobra.Command{
fmt.Println(text)
return nil
},
- Long: `Expand prototype uniquely identified by (possibly partial)
-` + " `prototype-name` " + `, filling in parameters from flags, and emitting the generated
-code to stdout.
+ Long: `
+This ` + "`preview`" + ` command expands a prototype with CLI flag parameters, and
+emits the resulting manifest to stdout. This allows you to see the potential
+output of a ` + "`ks generate`" + ` command without actually creating a new component file.
-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'.`,
+The output is formatted in Jsonnet. To see YAML or JSON equivalents, first create
+a component with ` + "`ks generate`" + ` and then use ` + "`ks show`" + `.
- Example: `# Preview prototype 'io.ksonnet.pkg.single-port-deployment', using the
-# 'nginx' image, and port 80 exposed.
-ks prototype preview io.ksonnet.pkg.prototype.simple-deployment \
- --name=nginx \
- --image=nginx
+### Related Commands
-# Preview prototype using a unique suffix of an identifier. See
-# introduction of help message for more information on how this works.
-ks prototype preview simple-deployment \
- --name=nginx \
- --image=nginx`,
+* ` + "`ks generate` " + `— ` + cmdShortDesc["use"] + `
+
+### Syntax
+`,
+ Example: `
+# Preview prototype 'io.ksonnet.pkg.single-port-deployment', using the
+# 'nginx' image, and port 80 exposed.
+ks prototype preview single-port-deployment \
+ --name=nginx \
+ --image=nginx \
+ --port=80`,
}
// generateCmd acts as an alias for `prototype use`
@@ -327,7 +342,7 @@ var generateCmd = &cobra.Command{
var prototypeUseCmd = &cobra.Command{
Use: "use <prototype-name> <componentName> [type] [parameter-flags]",
- Short: `Expand prototype, place in components/ directory of ksonnet app`,
+ Short: cmdShortDesc["use"],
DisableFlagParsing: true,
RunE: func(cmd *cobra.Command, rawArgs []string) error {
if len(rawArgs) == 1 && (rawArgs[0] == "--help" || rawArgs[0] == "-h") {
@@ -409,33 +424,50 @@ var prototypeUseCmd = &cobra.Command{
return manager.CreateComponent(componentName, text, params, templateType)
},
- Long: `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 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'.`,
-
- Example: `# Instantiate prototype 'io.ksonnet.pkg.single-port-deployment', using the
+ Long: `
+The ` + "`generate`" + ` command (aliased from ` + "`prototype use`" + `) generates Kubernetes-
+compatible, Jsonnet ` + `manifests for components in your ksonnet app. Each prototype
+corresponds to a single manifest in the` + " `components/` " + `directory. This manifest
+can define one or more Kubernetes resources.
+
+1. The first argument, the **prototype name**, can either be fully qualified
+(e.g.` + " `io.ksonnet.pkg.single-port-service`" + `) or a partial match (e.g.` +
+ " `service`" + `).
+If using a partial match, note that any ambiguity in resolving the name will
+result in an error.
+
+2. The second argument, the **component name**, determines the filename for the
+generated component manifest. For example, the following command will expand
+template` + " `io.ksonnet.pkg.single-port-deployment` " + `and place it in the
+file` + " `components/nginx-depl.jsonnet` " + `. Note that by default ksonnet will
+expand prototypes into Jsonnet files.
+
+ ks prototype use io.ksonnet.pkg.single-port-deployment nginx-depl \
+ --name=nginx \
+ --image=nginx
+
+3. Prototypes can be further customized by passing in **parameters** via additional
+command line flags, such as` + " `--name` " + `and` + " `--image` " + `in the example above. Note that
+different prototypes support their own unique flags.
+
+### Related Commands
+
+* ` + "`ks apply` " + `— Apply your component manifests to a cluster
+* ` + "`ks param set` " + `— Change the values you specified when generating the component
+
+### Syntax
+`,
+ Example: `
+# Instantiate prototype 'io.ksonnet.pkg.single-port-deployment', using the
# 'nginx' image. The expanded prototype is placed in
# 'components/nginx-depl.jsonnet'.
-ks prototype use io.ksonnet.pkg.prototype.simple-deployment nginx-depl \
- --name=nginx \
+ks prototype use io.ksonnet.pkg.single-port-deployment nginx-depl \
+ --name=nginx \
--image=nginx
# Instantiate prototype 'io.ksonnet.pkg.single-port-deployment' using the
-# unique suffix, 'deployment'. The expanded prototype is again placed in
-# 'components/nginx-depl.jsonnet'. See introduction of help message for more
-# information on how this works. Note that if you have imported another
+# suffix, 'deployment'. The expanded prototype is again placed in
+# 'components/nginx-depl.jsonnet'. NOTE: if you have imported another
# prototype with this suffix, this may resolve ambiguously for you.
ks prototype use deployment nginx-depl \
--name=nginx \
diff --git a/docs/cli-reference/ks.md b/docs/cli-reference/ks.md
index 35e8e38d7eedd6d9d51a63e1c71db3c5cc76c137..8bdccec48727e00cd9e86589002afded9a23bd68 100644
--- a/docs/cli-reference/ks.md
+++ b/docs/cli-reference/ks.md
@@ -18,7 +18,7 @@ Synchronise Kubernetes resources with config files
* [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 generate](ks_generate.md) - Use the specified prototype to generate a component manifest
* [ks init](ks_init.md) - Initialize a ksonnet application
* [ks param](ks_param.md) - Manage ksonnet component parameters
* [ks pkg](ks_pkg.md) - Manage packages and dependencies for the current ksonnet project
diff --git a/docs/cli-reference/ks_generate.md b/docs/cli-reference/ks_generate.md
index ad0cfa510b66ab802c397d82e2daa344a42f0c85..993a18d446066400563e45378b817940a3ecbeb7 100644
--- a/docs/cli-reference/ks_generate.md
+++ b/docs/cli-reference/ks_generate.md
@@ -1,25 +1,42 @@
## ks generate
-Expand prototype, place in components/ directory of ksonnet app
+Use the specified prototype to generate a component manifest
### 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
+The `generate` command (aliased from `prototype use`) generates Kubernetes-
+compatible, Jsonnet manifests for components in your ksonnet app. Each prototype
+corresponds to a single manifest in the `components/` directory. This manifest
+can define one or more Kubernetes resources.
+
+1. The first argument, the **prototype name**, can either be fully qualified
+(e.g. `io.ksonnet.pkg.single-port-service`) or a partial match (e.g. `service`).
+If using a partial match, note that any ambiguity in resolving the name will
+result in an error.
+
+2. The second argument, the **component name**, determines the filename for the
+generated component manifest. For example, the following command will expand
+template `io.ksonnet.pkg.single-port-deployment` and place it in the
+file `components/nginx-depl.jsonnet` . Note that by default ksonnet will
+expand prototypes into Jsonnet files.
+
+ ks prototype use io.ksonnet.pkg.single-port-deployment nginx-depl \
+ --name=nginx \
+ --image=nginx
+
+3. Prototypes can be further customized by passing in **parameters** via additional
+command line flags, such as `--name` and `--image` in the example above. Note that
+different prototypes support their own unique flags.
+
+### Related Commands
+
+* `ks apply` — Apply your component manifests to a cluster
+* `ks param set` — Change the values you specified when generating the component
+
+### Syntax
-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]
diff --git a/docs/cli-reference/ks_prototype.md b/docs/cli-reference/ks_prototype.md
index 9a369956626d75b433fea0aadfe4ddd886ac55ba..d9d53fca33a495184e878f644278e1c4898296be 100644
--- a/docs/cli-reference/ks_prototype.md
+++ b/docs/cli-reference/ks_prototype.md
@@ -5,51 +5,23 @@ Instantiate, inspect, and get examples for ksonnet prototypes
### Synopsis
-Manage, inspect, instantiate, and get examples for ksonnet prototypes.
-Prototypes are Kubernetes app configuration templates with "holes" that can be
-filled in by (e.g.) the ksonnet CLI tool or a language server. For example, a
-prototype for a `apps.v1beta1.Deployment` might require a name and image, and
-the ksonnet CLI could expand this to a fully-formed 'Deployment' object.
+Use the `prototype` subcommands to manage, inspect, instantiate, and get
+examples for ksonnet prototypes.
-Commands:
- use Instantiate prototype, filling in parameters from flags, and
- emitting the generated code to stdout.
- describe Display documentation and details about a prototype
- search Search for a prototype
+Prototypes are pre-written but incomplete Kubernetes manifests, with "holes"
+(parameters) that can be filled in with the ksonnet CLI or manually. For example,
+the prototype `io.ksonnet.pkg.single-port-deployment` requires a name and image,
+and the ksonnet CLI can expand this into a fully-formed 'Deployment' object.
-```
-ks prototype
-```
+These complete manifests are output into your `components/` directory. In other
+words, prototypes provide the basis for the **components** of your app. You can
+use prototypes to autogenerate boilerplate code and focus on customizing them
+for your use case.
-### Examples
```
-# Display documentation about prototype
-# 'io.ksonnet.pkg.prototype.simple-deployment', including:
-#
-# (1) a description of what gets generated during instantiation
-# (2) a list of parameters that are required to be passed in with CLI flags
-#
-# NOTE: Many subcommands only require the user to specify enough of the
-# identifier to disambiguate it among other known prototypes, which is why
-# 'simple-deployment' is given as argument instead of the fully-qualified
-# name.
-ks prototype describe simple-deployment
-
-# Instantiate prototype 'io.ksonnet.pkg.prototype.simple-deployment', using
-# the 'nginx' image, and port 80 exposed.
-#
-# SEE ALSO: Note above for a description of why this subcommand can take
-# 'simple-deployment' instead of the fully-qualified prototype name.
-ks prototype use simple-deployment \
- --name=nginx \
- --image=nginx \
- --port=80 \
- --portName=http
-
-# Search known prototype metadata for the string 'deployment'.
-ks prototype search deployment
+ks prototype
```
### Options inherited from parent commands
@@ -60,9 +32,9 @@ ks prototype search deployment
### SEE ALSO
* [ks](ks.md) - Synchronise Kubernetes resources with config files
-* [ks prototype describe](ks_prototype_describe.md) - Describe a ksonnet prototype
-* [ks prototype list](ks_prototype_list.md) - List all known ksonnet prototypes
-* [ks prototype preview](ks_prototype_preview.md) - Expand prototype, emitting the generated code to stdout
-* [ks prototype search](ks_prototype_search.md) - Search for a ksonnet prototype
-* [ks prototype use](ks_prototype_use.md) - Expand prototype, place in components/ directory of ksonnet app
+* [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)
+* [ks prototype search](ks_prototype_search.md) - Search for a prototype
+* [ks prototype use](ks_prototype_use.md) - Use the specified prototype to generate a component manifest
diff --git a/docs/cli-reference/ks_prototype_describe.md b/docs/cli-reference/ks_prototype_describe.md
index 46f5af98db7f0d64bbac1f03d83e4b8c6be72ba1..3a1e373929376d0e8acc3067d082ddcc235c02a8 100644
--- a/docs/cli-reference/ks_prototype_describe.md
+++ b/docs/cli-reference/ks_prototype_describe.md
@@ -1,21 +1,26 @@
## ks prototype describe
-Describe a ksonnet prototype
+See more info about a prototype's output and usage
### Synopsis
-Output documentation, examples, and other information for some ksonnet
-prototype uniquely identified by some (possibly partial) `prototype-name`. This
-includes:
- 1. a description of what gets generated during instantiation
- 2. a list of parameters that are required to be passed in with CLI flags
+This command outputs documentation, examples, and other information for
+the specified prototype (identified by name). Specifically, this describes:
+
+ 1. What sort of component is generated
+ 2. Which parameters (required and optional) can be passed in via CLI flags
+ to customize the component
+ 3. The file format of the generated component manifest (currently, Jsonnet only)
+
+### Related Commands
+
+* `ks prototype preview` — Preview a prototype's output without creating a component (stdout)
+* `ks prototype use` — Use the specified prototype to generate a component manifest
+
+### Syntax
-`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 'simple-deployment' might be
-unique enough to resolve to 'io.ksonnet.pkg.prototype.simple-deployment'.
```
ks prototype describe <prototype-name>
@@ -24,16 +29,9 @@ ks prototype describe <prototype-name>
### Examples
```
-# Display documentation about prototype, including:
-ks prototype describe io.ksonnet.pkg.prototype.simple-deployment
-
-# Display documentation about prototype using a unique suffix of an
-# identifier. That is, this command only requires a long enough suffix to
-# uniquely identify a ksonnet prototype. In this example, the suffix
-# 'simple-deployment' is enough to uniquely identify
-# 'io.ksonnet.pkg.prototype.simple-deployment', but 'deployment' might not
-# be, as several names end with that suffix.
-ks prototype describe simple-deployment
+
+# Display documentation about the prototype 'io.ksonnet.pkg.single-port-deployment'
+ks prototype describe deployment
```
### Options inherited from parent commands
diff --git a/docs/cli-reference/ks_prototype_list.md b/docs/cli-reference/ks_prototype_list.md
index 73587a5cf92f96f9b174a8966b7cba571440b752..5866b2370fe872adf9c2bf79de7f909408fc63d2 100644
--- a/docs/cli-reference/ks_prototype_list.md
+++ b/docs/cli-reference/ks_prototype_list.md
@@ -1,14 +1,31 @@
## ks prototype list
-List all known ksonnet prototypes
+List all locally available ksonnet prototypes
### Synopsis
-List all known ksonnet prototypes.
+
+The `list` command displays all prototypes that are available locally, as
+well as brief descriptions of what they generate.
+
+ksonnet comes with a set of system prototypes that you can use out-of-the-box
+(e.g. `io.ksonnet.pkg.configMap`). However, you can use more advanced
+prototypes like `io.ksonnet.pkg.redis-stateless` by downloading extra packages
+from the *incubator* registry.
+
+### Related Commands
+
+* `ks prototype describe` — See more info about a prototype's output and usage
+* `ks prototype preview` — Preview a prototype's output without creating a component (stdout)
+* `ks prototype use` — Use the specified prototype to generate a component manifest
+* `ks pkg install` — Install more prototypes (from external packages)
+
+### Syntax
+
```
-ks prototype list <name-substring>
+ks prototype list
```
### Options inherited from parent commands
diff --git a/docs/cli-reference/ks_prototype_preview.md b/docs/cli-reference/ks_prototype_preview.md
index 2cecec55ffbf42e422108c0e2b670c048e5b6f1e..255c0968e9c0d1314aafdd7cc900aaff7a1437d3 100644
--- a/docs/cli-reference/ks_prototype_preview.md
+++ b/docs/cli-reference/ks_prototype_preview.md
@@ -1,37 +1,39 @@
## ks prototype preview
-Expand prototype, emitting the generated code to stdout
+Preview a prototype's output without creating a component (stdout)
### Synopsis
-Expand prototype uniquely identified by (possibly partial)
- `prototype-name` , filling in parameters from flags, and emitting the generated
-code to stdout.
-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'.
+This `preview` command expands a prototype with CLI flag parameters, and
+emits the resulting manifest to stdout. This allows you to see the potential
+output of a `ks generate` command without actually creating a new component file.
+
+The output is formatted in Jsonnet. To see YAML or JSON equivalents, first create
+a component with `ks generate` and then use `ks show`.
+
+### Related Commands
+
+* `ks generate` — Use the specified prototype to generate a component manifest
+
+### Syntax
+
```
-ks prototype preview <prototype-name> [type] [parameter-flags]
+ks prototype preview <prototype-name> [parameter-flags]
```
### Examples
```
+
# Preview prototype 'io.ksonnet.pkg.single-port-deployment', using the
# 'nginx' image, and port 80 exposed.
-ks prototype preview io.ksonnet.pkg.prototype.simple-deployment \
- --name=nginx \
- --image=nginx
-
-# Preview prototype using a unique suffix of an identifier. See
-# introduction of help message for more information on how this works.
-ks prototype preview simple-deployment \
- --name=nginx \
- --image=nginx
+ks prototype preview single-port-deployment \
+ --name=nginx \
+ --image=nginx \
+ --port=80
```
### Options inherited from parent commands
diff --git a/docs/cli-reference/ks_prototype_search.md b/docs/cli-reference/ks_prototype_search.md
index a679d931f4a2bc5873d01658c745a370b40ba0a7..fff8627593ba95f245ee7fd560f15bd0b5ba0067 100644
--- a/docs/cli-reference/ks_prototype_search.md
+++ b/docs/cli-reference/ks_prototype_search.md
@@ -1,11 +1,21 @@
## ks prototype search
-Search for a ksonnet prototype
+Search for a prototype
### Synopsis
-Search ksonnet for prototypes whose names contain `name-substring` .
+
+The `prototype search` command allows you to search for specific prototypes by name.
+Specifically, it matches any prototypes with names that contain the string <name-substring>.
+
+### Related Commands
+
+* `ks prototype describe` — See more info about a prototype's output and usage
+* `ks prototype list` — List all locally available ksonnet prototypes
+
+### Syntax
+
```
ks prototype search <name-substring>
@@ -14,8 +24,9 @@ ks prototype search <name-substring>
### Examples
```
-# Search known prototype metadata for the string 'deployment'.
-ks prototype search deployment
+
+# Search for prototypes with names that contain the string 'service'.
+ks prototype search service
```
### Options inherited from parent commands
diff --git a/docs/cli-reference/ks_prototype_use.md b/docs/cli-reference/ks_prototype_use.md
index 609a5ec501b96852d99e2d26b81b8a9bf4d822fa..49de3946d40b89fed7565b9862fa81c476574284 100644
--- a/docs/cli-reference/ks_prototype_use.md
+++ b/docs/cli-reference/ks_prototype_use.md
@@ -1,25 +1,42 @@
## ks prototype use
-Expand prototype, place in components/ directory of ksonnet app
+Use the specified prototype to generate a component manifest
### 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
+The `generate` command (aliased from `prototype use`) generates Kubernetes-
+compatible, Jsonnet manifests for components in your ksonnet app. Each prototype
+corresponds to a single manifest in the `components/` directory. This manifest
+can define one or more Kubernetes resources.
+
+1. The first argument, the **prototype name**, can either be fully qualified
+(e.g. `io.ksonnet.pkg.single-port-service`) or a partial match (e.g. `service`).
+If using a partial match, note that any ambiguity in resolving the name will
+result in an error.
+
+2. The second argument, the **component name**, determines the filename for the
+generated component manifest. For example, the following command will expand
+template `io.ksonnet.pkg.single-port-deployment` and place it in the
+file `components/nginx-depl.jsonnet` . Note that by default ksonnet will
+expand prototypes into Jsonnet files.
+
+ ks prototype use io.ksonnet.pkg.single-port-deployment nginx-depl \
+ --name=nginx \
+ --image=nginx
+
+3. Prototypes can be further customized by passing in **parameters** via additional
+command line flags, such as `--name` and `--image` in the example above. Note that
+different prototypes support their own unique flags.
+
+### Related Commands
+
+* `ks apply` — Apply your component manifests to a cluster
+* `ks param set` — Change the values you specified when generating the component
+
+### Syntax
-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 prototype use <prototype-name> <componentName> [type] [parameter-flags]
@@ -28,17 +45,17 @@ ks prototype use <prototype-name> <componentName> [type] [parameter-flags]
### Examples
```
+
# Instantiate prototype 'io.ksonnet.pkg.single-port-deployment', using the
# 'nginx' image. The expanded prototype is placed in
# 'components/nginx-depl.jsonnet'.
-ks prototype use io.ksonnet.pkg.prototype.simple-deployment nginx-depl \
- --name=nginx \
+ks prototype use io.ksonnet.pkg.single-port-deployment nginx-depl \
+ --name=nginx \
--image=nginx
# Instantiate prototype 'io.ksonnet.pkg.single-port-deployment' using the
-# unique suffix, 'deployment'. The expanded prototype is again placed in
-# 'components/nginx-depl.jsonnet'. See introduction of help message for more
-# information on how this works. Note that if you have imported another
+# suffix, 'deployment'. The expanded prototype is again placed in
+# 'components/nginx-depl.jsonnet'. NOTE: if you have imported another
# prototype with this suffix, this may resolve ambiguously for you.
ks prototype use deployment nginx-depl \
--name=nginx \