⚡ relax_cli

dart pub global activate relax_cli

Most scaffolding tools stop the moment your project is created. relax keeps going. It generates a clean, multi-flavor Flutter app with the state management you choose — Bloc, Provider, Riverpod, or GetX — and then gives you a full quality platform to analyze architecture, generate tests, measure coverage, and track your project's health over time. All from your terminal, with zero config.

Contents

• Why relax?
• Quickstart
• The relax quality platform — analyze, generate tests & use cases, dashboard, CI
• Scaffolding and code generation
• Environment, packages, and builds
• Supported architectures
• What you get out of the box
• Installation
• Development and contributing
• License

Why relax?

• 🏗️ Real projects, not templates. relax create scaffolds Clean Architecture, Material 3 theming, dependency injection, i18n, multi-flavor entry points, navigation, and a working example feature — ready to flutter run.
• 🔍 A quality platform built in. relax quality reads any Flutter project (regardless of state management) and reports architecture violations, code smells, missing tests, and a 0–100 health score — then generates the tests and use cases to fix them.
• 📊 See it, don't guess it. An embedded, offline web dashboard (--dashboard) with a score gauge, coverage heatmap, and clickable dependency graph. No accounts, no telemetry, localhost only.
• 🤖 CI-ready. JSON + JUnit reports, configurable quality gates, and score-regression detection out of the box.
• 🧩 Batteries included. Manage Flutter SDK versions, add packages, and build optimized release artifacts without leaving the CLI.
• 🚀 One dependency-free binary. Pure Dart. No Node, no native database, no build step.

Quickstart

# Install
dart pub global activate relax_cli

# Create a Clean Architecture app (pick your state management)
relax create my_app -a bloc

# Run it
cd my_app
relax pub get
flutter run --flavor development -t lib/main_development.dart

# Later: check its health
relax quality

That's it — a real, running app with theming, navigation, DI, and tests, plus a quality baseline.

The relax quality platform

Point it at any Flutter project — one you generated with relax, or a legacy codebase using GetX, Bloc/Cubit, Riverpod, Provider, MobX, or nothing at all. Analysis is read-only and non-destructive by default.

relax quality                     # instant health report in your terminal
relax quality --dashboard         # interactive web dashboard on localhost
relax quality --generate-tests    # scaffold mocktail tests for untested logic
relax quality --generate-usecases # extract UseCases from your controllers
relax quality --test --coverage   # run tests + coverage, fold into the score
relax quality --ci                # JSON + JUnit + quality gate for your pipeline

It parses lib/ with the official Dart analyzer, classifies every file into a layer (widget → controller → usecase → repository → datasource → api_service → model), and surfaces:

And it doesn't just report — it fixes:

• --generate-tests writes mocktail-based test scaffolds (one group/test per scenario: success, invalid input, network/server error, timeout) for every untested business function.
• --generate-usecases extracts a UseCase class from each controller method that carries domain logic — injected dependencies, an execute() matching the signature, the infra call reconstructed for you.

Safe by design. Generation only ever creates new files — it never rewrites your source. Every write is previewable with --dry-run and journals a reversible unified-diff patch under .relax/quality/patches/.

The dashboard

relax quality --dashboard --test --coverage

A self-contained single-page app (ships inside the CLI — no build step, no external assets) served on 127.0.0.1 only. Score gauge, coverage bars by layer, architecture badges, test results, violations, a per-feature heatmap, a score-over-time trend chart, and a clickable dependency graph laid out UI → Controller → UseCase → Repository → Datasource → API.

Ship it in CI

# e.g. GitHub Actions
- run: relax quality --ci

Writes relax-quality-report.json + relax-quality-junit.xml, and exits non-zero when your thresholds aren't met. Configure everything in .relaxrc:

{
  "quality": {
    "rules": { "maxFileLength": 400, "maxFunctionLength": 50, "maxCyclomaticComplexity": 10 },
    "ci":    { "minCoverage": 80, "maxViolations": 5, "failOnRegression": true },
    "historyRetention": 90
  }
}

Every run is recorded to .relax/quality/history.jsonl (score, coverage, test counts, git SHA) — powering the score delta, the dashboard trend chart, and regression gating. Nothing leaves your machine.

Scaffolding and code generation

relax create — a new project

relax create my_app                    # interactive architecture prompt
relax create my_app -a bloc            # or pick directly

relax create my_app -a riverpod \
  --org com.mycompany \
  --description "My awesome app" \
  --primary-color 1565C0 \
  --font Poppins

relax generate — add pieces to an existing project

relax g feature settings          # feature + auto-registered route
relax g feature auth/login         # nested feature folders, arbitrary depth
relax g page product/product_details   # page wired into its feature + child route
relax g module product             # Clean Architecture module with RelaxORM CRUD
relax g model user_profile         # standalone @RelaxTable ORM model
relax g router                     # retrofit navigation into an older project

• Auto-detects your project's architecture — no need to repeat -a.
• Auto-wires routes for every architecture (go_router GoRoute or GetX GetPage + Binding); idempotent, opt out with --no-route.
• Auto-exports new pages from the feature barrel and runs build_runner after module/model generation.

Environment, packages, and builds

relax sdk — manage Flutter SDK versions

No external tools required. Install, pin per-project or globally, and run any command against a specific SDK.

relax sdk install 3.29.0            # or: relax sdk install stable
relax sdk use 3.29.0               # pin for this project (--global for default)
relax sdk list                     # list installed versions
relax sdk releases --channel beta  # browse available releases
relax sdk flutter build apk        # run flutter with the pinned SDK
relax sdk exec make build          # run any command with the SDK on PATH

relax build — optimized release artifacts

relax build apk                    # production APK, split per ABI
relax build apk -f staging         # staging flavor
relax build aab                    # production AAB for Google Play

Formats code first, then applies --obfuscate, --split-debug-info, --tree-shake-icons, and (APK) --split-per-abi automatically. -f/--flavor selects development/staging/production; -t/--target overrides the entry point.

relax pub, relax clean, relax doctor

relax pub get                      # flutter pub get
relax pub add http -V ^1.2.0       # add a package at a version
relax clean                        # clean build artifacts
relax doctor                       # verify Dart, Flutter, and project setup

relax doctor
v1.1.0

  [+] Dart SDK — 3.11.0
  [+] Flutter SDK — 3.29.0
  [+] Flutter project — detected

FVM-aware: every Flutter command auto-detects FVM. If .fvm/fvm_config.json is present, fvm flutter is used automatically — no configuration.

Supported architectures

What you get out of the box

• Material 3 theming with light/dark mode and a customizable seed color
• Multi-flavor entry points: development, staging, production
• Feature-based Clean Architecture with barrel files and the repository pattern
• Navigation wired automatically (go_router / GetX) with type-safe route names
• RelaxORM integration: typed CRUD, reactive streams, auto-generated schemas
• Dependency injection via GetIt, i18n via slang, sealed events/states (Dart 3+)
• Auto code generation — build_runner runs after module/model creation
• A ready-to-run project with a working Home feature

my_app/
├── lib/
│   ├── main_development.dart        # flavor entry points
│   ├── main_staging.dart
│   ├── main_production.dart
│   ├── bootstrap.dart               # app initialization
│   ├── app/
│   │   ├── router/app_router.dart   # navigation
│   │   └── view/app.dart            # MaterialApp + theme
│   ├── core/
│   │   ├── di/                      # dependency injection (GetIt)
│   │   └── theme/                   # colors, theme, typography (Material 3)
│   ├── features/
│   │   ├── features.dart            # aggregate barrel
│   │   └── home/
│   │       ├── bloc/                # Bloc, Events, States
│   │       └── view/                # Page & View
│   └── i18n/slang/                  # translations (generated)
├── test/
├── pubspec.yaml
└── analysis_options.yaml

lib/modules/product/
├── product.dart                     # barrel
├── models/product.dart              # @RelaxTable model (+ product.g.dart, generated)
├── repositories/                    # abstract interface + implementation
└── data_sources/                    # RelaxORM Collection<T>

Installation

# From pub.dev
dart pub global activate relax_cli

# From source
dart pub global activate --source path .

Make sure the pub global bin directory is on your PATH (~/.pub-cache/bin on macOS/Linux, %LOCALAPPDATA%\Pub\Cache\bin on Windows).

Development and contributing

dart test                  # run tests
dart test --concurrency=1  # sequential (some tests use Directory.current)
dart analyze               # static analysis
dart run bin/relax.dart create my_app -a bloc   # run locally
dart compile exe bin/relax.dart -o relax         # native binary

Issues and PRs welcome — see CONTRIBUTING.md. By participating you agree to the Code of Conduct.

License

MIT © 2025 KalybosPro