From 6dcbc57c454b5d6c8a845be43880ab45ed66bd1c Mon Sep 17 00:00:00 2001
From: Cameron Cooke <web@cameroncooke.com>
Date: Thu, 7 May 2026 21:21:33 +0100
Subject: [PATCH] docs: Document launchArgs usage

Document launchArgs as the canonical launch-argument input for
build-and-run and launch-only tools. Clarify that extraArgs remains scoped
to xcodebuild and build settings.

Co-Authored-By: Codex <noreply@openai.com>
---
 app/docs/_content/cli.mdx   | 42 +++++++++++++++++++++++++++++++++++++
 app/docs/_content/tools.mdx | 22 ++++++++++++++++++-
 2 files changed, 63 insertions(+), 1 deletion(-)

diff --git a/app/docs/_content/cli.mdx b/app/docs/_content/cli.mdx
index 9e252fa..0559e98 100644
--- a/app/docs/_content/cli.mdx
+++ b/app/docs/_content/cli.mdx
@@ -93,6 +93,48 @@ xcodebuildmcp simulator build-and-run \
   --project-path ./MyApp.xcodeproj
 ```
 
+Pass launch arguments with `launchArgs` on build-and-run tools (`simulator build-and-run`, `device build-and-run`, `macos build-and-run`) and launch-only tools (`simulator launch-app`, `device launch`, `macos launch`). Keep `extraArgs` for `xcodebuild` flags and build settings overrides; those values are not passed to the app process.
+
+```shell
+xcodebuildmcp simulator build-and-run --json '{
+  "scheme": "MyApp",
+  "projectPath": "./MyApp.xcodeproj",
+  "simulatorName": "iPhone 17 Pro",
+  "launchArgs": ["--mock-weather-api"]
+}'
+```
+
+### Build and run on a physical device with runtime args
+
+```shell
+xcodebuildmcp device build-and-run --json '{
+  "scheme": "MyApp",
+  "projectPath": "./MyApp.xcodeproj",
+  "deviceId": "<DEVICE_UDID>",
+  "launchArgs": ["--uitesting"]
+}'
+```
+
+### Build and run on macOS with runtime args
+
+```shell
+xcodebuildmcp macos build-and-run --json '{
+  "scheme": "MyApp",
+  "projectPath": "./MyApp.xcodeproj",
+  "launchArgs": ["--uitesting"]
+}'
+```
+
+### Launch an installed simulator app with runtime args
+
+```shell
+xcodebuildmcp simulator launch-app --json '{
+  "simulatorId": "<SIMULATOR_UDID>",
+  "bundleId": "com.example.MyApp",
+  "launchArgs": ["--uitesting"]
+}'
+```
+
 ### Run XCTests with pre-resolved test cases and live progress
 
 ```shell
diff --git a/app/docs/_content/tools.mdx b/app/docs/_content/tools.mdx
index e322a47..9224fd6 100644
--- a/app/docs/_content/tools.mdx
+++ b/app/docs/_content/tools.mdx
@@ -16,6 +16,8 @@ import { ToolExplorer } from "../_components/tool-explorer"
 
 The one-shot tool your agent will reach for most. Builds the scheme, installs the resulting `.app` on a booted simulator, and launches it, with logs captured to a file.
 
+`launchArgs` is also supported on the other build-and-run tools (`build_run_device` and `build_run_macos`) and launch-only tools (`launch_app_sim`, `launch_app_device`, `launch_mac_app`) with the same contract: launch args go only to runtime launch steps, while `extraArgs` stays build/build-settings only.
+
 <div className="params">
   <div className="param">
     <div>
@@ -41,7 +43,7 @@ The one-shot tool your agent will reach for most. Builds the scheme, installs th
       <div className="param-type">string</div>
     </div>
     <div className="param-desc">
-      Absolute or relative path to <code>.xcworkspace</code>. Takes precedence over <code>projectPath</code> if both are set.
+      Absolute or relative path to <code>.xcworkspace</code>. Mutually exclusive with <code>projectPath</code>. Optional when set in session defaults.
     </div>
   </div>
   <div className="param">
@@ -71,6 +73,24 @@ The one-shot tool your agent will reach for most. Builds the scheme, installs th
       Build configuration. <span className="default">Default: <code>Debug</code></span>
     </div>
   </div>
+  <div className="param">
+    <div>
+      <div className="param-name">extraArgs</div>
+      <div className="param-type">string[]</div>
+    </div>
+    <div className="param-desc">
+      Additional <code>xcodebuild</code> and build-settings arguments. Use this for build-system flags, not app launch arguments.
+    </div>
+  </div>
+  <div className="param">
+    <div>
+      <div className="param-name">launchArgs</div>
+      <div className="param-type">string[]</div>
+    </div>
+    <div className="param-desc">
+      Arguments passed to the launched app process. Use this for runtime flags that appear in <code>ProcessInfo.processInfo.arguments</code>.
+    </div>
+  </div>
 </div>
 
 ## Naming conventions