flutter-dev 0.1.9

A cross-platform CLI toolkit for Flutter development workflows.

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.9, Python >=3.8, MIT license, and support for macOS, Linux, and Windows.

Key Features

• Flutter build automation for APK, split APK, AAB, IPA, 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, foreground app data clearing, screen mirroring with scrcpy, wireless ADB setup, and Date & Time settings.
• 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, mirror, datetime, release-run
Java/JDK	Android builds
CocoaPods	pod, ipa
Xcode / xcrun	iOS simulator and IPA workflows on macOS
scrcpy	mirror
Firebase CLI	web-deploy
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

# 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 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.

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	Detects the foreground app and runs adb shell pm clear <package> on Android. Confirmation is skipped when it matches the current Flutter project; otherwise the default-Yes safety prompt is shown. iOS prints manual options.
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 mirror --wireless	Guides wireless ADB setup using a USB-connected Android device.
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.

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 doctor	Checks platform, Python, Flutter/Dart/Git, Python packages, Android/iOS tools, optional CLIs, .env, Flutter project detection, and global fdev availability.
fdev upgrade	Shows the current version, Python environment, package location, and PyPI source, then upgrades with python -m pip install --upgrade flutter-dev and reports the resulting version.
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 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

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. ~/.config/flutter-dev/.env
4. ~/scripts/flutter-tools/.env
5. .env beside the installed module/source
6. .env in the current working directory

Recommended setup:

mkdir -p ~/.config/flutter-dev
nano ~/.config/flutter-dev/.env

Then test:

fdev ai
gemini-api

Note: the current fdev doctor .env check is more limited than the AI runtime lookup. If doctor reports a missing .env but gemini-api succeeds, the AI configuration is still usable.

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/release-run build workflow
managers/project.py     setup, cleanup, lang, db, pod, cache repair
managers/app.py         install, uninstall, 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 skips confirmation only when the foreground Android app matches the current Flutter project's package ID; otherwise it uses 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 upgrade
fdev delete

Both commands print the detected OS and exact Python executable before running. They use that executable with -m pip, not a hardcoded python, python3, pip, or pip3, so the active venv/global Python that launched fdev is the environment that gets upgraded or deleted. On Windows, fdev delete and 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 mirror --wireless

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