From 8c7081d614b3033005a031d889c591991ff2f975 Mon Sep 17 00:00:00 2001
From: Rishikesh Singh <rishikesh.singh.cg@gmail.com>
Date: Sat, 26 Sep 2026 13:38:17 +0530
Subject: [PATCH] docs: improve CLI pass-through argument documentation for
 Windows (#1336)

- Keep standard CLI examples using unquoted -- separator
- Add dedicated notes explaining the quotation requirement ("--") for Windows (Command Prompt and PowerShell)
- Add Passing Platform-Specific Arguments section to the Cordova CLI guide with notes for Windows users
- Fixes #1336
---
 www/docs/en/latest/guide/cli/index.md         | 19 +++++++++++
 .../latest/guide/platforms/android/index.md   | 32 ++++++++++++++++---
 .../en/latest/guide/platforms/ios/index.md    |  8 +++--
 3 files changed, 52 insertions(+), 7 deletions(-)

diff --git a/www/docs/en/latest/guide/cli/index.md b/www/docs/en/latest/guide/cli/index.md
index ca23476d35b..f6d3cfcfc5e 100644
--- a/www/docs/en/latest/guide/cli/index.md
+++ b/www/docs/en/latest/guide/cli/index.md
@@ -116,9 +116,28 @@ You can optionally limit the scope of each build to specific platforms - 'ios' i
 cordova build ios
 ```
 
+### Passing Platform-Specific Arguments
+
+When using `cordova build` or `cordova run`, you can pass platform-specific options (such as signing flags or Gradle parameters) by prefixing them with the `--` pass-through separator:
+
+```bash
+# Example passing Gradle flags on Android
+cordova build android -- --gradleArg=-PcdvMinSdkVersion=20
+
+# Example passing signing flags on Android
+cordova build android --release -- --packageType=apk
+```
+
+> **Note for Windows users:** On Windows (Command Prompt and PowerShell), the `--` separator must be enclosed in quotation marks (`"--"`) so that the shell forwards the arguments to platform build scripts correctly, for example:
+> ```bash
+> cordova build android --release "--" --packageType=apk
+> ```
+
 **See Also:**
 
 - [Cordova build command reference documentation][cdv_build]
+- [Android Platform Guide](../../guide/platforms/android/index.html)
+- [iOS Platform Guide](../../guide/platforms/ios/index.html)
 
 ## Test the App
 
diff --git a/www/docs/en/latest/guide/platforms/android/index.md b/www/docs/en/latest/guide/platforms/android/index.md
index f2de675cd73..65dc453d238 100644
--- a/www/docs/en/latest/guide/platforms/android/index.md
+++ b/www/docs/en/latest/guide/platforms/android/index.md
@@ -470,7 +470,7 @@ You can set these properties in one of four ways:
 
 - Using an Environment Variables:
 
-    **Example:**
+    **Example (Unix/macOS):**
 
     ```bash
     export ORG_GRADLE_PROJECT_cdvMinSdkVersion=20
@@ -479,12 +479,18 @@ You can set these properties in one of four ways:
 
 - Using the `--gradleArg` flag with the Cordova `build` or `run` command:
 
-    **Example:**
+    **Example (Unix/macOS):**
 
     ```bash
     cordova run android -- --gradleArg=-PcdvMinSdkVersion=20
     ```
 
+    **Example (Windows):**
+
+    ```bash
+    cordova run android "--" --gradleArg=-PcdvMinSdkVersion=20
+    ```
+
 - Creating a `gradle.properties` in the project's Android platform directory
 
     Create a file named `gradle.properties` in the directory `<project-root>/platforms/android` with the contents such as:
@@ -559,10 +565,18 @@ To change the Gradle JVM args, the `--jvmargs` flag can be used with both Cordov
 
 By default, JVM args has a value of `-Xmx2048m`. To increase the maximum allowed memory, use the `-Xmx` JVM arg. Example given below:
 
-```
+**Example (Unix/macOS):**
+
+```bash
 cordova build android -- --jvmargs='-Xmx4g'
 ```
 
+**Example (Windows):**
+
+```bash
+cordova build android "--" --jvmargs="-Xmx4g"
+```
+
 The following units are supported:
 
 | unit      | value     | example
@@ -609,9 +623,17 @@ The parameters above can be specified as an argument when using the [Cordova CLI
 
 _**Note**: You should use double `--` to indicate that these are platform-specific arguments._
 
-Example:
+**Example (Unix/macOS):**
+
+```bash
+cordova run android --release -- --keystore=../my-release-key.keystore --storePassword=password --alias=alias_name --password=password --packageType=bundle
+```
+
+**Example (Windows):**
 
-`cordova run android --release -- --keystore=../my-release-key.keystore --storePassword=password --alias=alias_name --password=password --packageType=bundle`.
+```bash
+cordova run android --release "--" --keystore=../my-release-key.keystore --storePassword=password --alias=alias_name --password=password --packageType=bundle
+```
 
 ### Using `build.json`
 
diff --git a/www/docs/en/latest/guide/platforms/ios/index.md b/www/docs/en/latest/guide/platforms/ios/index.md
index 97f02eed02c..38e41568749 100644
--- a/www/docs/en/latest/guide/platforms/ios/index.md
+++ b/www/docs/en/latest/guide/platforms/ios/index.md
@@ -231,9 +231,13 @@ To sign an app, you need the following parameters:
 
 These parameters can be specified using the command line arguments above to the Cordova CLI `build` or `run` commands.
 
-**Note**: You should use double `--` to indicate that these are platform-specific arguments, for example:
+**Note**: You should use double `--` to indicate that these are platform-specific arguments.
 
-`cordova run ios --release -- --codeSignIdentity="iPhone Developer" --developmentTeam=FG35JLLMXX4A --packageType=development`.
+**Example (Unix/macOS):**
+
+```bash
+cordova run ios --release -- --codeSignIdentity="iPhone Developer" --developmentTeam=FG35JLLMXX4A --packageType=development
+```
 
 ### Using build.json