From 1c3f4fe80f0a74259ff282be41735088a9d01f62 Mon Sep 17 00:00:00 2001
From: Matthew Sanabria <24284972+sudomateo@users.noreply.github.com>
Date: Tue, 25 May 2021 10:06:23 -0400
Subject: [PATCH] Add examples to `terraform console` command (#28773)

These examples showcase come use cases for `terraform console`.
---
 website/docs/cli/commands/console.html.md | 75 ++++++++++++++++++++++-
 1 file changed, 73 insertions(+), 2 deletions(-)

diff --git a/website/docs/cli/commands/console.html.md b/website/docs/cli/commands/console.html.md
index 5d888ead1..71ed6d62f 100644
--- a/website/docs/cli/commands/console.html.md
+++ b/website/docs/cli/commands/console.html.md
@@ -43,8 +43,12 @@ final command is printed unless an error occurs earlier.
 For example:
 
 ```shell
-$ echo "1 + 5" | terraform console
-6
+$ echo 'split(",", "foo,bar,baz")' | terraform console
+tolist([
+  "foo",
+  "bar",
+  "baz",
+])
 ```
 
 ## Remote State
@@ -52,3 +56,70 @@ $ echo "1 + 5" | terraform console
 If [remote state](/docs/language/state/remote.html) is used by the current backend,
 Terraform will read the state for the current workspace from the backend
 before evaluating any expressions.
+
+## Examples
+
+The `terraform console` command will read the Terraform configuration in the
+current working directory and the Terraform state file from the configured
+backend so that interpolations can be tested against both the values in the
+configuration and the state file.
+
+With the following `main.tf`:
+
+```hcl
+variable "apps" {
+  type = map(any)
+  default = {
+    "foo" = {
+      "region" = "us-east-1",
+    },
+    "bar" = {
+      "region" = "eu-west-1",
+    },
+    "baz" = {
+      "region" = "ap-south-1",
+    },
+  }
+}
+
+resource "random_pet" "example" {
+  for_each = var.apps
+}
+```
+
+Executing `terraform console` will drop you into an interactive shell where you
+can test interpolations to:
+
+Print a value from a map:
+
+```
+> var.apps.foo
+{
+  "region" = "us-east-1"
+}
+```
+
+Filter a map based on a specific value:
+
+```
+> { for key, value in var.apps : key => value if value.region == "us-east-1" }
+{
+  "foo" = {
+    "region" = "us-east-1"
+  }
+}
+```
+
+Check if certain values may not be known until apply:
+
+```
+> random_pet.example
+(known after apply)
+```
+
+Test various functions:
+
+```
+> cidrnetmask("172.16.0.0/12")
+"255.240.0.0"
+```