fix(core): properly quote shell metacharacters in CLI args passed to tasks

[baer]

Current Behavior

When CLI arguments containing shell metacharacters (like |, &, $, ;, *, etc.) are passed through Nx to underlying tasks, they are not properly quoted, causing shell interpretation errors.

For example, running:

nx test app --grep="@tag1|@tag2"

Would fail with /bin/sh: @smoke: command not found because the pipe character | was interpreted by the shell as a pipe operator instead of being passed as a literal string to the underlying command.

Users had to use awkward double-quoting workarounds like --grep='"@tag1|@tag2"' to get the expected behavior.

Expected Behavior

CLI arguments containing shell metacharacters should be automatically quoted before being passed to underlying commands, so that:

nx test app --grep="@tag1|@tag2"

Works correctly and passes --grep="@tag1|@tag2" to the underlying test runner without shell interpretation.

Related Issue(s)

Fixes #32305
Fixes #26682

Implementation Details

• Created a shared needsShellQuoting() utility in packages/nx/src/utils/shell-quoting.ts that detects shell metacharacters
• Updated wrapArgIntoQuotesIfNeeded() in run-commands.impl.ts to use the shared utility
• Updated stringShouldBeWrappedIntoQuotes() in serialize-overrides-into-command-line.ts to use the shared utility
• Fixed a bug where arg.split('=') would incorrectly split values containing = (e.g., --define=FOO=bar|baz)
• Added proper escaping of embedded double quotes when wrapping values
• Added comprehensive test coverage

Shell metacharacters now handled:

| & ; < > ( ) $ ` \ " ' * ? [ ] { } ~ # ! and whitespace

[netlify]

✅ Deploy Preview for nx-docs canceled.

Name	Link
🔨 Latest commit	2ed5bb2
🔍 Latest deploy log	https://app.netlify.com/projects/nx-docs/deploys/69a16ea24c176c0008d76ec6

[netlify]

✅ Deploy Preview for nx-dev canceled.

Name	Link
🔨 Latest commit	2ed5bb2
🔍 Latest deploy log	https://app.netlify.com/projects/nx-dev/deploys/69a16ea2083cea000889df41

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 2991056

Command	Status	Duration	Result
nx affected --targets=lint,test,build,e2e,e2e-c...	✅ Succeeded	51m 36s	View ↗
nx run-many -t check-imports check-lock-files c...	✅ Succeeded	3m 25s	View ↗
nx-cloud record -- nx-cloud conformance:check	✅ Succeeded	8s	View ↗
nx-cloud record -- nx format:check	✅ Succeeded	2s	View ↗
nx-cloud record -- nx sync:check	✅ Succeeded	<1s	View ↗

---

☁️ Nx Cloud last updated this comment at 2026-02-27 16:11:33 UTC

[nx-cloud]

Important

At least one additional CI pipeline execution has run since the conclusion below was written and it may no longer be applicable.

Nx Cloud is proposing a fix for your failed CI:

We've updated the shell quoting logic to properly handle values that are already wrapped in quotes. The original implementation only checked if a value started with a quote character, but didn't verify if it was fully wrapped in matching quotes, causing shell parsing errors when literal quoted strings were passed as arguments. This fix detects fully-wrapped single and double quotes, strips double quotes for re-processing, and preserves single quotes as-is, ensuring shell metacharacters are properly escaped while respecting existing quoting conventions.

Warning

❌ We could not verify this fix.

Suggested Fix changes

diff --git a/packages/nx/src/executors/run-commands/run-commands.impl.ts b/packages/nx/src/executors/run-commands/run-commands.impl.ts
index bbbcfa69b9..21f207c674 100644
--- a/packages/nx/src/executors/run-commands/run-commands.impl.ts
+++ b/packages/nx/src/executors/run-commands/run-commands.impl.ts
@@ -398,22 +398,49 @@ function wrapArgIntoQuotesIfNeeded(arg: string): string {
     // Split only on first '=' to handle values containing '='
     const eqIndex = arg.indexOf('=');
     const key = arg.substring(0, eqIndex);
-    const value = arg.substring(eqIndex + 1);
-    if (
-      key.startsWith('--') &&
-      needsShellQuoting(value) &&
-      !(value[0] === "'" || value[0] === '"')
-    ) {
+    let value = arg.substring(eqIndex + 1);
+
+    // Check if value is wrapped in matching quotes
+    if (value.length >= 2) {
+      const firstChar = value[0];
+      const lastChar = value[value.length - 1];
+
+      if (firstChar === "'" && lastChar === "'") {
+        // Preserve single-quoted values as-is
+        return arg;
+      } else if (firstChar === '"' && lastChar === '"') {
+        // Strip outer double quotes and re-process the inner content
+        value = value.substring(1, value.length - 1);
+      }
+    }
+
+    if (key.startsWith('--') && needsShellQuoting(value)) {
       // Escape any existing double quotes in the value
       const escaped = value.replace(/"/g, '\\"');
       return `${key}="${escaped}"`;
     }
-    return arg;
-  } else if (needsShellQuoting(arg) && !(arg[0] === "'" || arg[0] === '"')) {
-    // Escape any existing double quotes in the value
-    const escaped = arg.replace(/"/g, '\\"');
-    return `"${escaped}"`;
+    return `${key}=${value}`;
   } else {
+    // Handle positional arguments
+    // Check if already wrapped in matching quotes
+    if (arg.length >= 2) {
+      const firstChar = arg[0];
+      const lastChar = arg[arg.length - 1];
+
+      if (firstChar === "'" && lastChar === "'") {
+        // Preserve single-quoted values as-is
+        return arg;
+      } else if (firstChar === '"' && lastChar === '"') {
+        // Strip outer double quotes and re-process the inner content
+        arg = arg.substring(1, arg.length - 1);
+      }
+    }
+
+    if (needsShellQuoting(arg)) {
+      // Escape any existing double quotes in the value
+      const escaped = arg.replace(/"/g, '\\"');
+      return `"${escaped}"`;
+    }
     return arg;
   }
 }

🔔 Heads up, your workspace has pending recommendations ↗ to auto-apply fixes for similar failures.

Because this branch comes from a fork, it is not possible for us to apply fixes directly, but you can apply the changes locally using the available options below.

Apply changes locally with:

npx nx-cloud apply-locally iKWx-mv3h

Apply fix locally with your editor ↗   View interactive diff ↗

_{🎓 Learn more about Self-Healing CI on nx.dev}

[leosvelperez]

@baer thanks for contributing!

I fixed an issue caught by our e2e test suite and added additional tests to prevent regressions. Could you re-verify on your end that everything still works for you?