ARCLE CLI
Agentic Flutter Development Platform
Scaffold Clean Architecture projects with BLoC, GetX, or Riverpod, choose Dio or Http networking, and configure AI agent support for Claude Code, Codex, and Gemini.
Why ARCLEARCLE removes repetitive setup work for scalable Flutter apps.
|
|
What's New In v3.0.4
- π§± Mandatory Screen Componentization Rule β Updated
.ai/coding-rules.mdand agent instruction templates (CLAUDE.md,CODEX.md,GEMINI.md) to strictly enforce clean, declarative_screen.dartfiles:- Screens must only compose named sub-widgets inside
build()β no monolithic inline widget trees or private_buildX()helper methods. - Sub-widgets extracted to feature
presentation/widgets/<name>_widget.dart(or_card.dart). - Screen-specific enums and constants extracted to feature
presentation/resources/. - Non-trivial formatting, mapping, and UI logic delegated to controllers or
presentation/utils/. - Agents must inspect existing feature widgets, resources, and controllers before generating duplicate UI elements.
- Screens must only compose named sub-widgets inside
What's New In v3.0.3
- πΌοΈ Enhanced
CommonImageContainerβ Added optional dynamic dimensions (double? height/width), text initials fallback rendering with responsive typography (fallbackText,fallbackTextColor), SVG color tinting (svgColor), and customizable borders/paddings. - π Upgraded
PaginatedListViewβ Built-in default empty state with localized text and icon,asSliversembedding mode (_sliversviaSliverMainAxisGroup), and correctedSliverPaddingwrapping for seamless integration inside custom scroll views. - π€ Standardized AI Agent Workflow (Claude, Codex, Gemini) β Unified mandatory 10-step engineering workflow across
.claude/CLAUDE.md,.codex/CODEX.md, and.gemini/GEMINI.md, requiring shared.ai/rule loading, discovery, planning, UI design system tokens (Dimensions,AppColors), Clean Architecture contracts, and test verification (PASS/FAIL/SKIPPED/NOT RUN). - π§© Core Element Investigation & Reuse Mandate β Instructs all coding agents to inspect ARCLE's existing
lib/core/elements (common_widgets,theme_manager,utils,localization,services) before designing UI and reuse them first (e.g.CommonDropdown,CommonTextField,CommonCheckbox,CommonButton,CommonLoaderfor forms), requiring explicit developer permission before adding external packages. - π Codex Migration to
CODEX.mdβ Updated Codex configuration output to.codex/CODEX.mdwith automatic registration in.codex/settings.jsoncontext_files. - π©Ί Robust AI Diagnostics & Validation β Upgraded
arcle ai validate,arcle agent validate, andarcle ai doctorto verify agent instruction files, validate shared rule references, and detect deprecated.codex/instructions.mdfiles.
π¦ Installation
Option 1: Activate globally (Recommended)
dart pub global activate arcle
Then use the arcle command directly from anywhere in your terminal.
Make sure your pub cache bin folder is in your PATH:
- Linux/macOS:
$HOME/.pub-cache/bin - Windows:
%APPDATA%\Pub\Cache\bin
Add to your PATH if not already present:
- Linux/macOS: Add to
~/.bashrcor~/.zshrc:export PATH="$PATH:$HOME/.pub-cache/bin" - Windows: Use System Properties β Environment Variables β Add
%APPDATA%\Pub\Cache\bin
Option 2: Run without activating
dart pub global run arcle:arcle --help
π Quick Start
# Create a new project β numbered prompts pick state management and network
arcle create my_app
# Or skip the menus with explicit flags (great for CI/CD)
arcle create my_app --state bloc --network dio
arcle create my_app --state getx --network http
arcle create my_app --state riverpod --network dio
# Optional alias
arcle new my_app
# Add AI agent context after project creation (opt-in)
arcle configure-ai # interactive wizard β Claude / Codex / Gemini / All
arcle agent-init # alias
# Pre-commit quality gate
arcle review # full review + coverage + AI report
arcle -r # shortcut
# Organize imports
arcle organize imports # convert to package imports and sort imports
arcle organize imports --check # preview import changes
# Add a feature
arcle feature auth
arcle feat auth # alias
# Build APK
arcle build apk --debug
arcle build apk --release
arcle build apk # choose debug/staging, release/production, or both interactively
# Validate project health
arcle doctor
arcle doctor --fix
# Structural verification
arcle verify
# Localization β add / remove individual locales
arcle add locale en # Add English (sets up infra on first run)
arcle add locale bn # Add Bengali
arcle delete locale bn # Remove Bengali locale
arcle del locale bn # Short form remove
# CI/CD pipeline generation
arcle ci add github # Add a GitHub Actions workflow (.github/workflows/ci.yml)
arcle ci add gitlab # Add a GitLab CI pipeline (.gitlab-ci.yml)
arcle ci add github --test --coverage --build apk # Full pipeline: analyze, format, test+coverage, build
arcle ci list # Show which pipelines are configured
arcle ci remove github # Remove a pipeline
π Commands
| Command | Description | Alias |
|---|---|---|
arcle create <name> |
Create a new Flutter project with Clean Architecture | arcle new |
arcle init |
Scaffold Clean Architecture in an existing project | arcle setup |
arcle feature <name> |
Generate feature layers plus docs/<name>_plan.md and docs/<name>_history.md for the feature |
arcle feat |
arcle configure-ai |
Add AI agent context files, plus root docs/PLAN.md/docs/HISTORY.md, to a project |
arcle agent-init |
arcle history add |
Log AI/human work to root and feature docs/HISTORY.md |
|
arcle review |
Pre-commit quality gate (analyze, format, missing tests) | arcle audit, arcle -r |
arcle organize imports |
Convert relative imports to package imports and organize them | |
arcle doctor |
Validate ARCLE project health and safe repairs | arcle health |
arcle verify |
Run all verification checks and save docs/report.md |
arcle ver |
arcle auto-gen-di |
Regenerate DI and refresh dependencies (BLoC) | arcle autodi |
arcle gen-di |
Regenerate DI files only (BLoC) | arcle di |
arcle build apk |
Build debug/staging, release/production, or both APKs interactively | arcle b |
arcle gen-doc |
Generate project documentation | arcle docs |
arcle add locale <code> |
Add a locale (e.g. en, my, fr) |
arcle add loc <code> |
arcle delete locale <code> |
Remove a locale | arcle del locale <code> |
arcle ci add <github|gitlab> |
Add a CI/CD pipeline | |
arcle ci list |
List configured CI/CD pipelines | |
arcle ci remove <github|gitlab> |
Remove a CI/CD pipeline |
arcle review flags
| Flag | Default | Description |
|---|---|---|
--skip-analyze |
on | Skip dart analyze |
--skip-format |
on | Skip dart format check |
--skip-missing-tests |
on | Skip missing-tests scan |
--test |
on | Compatibility flag; tests run by default |
--coverage |
on | Compatibility flag; coverage runs by default |
--ai |
on | Compatibility flag; AI review runs by default |
--skip-test |
off | Skip tests and coverage |
--skip-ai |
off | Skip AI-assisted review |
--staged |
off | Diff only staged changes (git diff --staged) |
--path |
cwd | Target project directory |
State Management
ARCLE includes templates and generators for three state management solutions:
BLoC (Business Logic Component)
- Event-driven architecture with predictable state management
- Automatic DI generation using
GetItandInjectable - Requires
build_runnerβ runarcle auto-gen-diafter adding features - Best for: Complex apps with multiple features and events
GetX
- Lightweight, reactive state management with bindings
- No
build_runnerneeded - Best for: Quick prototyping and small to medium apps
Riverpod
- Type-safe provider-based state management
- No context needed, functional approach
- Best for: Apps requiring strong typing and immutability
π€ AI Agent Configuration
arcle create generates only the Flutter Clean Architecture structure. To add AI agent context files run this from your project root after creation:
arcle configure-ai # interactive wizard β pick Claude / Codex / Gemini / All / Skip
This writes:
.ai/β shared context files (settings.yaml,project-context.md,architecture-rules.md,coding-rules.md,security-rules.md,permissions.yaml).claude/β Claude Code integration (CLAUDE.md,settings.json).codex/β OpenAI Codex integration (CODEX.md,settings.json).gemini/β Google Gemini integration (GEMINI.md,settings.json)scripts/β setup and doctor scripts for your team
State management is read from arcle.yaml automatically. Use --force to overwrite existing config.
π Documentation & Work Tracking
arcle create / arcle init / arcle configure-ai all seed a root docs/ folder, and every arcle feature <name> adds its own docs/ folder too:
my_awesome_app/
βββ docs/
β βββ PLAN.md β whole-project plan
β βββ HISTORY.md β whole-project work log (newest entries on top)
βββ lib/features/login/
βββ docs/
βββ login_plan.md β this feature's plan
βββ login_history.md β this feature's work log
Feature docs are named after the feature (<name>_plan.md / <name>_history.md) so it's always clear which feature a file belongs to, even when several files are open side by side.
When an AI agent is configured via arcle configure-ai, its instruction file (CLAUDE.md, .codex/CODEX.md, or GEMINI.md) tells it to log work as it goes:
arcle history add --summary "Fixed login crash" --agent claude
arcle history add --feature login --summary "Implemented login API" --agent claude
The first form appends a row to root docs/HISTORY.md; adding --feature <name> also appends to that feature's lib/features/<name>/docs/<name>_history.md, so you get the full project history at the root and per-feature history inside each feature module.
β Requirements
- Dart SDK:
>=3.7.0 <4.0.0 - Flutter: 3.29.3 or higher
- Operating System: macOS, Linux, or Windows
- Terminal: bash, sh, zsh, PowerShell, or Windows Terminal
Platform Notes
- Android: ARCLE automatically configures Gradle build files with SDK versions (minSdk 21, compileSdk 35) and desugaring support for modern Java features. APK building is fully supported via
arcle build apk. - iOS: ARCLE automatically configures the iOS deployment target (13.0+) in Podfile and generates essential permission descriptions in Info.plist for camera, photos, microphone, location, calendar, and contacts access.
- Generated notification and permission services include platform guards so unsupported platforms fail safely instead of crashing.
- iOS Release Builds: Remember to configure Apple signing in Xcode, set your Team ID, and manage provisioning profiles before building for distribution.
- Web is safe for shared app code, but local notifications and runtime permissions are intentionally treated as unsupported by default.
Build Behavior
arcle build apk --version-name ... --version-code ...rewrites the target project'spubspec.yamlversion field before buildingarcle build apk --env prod|stag|localrewriteslib/core/env/env_factory.dartdefault environment before building- These build changes are persistent in the target Flutter project
π§ͺ Troubleshooting
Command Not Found: arcle
dart pub global activate arcle
# Linux/macOS β add to ~/.bashrc or ~/.zshrc
export PATH="$PATH:$HOME/.pub-cache/bin"
# Windows β add to System Environment Variables
%APPDATA%\Pub\Cache\bin
Flutter SDK Not Found
flutter --version
which flutter # or 'where flutter' on Windows
Build Failures
flutter channel stable
flutter upgrade
ποΈ Project Structure
my_awesome_app/
βββ lib/
β βββ main.dart # App entry point
β βββ bootstrap.dart # Bootstrap configuration
β βββ app/
β β βββ app.dart # App widget setup
β βββ core/ # Shared infrastructure
β β βββ network/ # ApiClient (Dio/Http), BaseResponse, ApiFailure, Result
β β βββ services/ # Session, Preferences, Notifications, Permissions
β β βββ theme_manager/ # AppTheme, AppColors, Dimensions
β β βββ di/ # Dependency injection setup
β β βββ env/ # Environment configurations
β β βββ localization/ # Localization & translation loader
β β βββ route_handler/ # Routing & navigation
β β βββ utils/ # Constants, dialogs, helpers
β β βββ common_widgets/ # Reusable UI widgets
β βββ features/
β βββ demo/ # Demo feature (included!)
β β βββ data/
β β βββ domain/
β β βββ presentation/
β βββ settings/ # Settings feature (included!)
βββ assets/
β βββ images/
β βββ icons/
β βββ langs/
β βββ en.json
β βββ bn.json
βββ test/
βββ pubspec.yaml
π Feature Structure by State Management
BLoC:
lib/features/feature_name/presentation/
βββ pages/ bloc/ widgets/
β βββ feature_name_bloc.dart
β βββ feature_name_event.dart
β βββ feature_name_state.dart
GetX:
lib/features/feature_name/presentation/
βββ pages/ controller/ bindings/ widgets/
Riverpod:
lib/features/feature_name/presentation/
βββ pages/ providers/ state/ widgets/
π Features
- π¦ Full project scaffolding with Clean Architecture
- π― Interactive state management selection (numbered prompt, works on all terminals)
- π§© Feature generation (data/domain/presentation layers)
- π Automatic DI wiring (BLoC/GetIt/Injectable)
- π± Build APK (debug and release modes)
- π Documentation generation
- π¨ Pre-configured theming system
- π Dual network client setup with Dio or Http and unified error handling
- π Per-locale management with
arcle add localeandarcle delete locale - π Deep project analysis with
arcle verify --full - π€ Optional AI agent context (Claude Code, Codex, Gemini) via
arcle configure-ai - π§ Universal responsive
Dimensionsclass viadart:uiPlatformDispatcher - β
Pre-commit quality gate with
arcle review
π Toolchain
- Dart SDK:
>=3.7.0 <4.0.0 - Flutter: 3.29.3+ (stable channel recommended)
See TOOLCHAIN.md for release-specific versions and environment setup details.
πΊοΈ Roadmap
Add support for more state management options (Provider, Redux)Generate unit tests automaticallyAdd GraphQL supportGenerate widget testsAdd Firebase integration optionSupport for custom templates
π€ Contributing
- Fork the repository
- Create a feature branch
- Commit your changes
- Push to your branch
- Open a pull request
π License
MIT License. See LICENSE.
π Acknowledgments
- Flutter team for the amazing framework
- BLoC, GetX, Riverpod library maintainers
- Clean Architecture community
- All contributors
β Star History
If ARCLE helps you, consider giving it a star! β
Happy Coding! π