flutter_init_cli 1.0.0

A production-ready, modular, plugin-based Flutter Project Generator CLI that configures theme, architecture, routing, and state management.

Flutter Init CLI 🚀

flutter_init_cli is a professional-grade, plugin-based Command Line Interface (CLI) tool designed to scaffold and generate clean, modular, and production-ready Flutter applications in seconds.

By automating boilerplate creation, folder structures, dependency wiring, declarative routing, and environment configurations, this tool saves developers hours of setup time and enforces standard architecture patterns.

---

Table of Contents 📖

1. Key Features
2. Prerequisites
3. Installation
4. Step-by-Step Getting Started Guide
5. Commands Reference
   • create
   • generate
6. Supported Architectures & Generated Folders
7. Environment & IDE Configuration
8. Troubleshooting & FAQs

---

Key Features 🌟

• Interactive Setup Wizard: A clean, keyboard-interactive command-line interface with arrow-key navigation for selection prompts.
• Multiple Folder Architectures: Choose the right structural layout for your scale:
  • Feature-First: Domain-driven directories grouped by feature module (Presentation, Domain, Data).
  • Clean Architecture: Strict separation of concerns divided into layers.
  • MVC / MVVM / Layer-First: Standard layered formats for traditional architectures.
• Diverse State Management Configurations: Out-of-the-box boilerplate and configuration hooks for:
  • Provider
  • Riverpod
  • BLoC / Cubit
  • GetX
  • MobX (including automatically running build_runner code generation)
• Declarative Routing: Boilerplate for standard Navigator named routes or GoRouter declarative routing.
• Networking & Offline Storage integration: Instant setup for Dio, HTTP, Hive database, SharedPreferences, and SecureStorage.
• Type-Safe Styling & Typography: Type-safe theme setup with primary color seed configs, dark mode triggers, and a clean, custom AppTextStyles class utilizing standard Material font weights (w400, w500, w600, w700).

---

Prerequisites 📋

Before installing and using the CLI, ensure the following are installed and configured on your system:

1. Flutter SDK (Version 3.10.0 or higher is recommended)
   • Ensure the flutter command is working in your terminal.
2. Dart SDK (Bundled automatically with the Flutter SDK)
   • Ensure the dart command is accessible.
3. CocoaPods (Required for iOS/macOS build toolchains on macOS)

---

Installation 📦

To activate the CLI globally from the source directory, run:

dart pub global activate --source path .

Adding Pub Executables to your Path:

If you run flutter_init_cli and receive a command not found error, you must add Dart's global package bin directory to your shell configuration profile (e.g., .zshrc, .bash_profile, or Windows Environment Variables).

• macOS / Linux: Add the following line to your ~/.zshrc or ~/.bashrc:

  export PATH="$PATH":"$HOME/.pub-cache/bin"
  

  Then reload your terminal:

  source ~/.zshrc
  

• Windows: Add %USERPROFILE%\AppData\Local\Pub\Cache\bin to your User PATH environment variables.

---

Step-by-Step Getting Started Guide 🚀

Step 1: Create a New App Boilerplate

Create a clean directory where you want to store your Flutter starter, navigate there, and run the wizard:

flutter_init_cli create

Follow the interactive prompts:

1. Project Name: Enter a valid snake_case Flutter package identifier (e.g., my_awesome_app).
2. UI Theme: Choose between Material 3 or Cupertino.
3. Primary Color: Input a HEX color (e.g., #6200EE) to seed the theme.
4. Dark Mode: Enable or disable automatic dark theme configurations.
5. Custom Font: Choose whether to register a custom font family (e.g., Outfit or Inter). (Note: You will need to add the font file to your assets and register it in pubspec.yaml to display it; see Custom Font Asset Setup below).
6. Architecture Layout: Select between MVC, MVVM, Clean Architecture, Feature-First, or Layer-First.
7. State Management: Choose Provider, Riverpod, BLoC, GetX, or MobX.
8. Routing Solution: Select standard Navigator named routing or GoRouter declarative routing.
9. Networking & Storage Options: Select the packages you want to pull and configure automatically.

The CLI will create the Flutter project, run flutter pub get, configure all dependencies/folders, and run any needed code-generation builders.

Step 2: Generate Feature Screens on the fly

Navigate into your newly generated project folder:

cd my_awesome_app

To generate a new feature module (e.g., profile screen):

flutter_init_cli generate profile

The CLI reads the project layout configuration stored inside .flutter_init_cli.json and automatically scaffolds the corresponding folder structure (Data, Domain, Presentation) and state management classes matching the project layout!

---

Commands Reference 🛠️

1. create Command

Scaffolds a new project.

• Usage:

  flutter_init_cli create [options]
  

• Options:
  • -n, --name: The name of the project. If not provided, the interactive wizard will ask for it.
  • -h, --help: Prints usage information for the create command.

---

2. generate Command (or alias g)

Scaffolds a feature module or screen inside an existing generated project.

• Usage:

  flutter_init_cli generate <feature_name>
  

  or

  flutter_init_cli g <feature_name>
  

• Options:
  • -h, --help: Prints usage information for the generate command.

---

Supported Architectures & Generated Folders 📁

A. Clean Architecture & Feature-First Layouts

When you run flutter_init_cli g <feature> inside a feature-based project, the CLI generates the complete Clean Architecture layout:

lib/
└── features/
    └── <feature_name>/
        ├── data/
        │   ├── datasources/
        │   ├── models/
        │   └── repositories/
        ├── domain/
        │   ├── entities/
        │   ├── repositories/
        │   └── usecases/
        └── presentation/
            ├── <state_folder>/   (e.g., bloc, provider, controller)
            ├── views/             (contains <feature_name>_view.dart)
            └── widgets/

B. MVC / MVVM / Layer-First Layouts

For traditional layered architectures, views and state files are generated in globally shared directories rather than nested folders:

• Views: Placed under lib/views/ (e.g., lib/views/profile_view.dart).
• State Managers: Placed under lib/controllers/, lib/viewmodels/, or lib/providers/ depending on the choice.

---

Environment & IDE Configuration 🔒

Dotenv Configuration

Every generated project includes a .env file at the root containing your default API URL config and a .env.example template.

• The .env file is automatically added to the project's .gitignore to prevent secret leakage.
• In main.dart, dotenv.load(fileName: ".env") is pre-configured.

VS Code Integration

Because macOS and VS Code hide dotfiles (like .env) by default, the CLI generates a .vscode/settings.json file containing:

{
  "files.exclude": {
    "**/.git": true,
    "**/.DS_Store": true,
    "**/node_modules": true
  }
}

This configuration forces the VS Code explorer tree to display .env and .env.example so you can edit configurations immediately.

Custom Font Asset Setup

If you select a custom font family name (for example: Outfit) during the creation wizard, the CLI sets it up as the default fontFamily in your MaterialApp theme and AppTextStyles class.

To make the font render correctly inside the app, you must add the corresponding font asset files to your project and register them in pubspec.yaml:

1. Download the font files (e.g., Outfit-Regular.ttf, Outfit-Medium.ttf, Outfit-SemiBold.ttf, Outfit-Bold.ttf) from Google Fonts.
2. Create a folder in your project root at assets/fonts/ and place the .ttf files inside it.
3. Open pubspec.yaml and register the font files under the flutter: block:

   flutter:
     fonts:
       - family: Outfit
         fonts:
           - asset: assets/fonts/Outfit-Regular.ttf
             weight: 400
           - asset: assets/fonts/Outfit-Medium.ttf
             weight: 500
           - asset: assets/fonts/Outfit-SemiBold.ttf
             weight: 600
           - asset: assets/fonts/Outfit-Bold.ttf
             weight: 700
   

---

Troubleshooting & FAQs ❓

Q: I made changes to the CLI source code, but the changes aren't appearing when I run flutter_init_cli.

A: Since globally activated path packages run from a compiled snapshot, Dart caches the executable. When you modify the source files in lib/ or bin/, you must update the snapshot by re-running:

dart pub global activate --source path .

Q: I get a compilation error inside the generated project's router.

A: Ensure that all generated dependencies are fully resolved. Run:

flutter pub get

If using packages that require code generation (like MobX or Riverpod code generation), run:

dart run build_runner build --delete-conflicting-outputs

Q: Does the generator support Cupertino themes?

A: Yes! Selecting the Cupertino theme in the wizard automatically generates a theme configuration class in lib/core/theme/app_theme.dart returning a CupertinoThemeData and wraps the app in a CupertinoApp (or GetCupertinoApp).