website: Explicit examples of -var escaping in various shells

The -var command line option comes with the disadvantage that a user must
contend both with Terraform's own parser and with the parser in whichever
shell they've decided to use, and different shells on different platforms
have different rules.

Previously we've largely just assumed that folks know the appropriate
syntax for the shell they chose, but it seems that command lines involving
spaces and other special characters arise rarely enough in other commands
that Terraform is often the first time someone needs to learn the
appropriate syntax for their shell.

We can't possibly capture all of the details of all shells in our docs,
because that's far outside of our own scope, but hopefully this new
section will go some way to give some real examples that will help folks
figure out how to write suitable escape sequences, if they choose to
set complex variable values on the command line rather than in .tfvars
as we recommend elsewhere on this page.

website/docs/cli/commands/plan.html.md

@@ -176,7 +176,9 @@ the previous section, are also available with the same meanings on
 * `-var 'NAME=VALUE` - Sets a value for a single
   [input variable](/docs/language/values/variables.html) declared in the
   root module of the configuration. Use this option multiple times to set
-  more than one variable.
+  more than one variable. For more information see
+  [Input Variables on the Command Line](#input-variables-on-the-command-line),
+  below.
 
 * `-var-file=FILENAME` - Sets values for potentially many
   [input variables](/docs/language/values/variables.html) declared in the
@@ -189,6 +191,79 @@ module, aside from the `-var` and `-var-file` options. For more information,
 see
 [Assigning Values to Root Module Variables](/docs/language/values/variables.html#assigning-values-to-root-module-variables).
 
+### Input Variables on the Command Line
+
+You can use the `-var` command line option to specify values for
+[input variables](/docs/language/values/variables.html) declared in your
+root module.
+
+However, to do so will require writing a command line that is parsable both
+by your chosen command line shell _and_ Terraform, which can be complicated
+for expressions involving lots of quotes and escape sequences. In most cases
+we recommend using the `-var-file` option instead, and write your actual values
+in a separate file so that Terraform can parse them directly, rather than
+interpreting the result of your shell's parsing.
+
+To use `-var` on a Unix-style shell on a system like Linux or macOS we
+recommend writing the option argument in single quotes `'` to ensure the
+shell will interpret the value literally:
+
+```
+terraform plan -var 'name=value'
+```
+
+If your intended value also includes a single quote then you'll still need to
+escape that for correct interpretation by your shell, which also requires
+temporarily ending the quoted sequence so that the backslash escape character
+will be significant:
+
+```
+terraform plan -var 'name=va'\''lue'
+```
+
+When using Terraform on Windows, we recommend using the Windows Command Prompt
+(`cmd.exe`). When you pass a variable value to Terraform from the Windows
+Command Prompt, use double quotes `"` around the argument:
+
+```
+terraform plan -var "name=value"
+```
+
+If your intended value includes literal double quotes then you'll need to
+escape those with a backslash:
+
+```
+terraform plan -var "name=va\"lue"
+```
+
+PowerShell on Windows cannot correctly pass literal quotes to external programs,
+so we do not recommend using Terraform with PowerShell when you are on Windows.
+Use Windows Command Prompt instead.
+
+The appropriate syntax for writing the variable value is different depending
+on the variable's [type constraint](/docs/language/expressions/type-constraints.html).
+The primitive types `string`, `number`, and `bool` all expect a direct string
+value with no special punctuation except that required by your shell, as
+shown in the above examples. For all other type constraints, including list,
+map, and set types and the special `any` keyword, you must write a valid
+Terraform language expression representing the value, and write any necessary
+quoting or escape characters to ensure it will pass through your shell
+literally to Terraform. For example, for a `list(string)` type constraint:
+
+```
+# Unix-style shell
+terraform plan -var 'name=["a", "b", "c"]'
+
+# Windows Command Prompt (do not use PowerShell on Windows)
+terraform plan -var "name=[\"a\", \"b\", \"c\"]"
+```
+
+Similar constraints apply when setting input variables using environment
+variables. For more information on the various methods for setting root module
+input variables, see
+[Assigning Values to Root Module Variables](/docs/language/values/variables.html#assigning-values-to-root-module-variables).
+
+
 ### Resource Targeting
 
 > **Hands-on:** Try the [Target resources](https://learn.hashicorp.com/tutorials/terraform/resource-targeting?in=terraform/state&utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial on HashiCorp Learn.

website/docs/language/values/variables.html.md

@@ -349,7 +349,13 @@ terraform apply -var='image_id_list=["ami-abc123","ami-def456"]' -var="instance_
 terraform apply -var='image_id_map={"us-east-1":"ami-abc123","us-east-2":"ami-def456"}'
 ```
 
-The `-var` option can be used any number of times in a single command.
+The above examples show appropriate syntax for Unix-style shells, such as on
+Linux or macOS. For more information on shell quoting, including additional
+examples for Windows Command Prompt, see
+[Input Variables on the Command Line](/docs/cli/commands/plan.html#input-variables-on-the-command-line).
+
+You can use the `-var` option multiple times in a single command to set several
+different variables.
 
 <a id="variable-files"></a>
 
@@ -424,10 +430,11 @@ to assign complex-typed values, like lists and maps.
 
 Some special rules apply to the `-var` command line option and to environment
 variables. For convenience, Terraform defaults to interpreting `-var` and
-environment variable values as literal strings, which do not need to be quoted:
+environment variable values as literal strings, which need only shell quoting,
+and no special quoting for Terraform. For example, in a Unix-style shell:
 
 ```
-$ export TF_VAR_image_id=ami-abc123
+$ export TF_VAR_image_id='ami-abc123'
 ```
 
 However, if a root module variable uses a [type constraint](#type-constraints)
@@ -442,6 +449,9 @@ $ export TF_VAR_availability_zone_names='["us-west-1b","us-west-1d"]'
 
 For readability, and to avoid the need to worry about shell escaping, we
 recommend always setting complex variable values via variable definitions files.
+For more information on quoting and escaping for `-var` arguments,
+see
+[Input Variables on the Command Line](/docs/cli/commands/plan.html#input-variables-on-the-command-line).
 
 ### Values for Undeclared Variables