diff --git a/docs/commands.md b/docs/commands.md
index c711368afb..15f18e84de 100644
--- a/docs/commands.md
+++ b/docs/commands.md
@@ -50,7 +50,18 @@ function setSecret(secret: string): void {}
 
 Now, future logs containing BAR will be masked. E.g. running `echo "Hello FOO BAR World"` will now print `Hello FOO **** World`.
 
-**WARNING** The add-mask and setSecret  commands only support single line secrets. To register a multiline secrets you must register each line individually otherwise it will not be masked.
+**WARNING** The add-mask and setSecret commands only support single-line
+secrets or multi-line secrets that have been escaped. `@actions/core`
+`setSecret` will escape the string you provide by default. When an escaped
+multi-line string is provided the whole string and each of its lines
+individually will be masked. For example you can mask `first\nsecond\r\nthird`
+using:
+
+```sh
+echo "::add-mask::first%0Asecond%0D%0Athird"
+```
+
+This will mask `first%0Asecond%0D%0Athird`, `first`, `second` and `third`.
 
 **WARNING** Do **not** mask short values if you can avoid it, it could render your output unreadable (and future steps' output as well).
 For example, if you mask the letter `l`, running `echo "Hello FOO BAR World"` will now print `He*********o FOO BAR Wor****d`
diff --git a/packages/core/__tests__/core.test.ts b/packages/core/__tests__/core.test.ts
index 5011fcc8bf..09bc587b03 100644
--- a/packages/core/__tests__/core.test.ts
+++ b/packages/core/__tests__/core.test.ts
@@ -161,7 +161,11 @@ describe('@actions/core', () => {
 
   it('setSecret produces the correct command', () => {
     core.setSecret('secret val')
-    assertWriteCalls([`::add-mask::secret val${os.EOL}`])
+    core.setSecret('multi\nline\r\nsecret')
+    assertWriteCalls([
+      `::add-mask::secret val${os.EOL}`,
+      `::add-mask::multi%0Aline%0D%0Asecret${os.EOL}`
+    ])
   })
 
   it('prependPath produces the correct commands and sets the env', () => {