Add Apple platform management CLI documentation

docs/TOC.yml

@@ -1332,6 +1332,8 @@
               href: developer-tools/cli/environment-diagnostics.md
             - name: Android SDK & emulator management
               href: developer-tools/cli/android-management.md
+            - name: Apple platform management
+              href: developer-tools/cli/apple-management.md
             - name: Device management
               href: developer-tools/cli/device-management.md
         - name: DevFlow

docs/developer-tools/cli/apple-management.md

@@ -0,0 +1,135 @@
+---
+title: "Apple platform management"
+description: "Learn how to use the .NET MAUI CLI to manage Xcode installations, simulator runtimes, and iOS simulators for .NET MAUI development."
+ms.date: 04/13/2026
+---
+
+# Apple platform management
+
+The .NET MAUI CLI provides commands for managing Apple development tools, including Xcode installations, simulator runtimes, and iOS simulators. These commands are available on macOS only.
+
+> [!IMPORTANT]
+> The .NET MAUI CLI is experimental and will change between releases.
+
+## Xcode management
+
+### List installed Xcode versions
+
+Use the `maui apple xcode list` command to discover all Xcode installations on your machine:
+
+```dotnetcli
+maui apple xcode list
+```
+
+The output includes the version, build number, path, and whether each installation is the currently selected Xcode:
+
+```
+Version | Build    | Path                          | Selected
+--------+----------+-------------------------------+---------
+26.4    | 17E192   | /Applications/Xcode.app       | ✓
+26.3    | 17D61a   | /Applications/Xcode-26.3.app  |
+```
+
+## Runtime management
+
+### List simulator runtimes
+
+Use the `maui apple runtime list` command to see the installed simulator runtimes:
+
+```dotnetcli
+maui apple runtime list
+```
+
+Filter by platform with the `--platform` option:
+
+```dotnetcli
+maui apple runtime list --platform iOS
+```
+
+The `--platform` option accepts `iOS`, `tvOS`, `watchOS`, and `visionOS`.
+
+The output shows each runtime's name, platform, version, availability, and whether it's bundled with Xcode:
+
+```
+Name                | Platform | Version | Available | Bundled
+--------------------+----------+---------+-----------+--------
+iOS 26.4            | iOS      | 26.4    | ✓         | Yes
+iOS 26.0            | iOS      | 26.0    | ✓         | No
+watchOS 26.4        | watchOS  | 26.4    | ✓         | Yes
+```
+
+## Simulator management
+
+The .NET MAUI CLI provides commands to list, start, stop, and delete iOS simulators.
+
+### List simulators
+
+```dotnetcli
+maui apple simulator list
+```
+
+The output shows each simulator's name, UDID, OS version, state, and availability:
+
+```
+Name                  | UDID                                 | OS        | State    | Available
+----------------------+--------------------------------------+-----------+----------+----------
+iPhone 17 Pro         | A1B2C3D4-E5F6-7890-ABCD-EF1234567890 | iOS 26.4  | Shutdown | ✓
+iPad Air (M4)         | B2C3D4E5-F6A7-8901-BCDE-F12345678901 | iOS 26.4  | Booted   | ✓
+```
+
+### Start a simulator
+
+Boot a simulator by name or UDID:
+
+```dotnetcli
+maui apple simulator start "iPhone 17 Pro"
+```
+
+```dotnetcli
+maui apple simulator start A1B2C3D4-E5F6-7890-ABCD-EF1234567890
+```
+
+The simulator launches in the background so you can continue using the terminal.
+
+### Stop a simulator
+
+Shut down a running simulator by name or UDID:
+
+```dotnetcli
+maui apple simulator stop "iPhone 17 Pro"
+```
+
+To stop all running simulators:
+
+```dotnetcli
+maui apple simulator stop all
+```
+
+### Delete a simulator
+
+Permanently remove a simulator and its associated data:
+
+```dotnetcli
+maui apple simulator delete "iPhone 17 Pro"
+```
+
+## Use in CI pipelines
+
+In automated environments, combine Apple commands with the `--json` and `--ci` flags for non-interactive, machine-readable output:
+
+```dotnetcli
+maui apple simulator list --json --ci
+maui apple xcode list --json --ci
+```
+
+Use `--json` when you need to parse command output programmatically:
+
+```dotnetcli
+maui apple simulator list --json | jq '.[] | select(.isBooted == true)'
+```
+
+## See also
+
+- [.NET MAUI CLI overview](index.md)
+- [Environment diagnostics](environment-diagnostics.md)
+- [Device management](device-management.md)

docs/developer-tools/cli/device-management.md

@@ -23,7 +23,7 @@ The output includes:
 
 - Physical Android devices connected via USB or Wi-Fi.
 - Running Android emulators.
-- iOS simulators (macOS).
+- Apple simulators, including booted and available devices (macOS).
 - Connected iOS devices (macOS).
 
 Each entry shows the device name, platform, identifier, and connection status.

docs/developer-tools/cli/environment-diagnostics.md

@@ -25,6 +25,7 @@ The command checks for the following components and their configurations:
 - Android SDK packages and platform tools
 - Java Development Kit (JDK) version and configuration
 - Xcode version and command-line tools (macOS)
+- Apple simulator runtimes and availability (macOS)
 - Visual Studio installation and required components
 - Environment variables and path configuration
 

docs/developer-tools/cli/index.md

@@ -56,6 +56,12 @@ The following table lists the available `maui` CLI commands:
 | `maui android emulator start` | Start an Android emulator |
 | `maui android emulator stop` | Stop a running emulator |
 | `maui android emulator delete` | Delete an emulator |
+| `maui apple xcode list` | List installed Xcode versions (macOS) |
+| `maui apple runtime list` | List simulator runtimes (macOS) |
+| `maui apple simulator list` | List simulator devices (macOS) |
+| `maui apple simulator start` | Boot a simulator (macOS) |
+| `maui apple simulator stop` | Shut down a simulator (macOS) |
+| `maui apple simulator delete` | Delete a simulator (macOS) |
 | `maui devflow` | DevFlow app automation and debugging |
 | `maui devflow MAUI tree` | Dump the visual tree of a running MAUI app |
 | `maui devflow MAUI screenshot` | Take a screenshot of a running MAUI app |
@@ -67,6 +73,7 @@ For more information, see:
 
 - [Environment diagnostics](environment-diagnostics.md)
 - [Android SDK & emulator management](android-management.md)
+- [Apple platform management](apple-management.md)
 - [Device management](device-management.md)
 - [DevFlow overview](../devflow/index.md)
 
@@ -107,5 +114,6 @@ maui doctor --json
 
 - [Environment diagnostics](environment-diagnostics.md)
 - [Android SDK & emulator management](android-management.md)
+- [Apple platform management](apple-management.md)
 - [Device management](device-management.md)
 - [DevFlow overview](../devflow/index.md)