flet debug: the new CLI for testing Flet apps on mobile devices

[FeodorFitsner]

Fix #4822

What's new

This PR adds three new CLI commands:

• flet debug - to run Flet app on a device or emulator.
• flet devices - to list connected devices.
• flet emulators - to list iOS/Android emulators and manage Android emulators.

How to use

Run this command to list all connected iOS/Android devices and emulators:

flet devices

If you see empty list make sure emulator is running or device connected.

Copy device ID you'd like to run your app on.

Run the following command to build Flet app and run on your device:

flet debug <ios|android> --device-id <device_id> --template-ref 0.70.0 -v

Testing on Android emulator

To list available iOS and Android emulators run this command:

flet emulators

This command requires Android SDK - you will be asked to install/update it.

To create a new Android emulator run:

flet emulators create my-emulator

To start an emulator:

flet emulators start my-emulator

Testing on iOS/iPadOS emulator

To create a new iOS/iPadOS simulator:

List simulator models:

xcrun simctl list devicetypes

List available runtimes:

xcrun simctl list runtimes

Create simulator:

xcrun simctl create "<Name>" "<Device Type>" "<Runtime>"

For example:

xcrun simctl create "My iPhone 17 Pro" "iPhone 17 Pro" com.apple.CoreSimulator.SimRuntime.iOS-26-1

Start Apple Simulator with:

open -a Simulator

Open "File -> Open Simulator -> .

Run this command to get simulator device ID:

flet devices

Testing on a real iPhone/iPad device

• Enable developer mode on your device.
• Connect the device with USB cable. You can use debug via Wi-Fi, but it's significantly slower than via cable.
• Open XCode, go to "Window -> Devices and Simulators". Wait until "device support files" are copied - it could take a few minutes.

When you connect an iOS device and open Xcode, it automatically downloads “device support” and symbol files from the iPhone. These files allow Xcode (and Flutter) to understand the exact iOS version on the device and provide fast, reliable debugging. Without them, Xcode can’t map system libraries correctly, which leads to slow startup, missing breakpoints, or warnings like “LLDB could not find the on-disk shared cache.” This setup happens only once per iOS version and is required for running or debugging apps on a physical device.

• Create a new provisioning profile that includes your device ID and developer certificate.
• Configure app bundle ID and "debugging" profile in pyproject.toml:

[tool.flet.ios]
bundle_id = "com.your-company.app"

[tool.flet.ios.export_methods."debugging"]
provisioning_profile = "Development com.your-company.app"

[sourcery-ai]

Sorry @FeodorFitsner, your pull request is larger than the review limit of 150000 diff characters

[Muddassir-Farooq-official]

@FeodorFitsner @InesaFitsner

The previous flet run --android/--ios workflow relied on the Flet mobile testing app, which limited the ability to test native functionalities like push notifications, permission handling (e.g., location, camera), and third-party native SDKs without first building a full APK/IPA.

​Does the new flet debug command resolve this? Does it allow us to fully test these native features in the emulator or on a device like flutter without performing a final release build (APK/IPA) every time?"

[FeodorFitsner]

Yes, flet debug allows running on emulator or a real device without making IPA/APK package and manually uploading it to a device.

"Flet" app will stay there too and allows quick experience your app on a mobile device, but with limited capabilities (not all permissions are enabled and the app itself is running on your computer).

[Muddassir-Farooq-official]

@FeodorFitsner any chance of stable release on v1 in December 2025

[FeodorFitsner]

Absolutely! We are going to release a stable Flet v1 Beta before Xmas.

[Muddassir-Farooq-official]

Absolutely! We are going to release a stable Flet v1 Beta before Xmas.

Thanks, a special request before launching stable v1 kindly improve app initial loading times when first UI screen appears or give a option to place any icon there.... And on windows hot reload sometime crashes and application stuck and need to restart kindly resolve these issue too...

[cloudflare-workers-and-pages]

Deploying flet-docs with    Cloudflare Pages

Latest commit:	34ac8ae
Status:	✅  Deploy successful!
Preview URL:	https://e795168e.flet-docs.pages.dev
Branch Preview URL:	https://flet-debug.flet-docs.pages.dev

View logs

[Copilot]

Pull request overview

This PR introduces three new CLI commands for testing Flet apps on mobile devices and emulators:

• flet debug - runs Flet apps on specified devices/emulators
• flet devices - lists connected iOS/Android devices
• flet emulators - manages iOS/Android emulators

Key changes include:

• Major code refactoring: extracting common functionality from build.py into new base classes (BaseFlutterCommand and BaseBuildCommand)
• Adding Android SDK AVD management capabilities
• Updating Flutter version from 3.38.2 to 3.38.3
• Adding documentation for new commands

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
commands/flutter_base.py	New base class for Flutter commands with common initialization logic
commands/build_base.py	New base class for build-related commands, extracted from build.py
commands/build.py	Refactored to extend BaseBuildCommand, significantly reduced code
commands/debug.py	New command for running apps on devices in debug mode
commands/devices.py	New command for listing connected devices
commands/emulators.py	New command for managing emulators
commands/publish.py	Added type=str.lower for argument normalization
commands/create.py	Added type=str.lower for argument normalization, unused variable fix
utils/android_sdk.py	Added AVD management methods
utils/flutter.py	Extracted get_flutter_dir() function
cli.py	Registered new commands
docs/	Added documentation files for new commands
.fvmrc	Updated Flutter version to 3.38.3

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.