cfbs input docs

Signed-off-by: Lars Erik Wik <lars.erik.wik@northern.tech>

JSON.md

@@ -172,3 +172,109 @@ cfbs init && cfbs add https://github.com/cfengine/some-repo
   ]
 }
 ```
+
+## Modules with input
+Some modules allow for users to add module input by responding to questions
+expressed in the `cfbs.json`. User responses generate
+[augments](https://docs.cfengine.com/docs/master/reference-language-concepts-augments.html)
+which added to `$(workdir)/masterfiles/def.json`. These questions are expressed
+under the `inputs` attribute of the `cfbs.json`. There are currently three ways
+to express input questions; string, object and list.
+
+A string input is the simplest expression you can make. It basically asks the
+user a question, and the response is stored as a string variable in `def.json`.
+
+The following example illustrates a module using string input in order to ask
+the user what file it should create.
+
+```json
+{
+  "name": "Example",
+  "type": "policy-set",
+  "description": "Example description",
+  "build": [
+    {
+      "name": "create-single-file",
+      "description": "Create a single file.",
+      "url": "https://github.com/larsewi/cfbs-test-modules.git",
+      "commit": "d95774c8c69a2895c687624851ef4ad9d5e0d02d",
+      "dependencies": ["autorun"],
+      "input": [
+        {
+          "name": "filename",
+          "prompt": {
+            "string": {
+              "label": "Filename",
+              "question": "What file should this module create?",
+            }
+          }
+        }
+      ],
+      "steps": [
+        "copy ./create-single-file.cf services/autorun/create-single-file.cf"
+      ],
+      "added_by": "cfbs add"
+    }
+  ]
+}
+```
+
+A user can add input by running the input command:
+
+```
+$ cfbs input create-single-file
+Collecting input for module 'create-single-file'
+What file should this module create? /tmp/testfile
+```
+
+The response is stored as a string variable with the name `filename`:
+
+```json
+{
+  "variables": {
+    "cfbs:create_single_file.filename": {
+      "value": "/tmp/testfile",
+      "comment": "Added by 'cfbs input'"
+    }
+  }
+}
+```
+
+The default namespace is set to `cfbs`, the default bundle name is set to be the
+module name canonified _(i.e. `create_single_file`)_, and the default comment is
+set to be `Input from 'cfbs input'.`. These attributes can be changed by the
+module developer by specifying the `namespace`, `bundle` and `comment`
+attributes respectively. E.g.
+
+```json
+...
+        {
+          "name": "filename",
+          "namespace": "my_namespace",
+          "bundle": "my_bundle",
+          "comment": "Example comment.",
+          "prompt": {
+            "string": {
+              "label": "Filename",
+              "question": "What file should this module create?",
+            }
+          }
+        }
+...
+```
+
+This would cause a similar response to produce the following output:
+
+```json
+{
+  "variables": {
+    "my_namespace:my_bundle.filename": {
+      "value": "/tmp/testfile",
+      "comment": "Example comment."
+    }
+  }
+}
+```
+
+An object input expression allows for users to generate more complex JSON
+objects.