From 14ba86af6eb20a7e22417a090f4d695619c64296 Mon Sep 17 00:00:00 2001 From: Gerald Versluis Date: Mon, 13 Apr 2026 13:06:44 +0200 Subject: [PATCH 1/2] Add Apple platform management CLI documentation New page documenting maui apple commands added in dotnet/maui-labs#56: - maui apple xcode list - maui apple runtime list [--platform] - maui apple simulator list/start/stop/delete Also updates: - CLI index: add Apple commands to command reference table - Environment diagnostics: mention Apple health checks - Device management: mention Apple simulators - TOC: add Apple platform management entry Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/TOC.yml | 2 + docs/developer-tools/cli/apple-management.md | 135 ++++++++++++++++++ docs/developer-tools/cli/device-management.md | 2 +- .../cli/environment-diagnostics.md | 1 + docs/developer-tools/cli/index.md | 8 ++ 5 files changed, 147 insertions(+), 1 deletion(-) create mode 100644 docs/developer-tools/cli/apple-management.md diff --git a/docs/TOC.yml b/docs/TOC.yml index b4a4b481f3..f8781ebf12 100644 --- a/docs/TOC.yml +++ b/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 diff --git a/docs/developer-tools/cli/apple-management.md b/docs/developer-tools/cli/apple-management.md new file mode 100644 index 0000000000..f323f4fe8d --- /dev/null +++ b/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 +--------+---------+-------------------------------+--------- +16.2 | 16C5032a| /Applications/Xcode.app | ✓ +15.4 | 15F31d | /Applications/Xcode-15.4.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 18.2 | iOS | 18.2 | ✓ | Yes +iOS 17.5 | iOS | 17.5 | ✓ | No +watchOS 11.2 | watchOS | 11.2 | ✓ | 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 16 Pro | A1B2C3D4-E5F6-7890-ABCD-EF1234567890 | iOS 18.2 | Shutdown | ✓ +iPad Air (M2) | B2C3D4E5-F6A7-8901-BCDE-F12345678901 | iOS 18.2 | Booted | ✓ +``` + +### Start a simulator + +Boot a simulator by name or UDID: + +```dotnetcli +maui apple simulator start "iPhone 16 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 16 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 16 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) diff --git a/docs/developer-tools/cli/device-management.md b/docs/developer-tools/cli/device-management.md index 94d0d29a10..8c21e34fdc 100644 --- a/docs/developer-tools/cli/device-management.md +++ b/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. diff --git a/docs/developer-tools/cli/environment-diagnostics.md b/docs/developer-tools/cli/environment-diagnostics.md index 7d73c7247d..642f13bfdb 100644 --- a/docs/developer-tools/cli/environment-diagnostics.md +++ b/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 diff --git a/docs/developer-tools/cli/index.md b/docs/developer-tools/cli/index.md index 6d518cd570..5bc448871a 100644 --- a/docs/developer-tools/cli/index.md +++ b/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) From 1015a68672d267236f013788040c6aad9c0d8b43 Mon Sep 17 00:00:00 2001 From: Gerald Versluis Date: Mon, 13 Apr 2026 13:35:25 +0200 Subject: [PATCH 2/2] Update example versions to latest Apple products Use Xcode 26.4, iOS 26.4, iPhone 17 Pro, iPad Air (M4), watchOS 26.4 in example output. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/developer-tools/cli/apple-management.md | 28 ++++++++++---------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/developer-tools/cli/apple-management.md b/docs/developer-tools/cli/apple-management.md index f323f4fe8d..cf248cf8f2 100644 --- a/docs/developer-tools/cli/apple-management.md +++ b/docs/developer-tools/cli/apple-management.md @@ -24,10 +24,10 @@ 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 ---------+---------+-------------------------------+--------- -16.2 | 16C5032a| /Applications/Xcode.app | ✓ -15.4 | 15F31d | /Applications/Xcode-15.4.app | +Version | Build | Path | Selected +--------+----------+-------------------------------+--------- +26.4 | 17E192 | /Applications/Xcode.app | ✓ +26.3 | 17D61a | /Applications/Xcode-26.3.app | ``` ## Runtime management @@ -53,9 +53,9 @@ The output shows each runtime's name, platform, version, availability, and wheth ``` Name | Platform | Version | Available | Bundled --------------------+----------+---------+-----------+-------- -iOS 18.2 | iOS | 18.2 | ✓ | Yes -iOS 17.5 | iOS | 17.5 | ✓ | No -watchOS 11.2 | watchOS | 11.2 | ✓ | Yes +iOS 26.4 | iOS | 26.4 | ✓ | Yes +iOS 26.0 | iOS | 26.0 | ✓ | No +watchOS 26.4 | watchOS | 26.4 | ✓ | Yes ``` ## Simulator management @@ -71,10 +71,10 @@ maui apple simulator list The output shows each simulator's name, UDID, OS version, state, and availability: ``` -Name | UDID | OS | State | Available -----------------------+--------------------------------------+----------+----------+---------- -iPhone 16 Pro | A1B2C3D4-E5F6-7890-ABCD-EF1234567890 | iOS 18.2 | Shutdown | ✓ -iPad Air (M2) | B2C3D4E5-F6A7-8901-BCDE-F12345678901 | iOS 18.2 | Booted | ✓ +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 @@ -82,7 +82,7 @@ iPad Air (M2) | B2C3D4E5-F6A7-8901-BCDE-F12345678901 | iOS 18.2 | Booted Boot a simulator by name or UDID: ```dotnetcli -maui apple simulator start "iPhone 16 Pro" +maui apple simulator start "iPhone 17 Pro" ``` ```dotnetcli @@ -96,7 +96,7 @@ The simulator launches in the background so you can continue using the terminal. Shut down a running simulator by name or UDID: ```dotnetcli -maui apple simulator stop "iPhone 16 Pro" +maui apple simulator stop "iPhone 17 Pro" ``` To stop all running simulators: @@ -110,7 +110,7 @@ maui apple simulator stop all Permanently remove a simulator and its associated data: ```dotnetcli -maui apple simulator delete "iPhone 16 Pro" +maui apple simulator delete "iPhone 17 Pro" ``` ## Use in CI pipelines