chore(docs): document how to correctly override list(string) parameters (#15497)

johnstcn · web-flow · commit 55dccae5a3f6 · 2024-11-13T15:41:36.000Z
- Adds documentation for how to correctly hold --parameter with list(string)
- Adds tests for the aforementioned documented correct finger positions for --parameter list(string)
diff --git a/cli/create_test.go b/cli/create_test.go
@@ -864,24 +864,34 @@ func TestCreateValidateRichParameters(t *testing.T) {
 		coderdtest.AwaitTemplateVersionJobCompleted(t, client, version.ID)
 		template := coderdtest.CreateTemplate(t, client, owner.OrganizationID, version.ID)
 
-		inv, root := clitest.New(t, "create", "my-workspace", "--template", template.Name)
-		clitest.SetupConfig(t, member, root)
-		pty := ptytest.New(t).Attach(inv)
-		clitest.Start(t, inv)
+		t.Run("Prompt", func(t *testing.T) {
+			inv, root := clitest.New(t, "create", "my-workspace-1", "--template", template.Name)
+			clitest.SetupConfig(t, member, root)
+			pty := ptytest.New(t).Attach(inv)
+			clitest.Start(t, inv)
+
+			pty.ExpectMatch(listOfStringsParameterName)
+			pty.ExpectMatch("aaa, bbb, ccc")
+			pty.ExpectMatch("Confirm create?")
+			pty.WriteLine("yes")
+		})
 
-		matches := []string{
-			listOfStringsParameterName, "",
-			"aaa, bbb, ccc", "",
-			"Confirm create?", "yes",
-		}
-		for i := 0; i < len(matches); i += 2 {
-			match := matches[i]
-			value := matches[i+1]
-			pty.ExpectMatch(match)
-			if value != "" {
-				pty.WriteLine(value)
-			}
-		}
+		t.Run("Default", func(t *testing.T) {
+			t.Parallel()
+			inv, root := clitest.New(t, "create", "my-workspace-2", "--template", template.Name, "--yes")
+			clitest.SetupConfig(t, member, root)
+			clitest.Run(t, inv)
+		})
+
+		t.Run("CLIOverride/DoubleQuote", func(t *testing.T) {
+			t.Parallel()
+
+			// Note: see https://go.dev/play/p/vhTUTZsVrEb for how to escape this properly
+			parameterArg := fmt.Sprintf(`"%s=[""ddd=foo"",""eee=bar"",""fff=baz""]"`, listOfStringsParameterName)
+			inv, root := clitest.New(t, "create", "my-workspace-3", "--template", template.Name, "--parameter", parameterArg, "--yes")
+			clitest.SetupConfig(t, member, root)
+			clitest.Run(t, inv)
+		})
 	})
 
 	t.Run("ValidateListOfStrings_YAMLFile", func(t *testing.T) {
diff --git a/docs/admin/templates/extending-templates/parameters.md b/docs/admin/templates/extending-templates/parameters.md
@@ -79,6 +79,31 @@ data "coder_parameter" "security_groups" {
 }
 ```
 
+> [!NOTE] Overriding a `list(string)` on the CLI is tricky because:
+>
+> - `--parameter "parameter_name=parameter_value"` is parsed as CSV.
+> - `parameter_value` is parsed as JSON.
+>
+> So, to properly specify a `list(string)` with the `--parameter` CLI argument,
+> you will need to take care of both CSV quoting and shell quoting.
+>
+> For the above example, to override the default values of the `security_groups`
+> parameter, you will need to pass the following argument to `coder create`:
+>
+> ```
+> --parameter "\"security_groups=[\"\"DevOps Security Group\"\",\"\"Backend Security Group\"\"]\""
+> ```
+>
+> Alternatively, you can use `--rich-parameter-file` to work around the above
+> issues. This allows you to specify parameters as YAML. An equivalent parameter
+> file for the above `--parameter` is provided below:
+>
+> ```yaml
+> security_groups:
+>   - DevOps Security Group
+>   - Backend Security Group
+> ```
+
 ## Options
 
 A `string` parameter can provide a set of options to limit the user's choices:
