From d759b7b4da11ae75eee7ecda3d03fcf779b554a3 Mon Sep 17 00:00:00 2001
From: Jan-Philipp Benecke <jan-philipp.benecke@jpbe.de>
Date: Fri, 13 Nov 2020 18:18:38 +0100
Subject: [PATCH] Document: CLI variables (#918)

* Initial version of CLI variables doc

* Add example based on comments

Co-authored-by: Tom Limoncelli <tlimoncelli@stackoverflow.com>
---
 docs/cli-variables.md | 64 +++++++++++++++++++++++++++++++++++++++++++
 docs/index.md         |  3 ++
 docs/toc.md           |  1 +
 3 files changed, 68 insertions(+)
 create mode 100644 docs/cli-variables.md

diff --git a/docs/cli-variables.md b/docs/cli-variables.md
new file mode 100644
index 000000000..c0babd76b
--- /dev/null
+++ b/docs/cli-variables.md
@@ -0,0 +1,64 @@
+---
+layout: default
+title: CLI variables
+---
+# CLI variables
+
+With dnscontrol you can pass variables from CLI into your `dnsconfig.js`.
+This gives you the opportunity to run different code when a value is passed.
+
+## 1. Passing variables
+To pass a variable from CLI, just use the parameter `-v key=value` of the commands `preview` or `push`.
+
+Example: `dnscontrol push -v testKey=testValue`
+
+This would pass the variable with the name `testKey` and the value of `testValue` to `dnsconfig.js`
+
+## 2. Define defaults
+If you want to define some default values, that are used when no variable is passed from CLI,
+you can do this with the following function:
+
+```js
+CLI_DEFAULTS({
+  'testValue': 'defaultValue'
+});
+```
+
+You need to define this defaults just once in your `dnsconfig.js`.
+Define the defaults **before** using it.
+
+_Please keep in mind, if there is no default value and you do not pass a variable, but you are using it in your `dnsconfig.js` it will fail!_
+
+## 3. Use cases
+See some use cases for CLI variables.
+
+#### Different IPs for internal/external DNS
+```js
+CLI_DEFAULTS({
+  'cliServer': 'external'
+});
+if (this.view == "internal") {
+    var host01 = "192.168.0.16";
+    var host02 = "192.168.0.17";
+} else {
+    var host01 = "10.0.0.16";
+    var host02 = "10.0.0.17";
+}
+
+D("example.org", registrar, DnsProvider(public), DnsProvider(bind),
+  A('sitea', host01, TTL(1800)),
+  A('siteb', host01, TTL(1800)),
+  A('sitec', host02, TTL(1800)),
+  A('sited', host02, TTL(1800))
+);
+```
+Running `dnscontrol push -v view=internal` would generate the zone for your internal dns.
+
+Just running `dnscontrol push` would generate the zone for your external dns.
+
+So you can use the same zone for external and internal resolution and there is no need to duplicate it.
+
+#### ProTip
+The cli variables functionality permits you to create very complex and
+sophisticated configurations, but you shouldn't. Be nice to the next
+person that edits the file, who may not be as expert as yourself.
diff --git a/docs/index.md b/docs/index.md
index 83005c5cd..15abced52 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -93,6 +93,9 @@ title: DNSControl
 				<li>
 					<a href="{{site.github.url}}/migrating">Migrating</a>: Migrating zones to DNSControl
 				</li>
+				<li>
+				    <a href="{{site.github.url}}/cli-variables">CLI variables</a>: Passing variables from CLI to JS
+				</li>
 			</ul>
 		</div>
 		<div class="col-md-4">
diff --git a/docs/toc.md b/docs/toc.md
index 50cb96cd3..9334cd26c 100644
--- a/docs/toc.md
+++ b/docs/toc.md
@@ -8,6 +8,7 @@ title: TOC
 - [Providers]({{site.github.url}}/provider-list): Which DNS providers are supported.
 - [Examples]({{site.github.url}}/examples): The DNSControl language by example.
 - [Migrating]({{site.github.url}}/migrating): Migrating zones to DNSControl.
+- [CLI Variables]({{site.github.url}}/cli-variales): Passing variables from CLI to JS
 
 ## Reference
 - [Language Reference]({{site.github.url}}/js): Description of the DNSControl language (DSL).