clarc_arch_cli 0.1.4

A CLI for scaffolding Flutter Clean Architecture projects, modules, and pages.

clarc

clarc is a Flutter scaffolding CLI for teams that want a Clean Architecture project layout without rebuilding the same folders, dependencies, routes, and dependency injection setup by hand.

The package name is clarc_arch_cli. The executable command is clarc.

What It Generates

• A Flutter project with app, core, and features layers.
• A complete default home feature across data, domain, and presentation.
• Feature modules with entities, models, repositories, use cases, Bloc, pages, routes, endpoint constants, and Get It registrations.
• Extra pages inside an existing feature module.
• Light/dark theme defaults for a newly created project.
• A safe starter home screen that loads data only after the user taps Load data.
• Optional local database wiring with sqflite.

Generated projects use common Flutter packages such as Dio, Dartz, Flutter Bloc, Get It, GoRouter, Equatable, Freezed, JSON Serializable, Shared Preferences, and Pretty Dio Logger.

Install

From pub.dev:

dart pub global activate clarc_arch_cli

Then run:

clarc --help

Make sure Dart's global pub executable directory is available in your PATH.

For local development from this repository:

dart pub get
dart pub global activate --source path .
clarc --help

You can also run the executable without global activation:

dart run clarc_arch_cli:clarc --help

Quick Start

Create a new project:

clarc create project my_app --org com.example

Add a feature module:

cd my_app
clarc create module auth

Add a page to that module:

clarc create page auth login

The page is created at:

lib/features/auth/presentation/pages/login_page.dart

And the route is registered as:

/auth/login

Interactive Wizard

You can run commands without all arguments and let clarc ask for the missing values:

clarc create project
clarc create module
clarc create page

For project creation, the wizard asks for:

What project do you want to create?
Which Flutter runner do you want to use?
  1. Flutter (default)
  2. FVM
  3. Puro
  4. Auto detect
  5. Custom command
Does this project use a local sqflite database?

Use --yes when you want the CLI to accept safe defaults in scripts.

Flutter Runner

clarc can run Flutter directly or through a version manager.

clarc create project my_app --flutter-cmd flutter
clarc create project my_app --flutter-cmd "fvm flutter"
clarc create project my_app --flutter-cmd "puro flutter"
clarc create project my_app --flutter-cmd auto

auto resolves the runner from the project tree:

• .fvmrc or .fvm uses fvm flutter.
• .puro.json or .puro uses puro flutter.
• Otherwise, it falls back to flutter.

Custom commands are supported, including quoted executable paths:

clarc create project my_app --flutter-cmd '"C:\Program Files\Flutter\bin\flutter.bat"'

clarc does not choose or lock your Flutter SDK version. Flutter, FVM, or Puro remain responsible for that.

Create A Project

clarc create project my_app --org com.example

Useful options:

clarc create project my_app --path ./apps
clarc create project my_app --platforms android,ios,web
clarc create project my_app --local-db
clarc create project my_app --no-local-db
clarc create project my_app --skip-flutter-create
clarc create project my_app --no-pub-get
clarc create project my_app --no-build-runner
clarc create project my_app --force
clarc create project my_app --yes

A new project includes:

• main.dart with setupLocator() before runApp.
• MaterialApp.router with GoRouter.
• Theme files in lib/core/theme.
• Dependency injection in lib/core/di/injection.dart.
• Endpoint constants in lib/core/constants/api_endpoints.dart.
• A default home feature.
• A Clarc-aware widget test that pumps App, not Flutter's default MyApp.

Create A Module

clarc create module auth --project-dir ./my_app

Generated structure:

lib/features/auth/
  data/
    datasources/
    models/
    repositories/
  domain/
    entities/
    repositories/
    usecases/
  presentation/
    bloc/
    pages/

clarc also updates:

• lib/app/router/app_router.dart
• lib/core/di/injection.dart
• lib/core/constants/api_endpoints.dart
• pubspec.yaml when required dependencies are missing

Entity files use the *_clarc.dart convention, for example:

lib/features/auth/domain/entities/auth_clarc.dart

Create A Page

clarc create page auth login --project-dir ./my_app

If the module does not exist, the CLI asks whether it should create the module first. When it creates a missing module, it can also run pub get and build_runner.

Generated Project Structure

lib/
  app/
    app.dart
    theme_controller.dart
    router/
      app_router.dart
  core/
    constants/
      api_endpoints.dart
    database/
      app_database.dart
    di/
      injection.dart
    error/
      failure.dart
    network/
      api_client.dart
    theme/
      app_colors.dart
      app_text_styles.dart
      app_theme.dart
    usecases/
      usecase.dart
  features/
    home/
      data/
        datasources/
        models/
        repositories/
      domain/
        entities/
        repositories/
        usecases/
      presentation/
        bloc/
        pages/
  main.dart

core/database is generated only when local database support is enabled.

The root project scaffold gets the richer theme and home-page defaults. Modules and pages created later stay intentionally plain so each feature can evolve with its own UI.

Existing Files And --force

clarc is conservative by default:

• New files are created.
• Files with the same content are reported as skipped.
• Existing files with different content are skipped unless --force is used.

Use --force only when you intentionally want to overwrite generated files. This is useful for deliberate regeneration, but risky if you already edited the generated code by hand.

Exit Codes

clarc returns process-friendly exit codes for scripts and CI:

0   Success or help output
1   Validation error, cancelled command, or runtime failure
64  Command usage or argument parser error

Recommended Workflow

Plain Flutter:

clarc create project my_app --org com.example
cd my_app
clarc create module auth
clarc create page auth login

FVM:

fvm use 3.24.0
clarc create project my_app --flutter-cmd "fvm flutter"
cd my_app
clarc create module auth --flutter-cmd "fvm flutter"
clarc create page auth login --flutter-cmd "fvm flutter"

Local database starter:

clarc create project offline_app --local-db

Troubleshooting

clarc is not recognized

Check that Dart's global pub executable directory is in your PATH.

You can still run the local executable with:

dart run clarc_arch_cli:clarc --help

Existing files are not changing

This is expected. clarc skips existing files by default. Re-run with --force only when you want generated files overwritten.

FVM or Puro is not being used

Use the wizard runner choice, pass --flutter-cmd "fvm flutter", or pass --flutter-cmd auto from inside a project that contains .fvmrc, .fvm, .puro.json, or .puro.

Generated Freezed files are missing

Run:

flutter pub get
flutter pub run build_runner build --delete-conflicting-outputs

Use fvm flutter or puro flutter instead of flutter if your project uses one of those tools.

Development

Format, analyze, and test before opening a change:

dart format bin lib test
dart analyze
dart test

Useful local smoke test:

dart run clarc_arch_cli:clarc create project sample_app \
  --skip-flutter-create \
  --no-pub-get \
  --no-build-runner \
  --yes

Release Checklist

Before publishing:

dart format bin lib test
dart analyze
dart test
dart doc --output .dart_tool/dartdoc
dart pub publish --dry-run

Then update:

• version in pubspec.yaml
• CHANGELOG.md
• Public API Dartdoc comments for exported symbols
• example/example.md when CLI usage changes

Publish:

dart pub publish

Published versions cannot be replaced, so always review the dry-run output before publishing.

For a closer approximation of pub.dev scoring, run pana on a copied checkout before publishing:

dart pub global activate pana
dart pub global run pana path/to/clarc-copy