[spec] Add spec for maui devtools by rmarinho · Pull Request #33865 · dotnet/maui

rmarinho · 2026-02-03T18:17:49Z

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!

MAUI Dev Tools Client -- Product Specification

This PR adds the product specification for maui -- a unified CLI tool for environment setup, device management, and AI agent integration across all MAUI platforms.

Problem

Setting up a MAUI development environment is one of the biggest friction points:

Fragmented native tools (sdkmanager, avdmanager, xcrun simctl, xcode-select) with different UX patterns
Silent failures that surface as cryptic MSBuild errors
No single "doctor" command like Flutter has
IDEs (VS and VS Code) independently implement detection/installation logic
AI agents have no structured API to query or fix environment state

Solution: `maui` CLI

A new CLI tool that provides environment health checks, automated fixes, and device management -- designed for three consumers in priority order: AI Agents > CI/CD > Humans.

Design Principles

Delegate to Native Toolchains -- Wraps sdkmanager, xcrun simctl, etc. No custom download/install logic
Reuse & Consolidate -- Leverages dotnet/android-tools for SDK/JDK discovery. Moves proven code from android-platform-support (internal) to the public android-tools package.
Stateless Architecture -- Each command reads state, acts, and exits
Machine-First Output -- Every command supports --json with stable schema; --dry-run, --ci for automation

Command Surface

Cross-Platform

Command	Description
`maui doctor`	Check environment health
`maui doctor --fix`	Auto-fix all detected issues
`maui doctor --platform <p>`	Filter by: dotnet, android, apple, windows
`maui device list`	List all devices (physical + emulators + simulators)
`maui device list --platform <p>`	Filter by platform
`maui device screenshot --device <id>`	Capture screenshot from device/simulator
`maui device logs --device <id>`	Stream logs from device
`maui --version`	Display version information

Android

Command	Description
`maui android install`	Set up full Android environment (JDK + SDK)
`maui android install --accept-licenses`	Non-interactive install
`maui android install --packages <list>`	Install specific packages
`maui android jdk check`	Check JDK installation status
`maui android jdk install`	Install OpenJDK (default: 17)
`maui android jdk list`	List installed JDK versions
`maui android sdk list`	List installed SDK packages
`maui android sdk list --available`	Show available packages
`maui android sdk install <packages>`	Install SDK package(s)
`maui android sdk accept-licenses`	Accept all SDK licenses
`maui android sdk uninstall <package>`	Uninstall SDK package
`maui android emulator list`	List emulators
`maui android emulator create <name>`	Create emulator
`maui android emulator start <name>`	Start emulator
`maui android emulator stop <name>`	Stop emulator
`maui android emulator delete <name>`	Delete emulator

Apple (macOS only)

Command	Description
`maui apple install`	Set up Apple development environment
`maui apple install --accept-licenses`	Also accept Xcode license
`maui apple install --runtime <version>`	Also install specific iOS runtime
`maui apple simulator list`	List simulators
`maui apple simulator create <name> <type> <runtime>`	Create simulator
`maui apple simulator start <id>`	Start simulator
`maui apple simulator stop <id>`	Stop simulator
`maui apple simulator delete <id>`	Delete simulator
`maui apple runtime check`	Check runtime installation status
`maui apple runtime list`	List installed runtimes
`maui apple runtime list --available`	List runtimes available for download
`maui apple runtime list --all`	List all runtimes (installed + available)
`maui apple runtime install <version>`	Install an iOS runtime
`maui apple xcode check`	Check Xcode installation and license status
`maui apple xcode list`	List Xcode installations
`maui apple xcode select <path>`	Switch active Xcode
`maui apple xcode accept-licenses`	Accept Xcode license agreement

Windows (Windows only)

Command	Description
`maui windows sdk list`	List Windows SDK installations
`maui windows developer-mode status`	Check Developer Mode status
`maui windows developer-mode enable`	Guide to enable Developer Mode

Global Options

All commands support: --json, --verbose, --ci, --dry-run

Key Features

One-command Android bootstrap: maui android install --accept-licenses installs JDK 17, Android SDK, and recommended packages
Apple environment setup: maui apple install --accept-licenses --runtime 18.5 verifies Xcode, accepts license, installs runtime
Structured error contract: Every error includes code, category, remediation type, and fix command -- designed for AI agent consumption
Unified permission model: OS elevation and AI agent permission gates documented per command
Copilot escalation: When auto-fix fails, structured diagnostic context is handed off to Copilot for AI-assisted troubleshooting

Goals

Goal	Metric
Reduce setup time	<10 min for 90% of users
Auto-fix rate	>80% of detected issues
API coverage	JSON output for all operations
Consolidate repos	Replace existing VS acquisition repos

Shared Libraries & Code Reuse

DevTools reuses existing Android tooling rather than building from scratch:

Library	Source	What We Reuse
`Xamarin.Android.Tools.AndroidSdk`	`dotnet/android-tools` (public NuGet)	SDK/JDK path discovery, validation, version mapping

Contributing to `dotnet/android-tools`

As part of this work, we are moving proven implementations from android-platform-support (internal) into the public dotnet/android-tools package. This benefits both the maui CLI and the broader .NET Android toolchain -- any tool or IDE that references Xamarin.Android.Tools.AndroidSdk gets these capabilities for free.

Feature	android-tools Issue	Description
Manifest feed parsing	#273	Parse Xamarin/Google manifests for download URLs and SHA-1 checksums
JDK installation	#270	Download, verify, and extract Microsoft OpenJDK
SDK bootstrap & management	#271	Bootstrap command-line tools, wrap `sdkmanager` for package operations
License acceptance	#272	Programmatic SDK license acceptance for CI/unattended scenarios

No hardcoded download URLs -- all SDK/JDK URLs and SHA-1 checksums come from the Xamarin Android Manifest Feed and Google's repository. Every download is checksum-verified before installation.

Spec Documents

Document	Description
`maui-devtools-spec.md`	Main specification (architecture, commands, schemas, error contract)
`maui-devtools-ide-integration.md`	VS Code and Visual Studio UI flows, status panels, fix dialogs

MVP Status

Most P0 features are implemented. VS Code extension integration is in progress. See Section 10 of the main spec for the full MVP vs vNext breakdown.

Copilot

Copilot wasn't able to review any files in this pull request.

rmarinho · 2026-02-04T17:05:59Z

@copilot why can t you review these files?

Copilot · 2026-02-04T17:06:08Z

@rmarinho I've opened a new pull request, #33893, to work on those changes. Once the pull request is ready, I'll request review from you.

- Add MauiDevice JSON schema with all fields (platforms[], idiom, runtime_identifiers, etc.) - Add SdkPackage JSON schema with is_installed flag - Update sdk list command: --available and --all flags (replaces list-available) - Update avd commands: stop, delete; --package optional with auto-detection - Update bootstrap: --packages flag for comma-separated package list - Add progress reporting documentation with JSON format - Add shell quoting implementation notes for semicolon handling - Update jdk commands: check, list (consistent naming) - Bump version to 2.7-draft

## Summary Syncs the DevTools spec with the current CLI implementation on `maui-client-tool` branch. ### What changed **New commands documented:** - `apple xcode list` — List installed Xcode versions with version, build number, selected status - `apple xcode select <path>` — Switch active Xcode installation - `android sdk accept-licenses` — Accept SDK licenses - `android avd stop/delete` — Stop and delete AVDs - `android bootstrap/jdk` commands in capabilities model **Schema updates:** - `MauiDevice`: Added `type`, `state`, `details` fields - `MauiDevice`: Documented Android-specific field semantics (identifier = AVD name for emulators, version = API level, version_name = OS version without prefix, platform_architecture = raw ABI) - New `XcodeInstallation` schema (path, developer_dir, version, build, is_selected) **Spec corrections to match implementation:** - `doctor --platform` → `doctor --category` (matching actual CLI flag) - Simulator boot/shutdown/delete use positional `<udid>` not `--udid` option - Global options: marked `--non-interactive`, `--correlation-id`, `--offline` as vNext (not yet implemented) - FR-X13/X14: Updated from vague 'handle multiple Xcode versions' to specific `xcode list`/`xcode select` commands (P0) **MVP tracking:** - Added status column to MVP table showing which features are implemented - Moved `deploy`, `config`, `diagnostic-bundle`, `telemetry` to vNext (not yet implemented) Version bumped to 2.8-draft.