Introduction

Technically, you can force multi-line content through Helm's --set, but it is usually the wrong tool. Shell escaping, Helm parsing, and YAML quoting all stack on top of one another, which makes multi-line values brittle and hard to debug.

The practical answer is usually: do not use plain --set for multi-line strings. Use --set-file or pass a small override file with -f instead.

Why --set Is a Poor Fit for Multi-Line Content

--set works best for small scalar overrides such as:

helm install myapp ./chart --set image.tag=1.2.3

Once the value contains embedded newlines, indentation, or large text blobs, the command line becomes fragile. A shell may interpret newline escapes one way, Helm may parse them another way, and the final YAML may still not look the way your template expects.

That is why multi-line configuration data such as scripts, certificates, or large config blocks should usually come from a file.

Best Option: --set-file

If the chart value is supposed to contain the literal contents of a file, use --set-file:

helm install myapp ./chart \
  --set-file config.script=./startup.sh

If your template expects a multi-line string, render it with a block scalar:

1apiVersion: v1
2kind: ConfigMap
3metadata:
4  name: myapp-script
5data:
6  startup.sh: |
7{{ .Values.config.script | indent 4 }}

This is the cleanest approach for real multi-line payloads because the shell only passes a file path, not the whole text blob.

Another Good Option: Use an Override Values File

For larger or more structured overrides, use -f with a dedicated values file:

1# override.yaml
2config:
3  script: |
4    echo "starting"
5    echo "ready"

Then install with:

helm install myapp ./chart -f override.yaml

This is often the most maintainable solution because the YAML stays readable and versionable.

If You Absolutely Must Stay on the Command Line

In Bash or Zsh, process substitution can help you avoid editing a physical file:

1helm install myapp ./chart -f <(cat <<'YAML'
2config:
3  script: |
4    echo "starting"
5    echo "ready"
6YAML
7)

This still uses a values file conceptually, but it is generated inline for one command. It is much safer than trying to cram literal newline escapes into plain --set.

What About --set-string

--set-string is helpful when Helm would otherwise coerce a scalar value such as true, 123, or 001 into the wrong type. It does not solve the general readability and escaping problems of multi-line text.

So for multi-line content:

• '--set-string is usually not the main answer'
• '--set-file is usually the best answer'
• '-f is the most maintainable answer for structured overrides'

Common Pitfalls

• Forcing a multi-line config block through plain --set and then fighting shell escaping.
• Forgetting that the shell may process backslashes and newlines before Helm even sees them.
• Using a template that does not preserve indentation correctly for YAML block scalars.
• Reaching for --set-string when the real problem is not type coercion but multi-line structure.
• Treating a large config blob as an inline CLI override when it really belongs in a file.

Summary

• Plain --set is not a good tool for overriding multi-line strings.
• Prefer --set-file when the value should come from a file's contents.
• Prefer -f with a small override YAML file when the override is structured or long.
• Use process substitution if you need a file-like override without creating a permanent file.
• The more text you are trying to pass, the more likely it is that a file-based approach is the correct one.