From fa996f21ddd4a5d3d912a8c5362a2184cfbf3a43 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 5 May 2026 19:16:41 +0000
Subject: [PATCH 1/2] Initial plan


From 8b65ccd0325ec3b9e0cd489dc0ad4f8b2a844c2c Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 5 May 2026 19:20:10 +0000
Subject: [PATCH 2/2] Fix incorrect shebang recommendation in file-based apps
 docs

Agent-Logs-Url: https://github.com/dotnet/docs/sessions/686c76cc-7134-414a-84d4-cc62a14aa6c1

Co-authored-by: adegeo <67293991+adegeo@users.noreply.github.com>
---
 docs/core/sdk/file-based-apps.md | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/docs/core/sdk/file-based-apps.md b/docs/core/sdk/file-based-apps.md
index 0ff2a73c00b4f..91a9aabc6ba80 100644
--- a/docs/core/sdk/file-based-apps.md
+++ b/docs/core/sdk/file-based-apps.md
@@ -318,7 +318,7 @@ Enable direct execution of file-based apps on Unix-like systems by using a sheba
 Add a shebang at the top of your file:
 
 ```csharp
-#!/usr/bin/env dotnet
+#!/usr/bin/env -S dotnet --
 #:package Spectre.Console
 
 using Spectre.Console;
@@ -341,6 +341,11 @@ Run directly:
 > [!NOTE]
 > Use `LF` line endings instead of `CRLF` when you add a shebang. Don't include a BOM in the file.
 
+To prevent `dotnet` from consuming arguments that match its own parameters—such as `--help`—the shebang uses `--` as a separator. The `--` separator tells `dotnet` to forward all subsequent command-line arguments directly to your app. The `-S` flag lets `env` split the remaining text into separate arguments so you can include `--` in the shebang.
+
+> [!NOTE]
+> If `-S` isn't supported on your system, use `#!/usr/bin/env dotnet` instead. With this shebang, `dotnet` might consume arguments that match its own CLI parameters.
+
 ## Implicit build files
 
 File-based apps respect MSBuild and NuGet configuration files in the same directory or parent directories. These files affect how the SDK builds your application. Be mindful of these files when organizing your file-based apps.