Flutter Dev

flutter-dev is a cross-platform Python CLI toolkit for automating common Flutter development workflows. It exposes the fdev command for project setup, release builds, device utilities, Git automation, AI-generated commit messages, screen mirroring, Firebase web deployment, and small productivity tools around an existing Flutter project.

The package is published on PyPI as flutter-dev and installs console commands for day-to-day Flutter work:

python -m pip install flutter-dev

Current package metadata declares version 0.1.17, Python >=3.8, MIT license, and support for macOS, Linux, and Windows.

Key Features

• Flutter build automation for APK, split APK, AAB, IPA, macOS DMG, release install, and Firebase web deploy.
• Project maintenance helpers for flutter clean, dependency refresh, build_runner, localization generation, analysis, formatting, cache repair, and CocoaPods.
• Localization CSV helpers for exporting ARB files to translator-friendly CSV files and generating ARB files back from CSV.
• Android device helpers for APK install, app uninstall, project/foreground app data clearing, screen mirroring with scrcpy, wireless ADB setup, and Date & Time settings.
• Dynamic Firebase App Check debug-token discovery, registration, listing, and revocation for connected Android devices.
• AI-assisted Git commits using Groq, Mistral, SambaNova, or OpenRouter-compatible chat completion APIs.
• Git workflow helpers for version tags, branch sync, deployment branch merge, discard, and GitHub account management through gh.
• Feature/page generator that creates a lib/features/<name> structure using the project's presenter/base-state pattern.
• Environment diagnostics through fdev doctor.
• Small utilities for Homebrew cleanup, file merging from paths.txt, AI provider switching, PyPI self-upgrade/delete, and git diff prompt export.

Installation

Install From PyPI

python -m pip install flutter-dev

Verify the CLI is available:

fdev doctor

python -m pip install flutter-dev installs the Python package, Python dependencies, and console scripts into the Python environment selected by python. It does not install Flutter, Dart, Git, Android SDK tools, CocoaPods, Firebase CLI, GitHub CLI, scrcpy, Java/JDK, or VS Code CLI.

Install From Source

git clone https://github.com/royalcourtbd/flutter-development-tools.git
cd flutter-development-tools
python -m pip install .

For editable local development:

python -m pip install -e .

Legacy Installer

The repository still includes install_legacy.py for the older ~/scripts/flutter-tools and ~/bin style installation:

python install_legacy.py

For new PyPI-based installs, prefer the console scripts installed by pip.

Requirements

Core requirements checked by fdev doctor:

• Python 3.8 or newer
• Flutter SDK
• Dart SDK
• Git
• Python packages: python-dotenv, requests

Feature-specific external tools:

Tool	Used by
Android SDK Platform Tools / adb	install, uninstall, clear-data, wireless, mirror, datetime, release-run, app-check token/register
Java/JDK	Android builds
CocoaPods	pod, ipa
Xcode / xcrun	iOS simulator and IPA workflows on macOS
scrcpy	mirror
Firebase CLI	web-deploy; App Check management when version 15.25.1 or newer
Google Cloud CLI / gcloud	App Check REST fallback when a compatible Firebase CLI is unavailable
GitHub CLI / gh	fdev git ...
VS Code CLI / code	Conflict helper in branch sync
Homebrew	brew, macOS install-scrcpy flow

Quick Start

Run commands from the root of a Flutter project when they need pubspec.yaml, Android Gradle files, iOS files, or build outputs.

# Show command help
fdev

# Show command help
fdev help

# Upgrade the fdev CLI from PyPI
fdev upgrade

# Check environment and optional tools
fdev doctor

# Initialize persistent AI configuration
fdev init

# Generate localization files
fdev lang

# Export ARB translations from lib/l10n to translations.csv
fdev arb-to-csv

# Generate ARB files in lib/l10n from translations.csv
fdev csv-to-arb

# Run build_runner
fdev db

# Build a release APK
fdev apk

# Build and install a release APK on a connected Android device
fdev release-run

# Mirror an Android device
fdev mirror

# Generate an AI-assisted commit message and commit after confirmation
fdev commit

Command Reference

Build Commands

Command	Description
fdev apk	Runs clean, pub get, flutter gen-l10n, build_runner, then flutter build apk --release --obfuscate --target-platform android-arm64 --split-debug-info=./.
fdev apk-split	Builds release APKs with --split-per-abi.
fdev aab	Builds a release Android App Bundle with obfuscation and split debug info.
fdev ipa	Builds an App Store IPA on non-Windows systems; runs CocoaPods steps when ios/ exists.
fdev dmg	Builds a macOS release app, packages it with an Applications shortcut, verifies the compressed DMG, and prints its path, size, and SHA-256. macOS only.
fdev release-run	Builds a release APK, installs it on a selected Android device, and launches the app.
fdev web-deploy	Runs flutter build web --release, then firebase deploy --only functions,hosting.

Android APK/AAB build commands rename output files using the Android app label and current date (DD_MMM) when the label is available, display file sizes, and open the output directory.

macOS Release DMG

Run fdev dmg from your Flutter app root (containing pubspec.yaml and macos/Runner.xcodeproj). Flutter, Dart, Xcode, ditto, and hdiutil must be available. Localization and build_runner are optional; the command reads pubspec.yaml and skips generators that are not configured.

fdev dmg

It runs these steps in order, stopping at the first failure:

flutter clean
flutter pub get
flutter gen-l10n # only when localization generation is configured
dart run build_runner build --delete-conflicting-outputs # only when declared
flutter build macos --release

Localization runs when flutter.generate is true and either l10n.yaml or ARB files in lib/l10n/ exist. A custom ARB directory is supported through l10n.yaml. An explicit l10n.yaml without flutter.generate: true is reported as a configuration error before cleaning the project. build_runner runs only when declared in dependencies or dev_dependencies. Skipped steps show a reason; configured generators and required build/packaging steps still stop the process if they fail.

The command discovers the single .app in build/macos/Build/Products/Release/ and reads its built Info.plist for the display name (falling back to bundle name/app filename) and release version. It uses ditto to preserve the app bundle, adds an /Applications symlink in a temporary staging directory, creates a compressed image with hdiutil create -format UDZO, and checks it with hdiutil verify.

Verified images are saved as dist/<AppName>-<version>-macOS.dmg. Existing files are preserved using numeric suffixes (-1, -2, etc.). Temporary staging and incomplete images are cleaned up on failure or interruption. Success prints the image path, size, and SHA-256 and opens dist/. Failures return a nonzero CLI exit code. Multiple release app bundles cause an error rather than an arbitrary selection.

This command preserves the app's existing signing; it does not perform Developer ID signing, notarization, upload, or create a custom Finder icon layout. Release mode alone does not imply a notarized app suitable for public distribution.

Project Commands

Command	Description
fdev setup	Runs clean, dependency upgrade, build_runner, localization generation, another dependency upgrade, flutter analyze, and dart format ..
fdev cleanup	Runs clean, pub get, dart fix --apply, dart format ., and flutter pub upgrade --major-versions.
fdev lang	Runs flutter gen-l10n.
fdev arb-to-csv	Exports lib/l10n/*.arb into translations.csv by default. Use -d/--directory and -o/--output to override paths.
fdev csv-to-arb	Generates app_<locale>.arb files into lib/l10n from translations.csv by default. Use -i/--input and -o/--output-dir to override paths.
fdev db	Runs dart run build_runner build --delete-conflicting-outputs.
fdev cache-repair	Runs flutter pub cache repair.
fdev pod	Updates CocoaPods from the ios/ directory after removing Podfile.lock when present.
create-page page <page_name>	Generates a feature/page structure directly through the packaged console script.
fdev page <page_name>	Legacy wrapper that currently calls ~/scripts/flutter-tools/create_page.py; for PyPI installs, prefer create-page page <page_name>.

Device Commands

Command	Description
fdev install	Installs a built APK from build/app/outputs/flutter-apk, prefers arm64-v8a, retries after uninstall on failure, then launches the app.
fdev uninstall	In a Flutter project root, uninstalls by package/bundle id. Outside a project, detects the foreground app and asks for confirmation.
fdev clear-data	In a Flutter project root, clears the installed project's Android package data without confirmation; if it is missing or the clear fails, falls back to the foreground app with a default-Yes safety prompt. Outside a project, always detects and confirms the foreground app. iOS prints manual options.
fdev app-check status [--device SERIAL] [--backend auto|cli|rest]	Shows all ADB device states, dynamically resolved Firebase Android metadata, provider detection, and Firebase management backend readiness.
fdev app-check token [--device SERIAL]	Reads one debug build's UUID4 App Check token from its discovered preference store, with official logcat fallback, and explicitly prints the secret.
fdev app-check register [--device SERIAL | --all] [--backend auto|cli|rest]	Collects token(s) without printing or persisting them and registers one selected device or every authorized connected device.
fdev app-check list [--backend auto|cli|rest]	Lists registered debug-token names, resource IDs, and update times; Firebase never returns the secrets.
fdev app-check revoke <id> [--backend auto|cli|rest] [--force]	Revokes a registered debug token after confirmation. Use --force for non-interactive operation.
fdev install-scrcpy	Installs scrcpy using the best supported package manager for the current platform.
fdev mirror	Launches scrcpy for a selected Android device.
fdev wireless	Guides wireless ADB setup using a USB-connected Android device; does not start screen mirroring.
fdev mirror --no-top	Launches scrcpy without the always-on-top flag.
fdev mirror --turn-screen-off	Launches scrcpy while keeping the Android device display turned off.
fdev datetime	Disables Android auto-time and opens Date & Time settings on the selected device.

When multiple Android devices are connected, device-aware commands prompt you to choose a device.

Firebase App Check Debug Tokens

There are five App Check subcommands: status, token, register, list, and revoke.

Run App Check commands from a Flutter project root, or pass --project-root. The resolver matches the Android applicationId with the appropriate client in android/app/google-services.json. It also reads firebase.json and .firebaserc when needed. Flavor-specific google-services.json files are discovered under android/app; ambiguous configurations require an explicit override instead of silently choosing the first client.

# Inspect device states, Firebase metadata, providers, and backend readiness
fdev app-check status --backend auto

# Print one device's token (the output is a secret)
fdev app-check token --device DEVICE_SERIAL

# Collect and register without printing the token
fdev app-check register --device DEVICE_SERIAL --backend cli

# Register every authorized connected device
fdev app-check register --all --backend cli

# Inspect and revoke registered token metadata
fdev app-check list --backend cli
fdev app-check revoke DEBUG_TOKEN_ID --backend cli

The default --backend auto uses Firebase CLI 15.25.1+ when available, otherwise it uses the Firebase App Check REST API with the active gcloud account. Force either route with --backend cli or --backend rest. Authenticate the selected tool before registration:

firebase login
# or
gcloud auth login

Configuration precedence is command-line option, environment override, then project discovery. Supported overrides are:

--package                 FDEV_APP_CHECK_PACKAGE / PACKAGE_NAME
--project                 FDEV_FIREBASE_PROJECT_ID / FIREBASE_PROJECT_ID
--project-number          FDEV_FIREBASE_PROJECT_NUMBER / FIREBASE_PROJECT_NUMBER
--app-id                  FDEV_FIREBASE_APP_ID / FIREBASE_ANDROID_APP_ID
--quota-project           FDEV_GOOGLE_CLOUD_QUOTA_PROJECT / GOOGLE_CLOUD_QUOTA_PROJECT
--device                  ANDROID_SERIAL

register keeps the debug token in memory and never writes it to a project file. The token subcommand is the only normal workflow that prints the secret. If a stable display name already exists, pass --force only when replacing the old token is intended.

The REST backend charges API quota to --quota-project, the configured gcloud billing/quota_project, or the active gcloud project, in that order. That project must have the Firebase App Check API enabled, and the active account must be allowed to consume its service quota.

Git Commands

Command	Description
fdev commit	Generates a Conventional Commit-style message from git diff HEAD, asks for confirmation, stages unstaged changes with git add ., then commits.
fdev tag	Auto-increments the latest Git tag, updates pubspec.yaml version/build number, commits the version bump, creates the tag, and pushes the commit and tag.
fdev discard	Prompts, then discards tracked changes and removes untracked files using Git commands.
fdev sync <branch...>	Fetches, merges named branches into the current branch, pushes, then merges current branch back into those branches. Requires a clean worktree.
fdev deploy	Merges the current branch into deployment and pushes it. Requires a clean worktree.
fdev git	Opens an interactive GitHub account manager using the GitHub CLI.

fdev git subcommands:

fdev git status
fdev git list
fdev git switch <username>
fdev git add
fdev git remove <username>
fdev git config

Switching GitHub accounts runs gh auth switch and gh auth setup-git, but it does not automatically change git user.name or git user.email. Use fdev git config when you want to update Git identity.

Utility Commands

Command	Description
fdev	Shows command help.
fdev help	Shows command help.
fdev -v / fdev --version	Shows the version installed in the active fdev Python environment.
fdev doctor	Checks platform, Python, Flutter/Dart/Git, Python packages, Android/iOS tools, optional CLIs, .env, Flutter project detection, and global fdev availability.
fdev init	Creates or repairs the persistent AI .env with safe provider defaults and empty API keys.
fdev upgrade	Checks the latest PyPI version first. If already current, skips pip and prints one up-to-date notice; otherwise upgrades quietly and reports the previous and installed versions.
fdev delete	Detects the OS, asks for confirmation, then uninstalls the active Python environment's flutter-dev package. Use fdev delete --yes to skip confirmation.
fdev ai	Shows the current AI provider and opens an interactive provider switch prompt.
fdev ai <provider>	Switches DEFAULT_AI_SERVICE to groq, mistral, sambanova, or openrouter.
fdev ai <provider> <model>	Switches provider when needed and saves a custom model ID for that provider.
fdev brew	Interactive Homebrew package manager for viewing packages, uninstalling with cleanup, clearing cache, and global cleanup.
fdev merge	Reads paths from paths.txt, merges file contents into path_merge_files.txt, and opens the result when there are no failures.
gemini-api	Tests the currently selected AI provider configuration.
git-diff-editor	Writes git diff output plus a prompt into diff_output.txt and opens it with the default app.

AI Configuration

AI features are used by fdev commit and gemini-api. Despite the historical gemini_api.py filename, the current source supports these providers:

• groq
• mistral
• sambanova
• openrouter

Each provider expects an API key, API URL, and model name. A typical configuration looks like this:

GROQ_API_KEY=your_groq_api_key_here
GROQ_API_URL=https://api.groq.com/openai/v1/chat/completions
GROQ_MODEL=llama-3.3-70b-versatile

MISTRAL_API_KEY=your_mistral_api_key_here
MISTRAL_API_URL=https://api.mistral.ai/v1/chat/completions
MISTRAL_MODEL=mistral-medium-latest

SAMBANOVA_API_KEY=your_sambanova_api_key_here
SAMBANOVA_API_URL=https://api.sambanova.ai/v1/chat/completions
SAMBANOVA_MODEL=Meta-Llama-3.3-70B-Instruct

OPENROUTER_API_KEY=your_openrouter_api_key_here
OPENROUTER_API_URL=https://openrouter.ai/api/v1/chat/completions
OPENROUTER_MODEL=openai/gpt-3.5-turbo

DEFAULT_AI_SERVICE=groq

The AI runtime searches for configuration in this order:

1. FLUTTER_DEV_ENV
2. $XDG_CONFIG_HOME/flutter-dev/.env
3. %APPDATA%/flutter-dev/.env on Windows, otherwise ~/.config/flutter-dev/.env
4. The legacy ~/.config/flutter-dev/.env path on Windows
5. ~/scripts/flutter-tools/.env

Recommended setup:

fdev init

fdev init never writes real credentials. It creates all provider URL/model defaults with empty API-key fields, preserves existing values, and restricts the file to the current user on Unix-like systems. On macOS and Linux the default path is ~/.config/flutter-dev/.env.

Then select a provider and test:

fdev ai mistral
gemini-api

If the selected provider's key is missing, fdev commit or gemini-api asks for it using hidden terminal input and saves it to the active configuration. After a new key is entered, press Enter to use the displayed default model or enter another model ID for the same provider. Exported environment variables continue to take precedence over values stored in .env.

Pressing Ctrl+C during key/model setup cancels the operation without saving a partial key or sending an AI request. If an exported variable conflicts with a provider/model change, fdev reports the override and asks you to unset it instead of claiming that the file change became active.

Change the model later without replacing the API key:

fdev ai groq llama-3.1-8b-instant

fdev doctor, fdev ai, gemini-api, and fdev commit use the same persistent configuration lookup.

Feature/Page Generation

Use the packaged command:

create-page page user_profile

This reads the Flutter project name from pubspec.yaml, lowercases the page name, converts snake_case to PascalCase for class names, and creates:

lib/features/user_profile/
  data/
    datasource/
    models/
    repositories/user_profile_repository_impl.dart
  domain/
    datasource/
    entities/
    repositories/user_profile_repository.dart
    usecase/
  presentation/
    presenter/user_profile_presenter.dart
    presenter/user_profile_ui_state.dart
    ui/user_profile_page.dart
    widgets/
  di/user_profile_di.dart

The generated Dart pattern is based on:

• {Prefix}Repository
• {Prefix}RepositoryImpl
• {Prefix}Di
• {Prefix}Presenter extends BasePresenter<{Prefix}UiState>
• {Prefix}UiState extends BaseUiState
• a simple StatelessWidget page

If lib/core/di/service_locator.dart exists, the generator attempts to add the feature DI import and await {Prefix}Di.setup(_serviceLocator); near //Feature DI setup.

Important notes:

• The generator overwrites the generated target files if they already exist.
• service_locator.dart updates are regex-based and skipped when the file is missing.
• The source does not generate BLoC/Cubit templates; it generates the project's presenter/base-state pattern.

Architecture

The package is organized as a Python CLI with a thin dispatcher and feature-specific managers:

fdev.py                 Main command dispatcher
create_page.py          Flutter feature/page generator
gemini_api.py           AI commit-message provider client and config loader
git_diff_output_editor.py
common_utils.py         Shared colors, spinners, env helpers, platform helpers
core/constants.py       Shared regex patterns, paths, and build command constants
core/state.py           Selected Android device state
managers/build.py       APK/AAB/IPA/DMG/release-run build workflow
managers/project.py     setup, cleanup, lang, db, pod, cache repair
managers/app.py         install, uninstall, project/foreground app data clearing
managers/device.py      ADB device detection and selection
managers/mirror.py      scrcpy install, mirror, wireless ADB setup
managers/git.py         commit, tag, discard, branch sync, deployment merge
managers/git_account.py GitHub account manager around gh CLI
managers/doctor.py      Environment diagnostics
managers/package.py     PyPI self-upgrade and local uninstall commands
managers/ai.py          AI provider status and switching
managers/brew.py        Interactive Homebrew manager
managers/merge.py       paths.txt to path_merge_files.txt merger
managers/web_deploy.py  Flutter web build plus Firebase deploy
managers/datetime.py    Android Date & Time settings helper

The installed Python layout is top-level modules plus the core and managers packages; it is not a single import package named flutter_dev.

Important Behavior Notes

• Many fdev commands mutate your Flutter project, Git repository, connected device, or local tool environment. Read command output before confirming prompts.
• fdev commit can stage all unstaged changes before committing.
• fdev tag updates pubspec.yaml, creates a commit, creates a Git tag, and pushes both.
• fdev discard removes tracked changes and untracked files after confirmation.
• fdev cleanup applies dart fix, formats the project, and runs a major-version dependency upgrade.
• fdev clear-data clears the installed current project's Android package without confirmation when run from a Flutter project root. If that package is missing or cannot be cleared, and whenever the command runs outside a project, it targets the foreground app after a default-Yes [Y/n] confirmation.
• fdev uninstall may fall back to foreground app detection outside a Flutter project root.
• fdev upgrade and fdev delete manage the local flutter-dev Python package, not the Flutter app on a device.
• fdev upgrade reports the installed version and location before upgrading, then shows the before→after version when the active process can verify it immediately.
• fdev delete removes the fdev command from the current Python environment after confirmation; reinstall with python -m pip install flutter-dev.
• fdev with no command prints command usage.
• Most command subcommands create build output directories at startup in the current working directory.
• Some subcommands return failure internally without always mapping that failure to a non-zero process exit code, so automation should inspect command output carefully.

Troubleshooting

Command Not Found

Make sure the Python environment where you installed the package is active:

python -m pip show flutter-dev
python -m pip install --upgrade flutter-dev

Then check:

which fdev
fdev doctor

On Windows, use:

where fdev

Upgrade Or Remove fdev

Use the built-in package management commands from the Python environment where fdev is installed:

fdev -v
fdev upgrade
fdev delete

The upgrade and delete commands print the detected OS and exact Python executable. Upgrade checks PyPI first and avoids running pip when the installed version is current. When pip is needed, both commands use the active executable with -m pip, not a hardcoded python, python3, pip, or pip3. On Windows, fdev delete and a required fdev upgrade schedule the same sys.executable -m pip ... operation in a delayed command process so the currently running console launcher can exit first.

Flutter Project Not Detected

Run project-specific commands from the directory that contains pubspec.yaml.

Build Commands Fail

Check that Flutter, Dart, Android SDK tools, Java/JDK, and project dependencies are installed:

fdev doctor
flutter doctor

AI Commit Fails

Check provider configuration and network access:

fdev ai
gemini-api

Ensure the selected provider has all three values set:

• <PROVIDER>_API_KEY
• <PROVIDER>_API_URL
• <PROVIDER>_MODEL

Screen Mirroring Fails

Install or repair scrcpy:

fdev install-scrcpy
fdev mirror
fdev mirror --turn-screen-off

--turn-screen-off may be combined with --no-top. The mirrored window stays active, but the physical Android display is turned off on supported devices.

For wireless mirroring, connect the device over USB first:

fdev wireless
fdev mirror

Starting with 0.1.16, use fdev wireless instead of fdev mirror --wireless. The old option is no longer supported. Wireless setup does not launch mirroring; run fdev mirror separately when needed. The --no-top and --turn-screen-off mirror options are unchanged.

create-page Works But fdev page Fails

For PyPI installs, use:

create-page page <page_name>

The fdev page wrapper still targets the legacy ~/scripts/flutter-tools/create_page.py path.

Packaging And Release Checks

For local packaging checks:

python -m pip install --upgrade build twine
rm -rf dist build flutter_dev.egg-info
python -m build
python -m twine check dist/*

Keep secrets out of release artifacts and documentation. Do not commit .env files or API keys. Use placeholder values in examples.

License

MIT License. See LICENSE.

Links

• Homepage: https://github.com/royalcourtbd/flutter-development-tools
• Repository: https://github.com/royalcourtbd/flutter-development-tools
• Issues: https://github.com/royalcourtbd/flutter-development-tools/issues
• Changelog: https://github.com/royalcourtbd/flutter-development-tools/blob/main/CHANGELOG.md