[spec] Add `maui device list` command spec to CLI design doc by rmarinho · Pull Request #34277 · dotnet/maui

rmarinho · 2026-02-27T10:49:43Z

Note

Are you waiting for the changes in this PR to be merged?
It would be very helpful if you could test the resulting artifacts from this PR and let us know in a comment if this change resolves your issue. Thank you!

Summary

Adds the maui device list command specification to the existing CLI design document (docs/design/cli.md). This command provides unified, cross-platform device enumeration without requiring a project context.

See PR #33865 for the full DevTools spec.

What is added

Command: `maui device list [--platform <p>] [--json]`

Lists connected devices, running emulators, and available simulators across all platforms in a single call.

Two approaches analysis

The spec analyzes two discovery approaches and recommends the project-free one:

	MSBuild (`dotnet run --list-devices`)	Native CLI (`maui device list`)
Project required	Yes	No
Cross-platform	One TFM at a time	All platforms at once
Speed	Slower (MSBuild eval)	Fast (<2s)
ID compatibility	Source of truth	Same native IDs

Scenarios requiring project-free discovery

AI agent bootstrapping (no .csproj yet)
IDE startup (device picker before project loads)
Environment validation ("can I see my phone?")
CI pipeline setup (check emulator before build)
Multi-project solutions (unified view)
Cross-platform overview (all devices at once)

Recommended approach

maui device list uses direct native tool invocation (adb devices, simctl list, devicectl list). Device IDs are compatible with dotnet run --device, making them complementary:

maui device list          →  "What devices exist on this machine?"
dotnet run --list-devices →  "What devices can run this project?"

Other changes

Added references to ComputeAvailableDevices MSBuild targets in dotnet/android and dotnet/macios
Updated AI agent workflow example to include device discovery step
Fixed AppleDev.Tools reference (xcdevice → devicectl)

github-actions · 2026-02-27T10:49:52Z

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/dotnet/maui/main/eng/scripts/get-maui-pr.sh | bash -s -- 34277

Or

Run remotely in PowerShell:

iex "& { $(irm https://raw.githubusercontent.com/dotnet/maui/main/eng/scripts/get-maui-pr.ps1) } 34277"

Add 'maui device list' command specification to the CLI design doc, including: - Command syntax with --platform and --json options - Human-readable and JSON output schemas - Analysis of two discovery approaches (MSBuild vs native CLI) - Comparison table of pros/cons - Six real-world scenarios requiring project-free device enumeration - Recommended approach (direct native tool invocation) - Relationship to dotnet run --list-devices (complementary) - References to ComputeAvailableDevices targets in dotnet/android and dotnet/macios Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

rolfbjarne · 2026-02-27T13:45:40Z

docs/design/cli.md

 - [simctl command-line tool](https://nshipster.com/simctl/)

 [vibe-wpf]: https://github.com/jonathanpeppers/vibe-wpf
 [appledev-tools]: https://github.com/Redth/AppleDev.Tools


Xamarin.MacDev?

jonathanpeppers · 2026-02-27T14:29:59Z

docs/design/cli.md

+| | Approach A (MSBuild) | Approach B (Native CLI) |
+|---|---|---|
+| **Project required** | Yes — needs `.csproj` | No |
+| **Cross-platform** | One platform per call (per TFM) | All platforms in one call |


Why would you need to list all the platforms in one call? This will be really slow.

vscode does that

jonathanpeppers · 2026-02-27T14:30:41Z

docs/design/cli.md

+1. **AI agent bootstrapping** — An agent starting a "vibe coding"
+   session needs to discover available targets before scaffolding a
+   project. It cannot call `dotnet run --list-devices` because there
+   is no `.csproj` yet.


I don't understand, why does it need to know the devices before a project exists?

What is it going to do with the list of devices?

you can see this AI usage, AI wants to see if device exists before creating it for example, or know figure what it can launch.

You can see this on CI, check if the device exists before creating one

Can you share a screenshot/example?

you can look at maui ci for example ,we list first the devices to understand if we need to create a emulator to then pass to appium script

But you have the repo cloned and have a project?

In the future, you should dotnet test a project and xharness will be deprecated?

Far point on xharness, dotnet test is definitely the future there 👍

The main scenarios I keep coming back to are the ones where there truly is no project:
VS Code extension startup it does tis right now no .csproj to evaluate. I have this working today in vscode-maui, it calls maui device list --json on activation.
Environment diagnostics — "can my Mac see my iPhone?" is a diagnostic question, not a build question. Requiring a project for that feels like needing a .csproj to run adb devices 😄
AI agent cold start — agent in an empty directory asked to "build me an iOS app" needs to know if a simulator exists before it even scaffolds the project.
I think you do have a good point, but since this is shared with dotnet run via the android-tools whats the diff of having a wrapper here?

@jonathanpeppers so you fine to merge this ? We can then in future maybe do a little better? if needed. We most have this merge already on android-tools so is just a case of the client tool use it.

Also we would need to update the client spec in the future as seems screenshot for example is now on MauiDevFlow on the maui labs repository

I would focus on getting the first command -- and making the CLI actually exist before merging this.

Merging now the cli exist on maui-labs

jonathanpeppers · 2026-02-27T14:31:13Z

docs/design/cli.md

+| **Project required** | Yes — needs `.csproj` | No |
+| **Cross-platform** | One platform per call (per TFM) | All platforms in one call |
+| **Metadata** | Rich (RuntimeIdentifier, workload-specific fields) | Standard (id, description, type, status) |
+| **Speed** | Slower (MSBuild evaluation + restore) | Fast (<2s, direct process calls) |


I doubt listing devices for all platforms will beat 2 seconds, do we have a measurement?

I have a working version now on vscode it s what it looks like :) I can try give you a exact number

Copilot AI review requested due to automatic review settings February 27, 2026 10:49

Copilot started reviewing on behalf of rmarinho February 27, 2026 10:50 View session

This comment was marked as outdated.

Sign in to view

rmarinho changed the title ~~docs: Add maui device list command spec to CLI design doc~~ [spec] Add maui device list command spec to CLI design doc Feb 27, 2026

rmarinho force-pushed the docs/maui-device-list branch from 94cab3a to 805c3bc Compare February 27, 2026 13:33

rmarinho force-pushed the docs/maui-device-list branch from 805c3bc to 5c20b77 Compare February 27, 2026 13:34

rmarinho requested a review from Copilot February 27, 2026 13:37

Copilot started reviewing on behalf of rmarinho February 27, 2026 13:38 View session

rolfbjarne self-requested a review February 27, 2026 13:39

Copilot AI reviewed Feb 27, 2026

View reviewed changes

rolfbjarne approved these changes Feb 27, 2026

View reviewed changes

rmarinho requested a review from jonathanpeppers February 27, 2026 14:18

jonathanpeppers reviewed Feb 27, 2026

View reviewed changes

This was referenced Mar 1, 2026

[repo-status] Daily Status Report - March 1, 2026 #34289

Closed

[repo-status] Daily Status Report - March 2, 2026 #34290

Closed

rmarinho mentioned this pull request Mar 16, 2026

Add Microsoft.Maui.Client tool for cross-platform device and SDK management #34498

Closed

MauiBot added s/agent-changes-requested AI agent recommends changes - found a better alternative or issues s/agent-fix-win AI found a better alternative fix than the PR s/agent-reviewed PR was reviewed by AI agent workflow (full 4-phase review) labels Mar 23, 2026

dotnet deleted a comment from MauiBot Mar 23, 2026

kubaflo removed s/agent-reviewed PR was reviewed by AI agent workflow (full 4-phase review) s/agent-changes-requested AI agent recommends changes - found a better alternative or issues s/agent-fix-win AI found a better alternative fix than the PR labels Mar 23, 2026

rmarinho merged commit 59b36c2 into main Apr 2, 2026
24 of 25 checks passed

rmarinho deleted the docs/maui-device-list branch April 2, 2026 11:24

This was referenced Apr 3, 2026

[repo-status] 📊 Daily Repo Status - April 3, 2026 #34795

Closed

[repo-status] 📊 Daily Repo Status - April 4, 2026 #34809

Closed

Conversation

rmarinho commented Feb 27, 2026

Summary

What is added

Command: maui device list [--platform <p>] [--json]

Two approaches analysis

Scenarios requiring project-free discovery

Recommended approach

Other changes

Uh oh!

github-actions bot commented Feb 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as outdated.

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

Command: `maui device list [--platform <p>] [--json]`

github-actions bot commented Feb 27, 2026 •

edited

Loading