vyrax_cli

Command-line interface for Vyrax, focused on Flutter architecture and performance analysis.

The CLI currently supports:

  • Project-aware vyrax init with stack detection and safe overwrite prompts.
  • vyrax analyze in text or JSON format.

Installation

From pub.dev (global)

dart pub global activate vyrax_cli

Then ensure your pub global binaries path is in PATH.

Verify the active version right after install/update:

vyrax --version

Do not add vyrax_cli under your app dependencies or dev_dependencies in pubspec.yaml. Use it as a global CLI tool.

Global means machine-wide (single install), not one install per project.

For end users, always update from pub.dev:

dart pub global activate vyrax_cli
vyrax --version

Do not use --source path unless you are developing the CLI itself.

Quick Start

Run in your Flutter project root:

vyrax init
vyrax analyze

Commands

vyrax init

Inspects your Flutter project and generates vyrax.yaml.

What it detects:

  • State management (riverpod, bloc, provider, etc.)
  • Dependency injection (get_it, injectable, etc.)
  • Networking (dio, http, etc.)
  • Routing (go_router, auto_route, navigator)
  • Serialization (freezed, json_serializable, etc.)
  • Architecture (clean, feature_first, mvvm, mvc, unknown)
  • Quality tools (flutter_lints, custom_lint, build_runner, melos, etc.)

Options:

vyrax init --project <path>

Behavior:

  • If project is not Flutter, command exits with code 1.
  • If vyrax.yaml exists, asks for confirmation before overwrite.

vyrax analyze

Runs Vyrax rules against the target project.

Options:

vyrax analyze --project <path> --format <text|json> [--changed|--staged|--against <branch>|<directory>|<file>] [--no-report] [--report-path <path>]

Examples:

vyrax analyze
vyrax analyze --format json
vyrax analyze --project ./examples/sample_app --format text
vyrax analyze --changed
vyrax analyze --staged
vyrax analyze --against main
vyrax analyze lib/features/auth
vyrax analyze lib/features/auth/login_page.dart
vyrax analyze --project ./examples/sample_app --report-path reports/latest.txt

Context-aware scopes:

  • vyrax analyze: analyze full project.
  • vyrax analyze --changed: analyze modified Dart files from Git.
  • vyrax analyze --staged: analyze staged Dart files from Git.
  • vyrax analyze --against <branch>: analyze Dart files changed versus a branch.
  • vyrax analyze <directory>: analyze all Dart files in a directory.
  • vyrax analyze <file.dart>: analyze one Dart file.

Notes:

  • Selected files are always analyzed completely (not only changed lines).
  • Use only one scope selector per execution.
  • If Git is not available for --changed, --staged, or --against, Vyrax returns a friendly message and exits with code 1.

Report generation behavior:

  • By default, analyze writes a text report file on every run.
  • Default folder: vyrax-reports/ in the analyzed project.
  • Default filename pattern: analyze-YYYYMMDD-HHMMSS.txt.
  • Use --no-report to disable report generation for a run.
  • Use --report-path <path> to write to a specific file (relative to project root, or absolute path).

Exit codes:

  • 0: no issues
  • 1: warnings only
  • 2: at least one error or critical issue
  • 3: invalid input or project resolution failure

Configuration

vyrax init generates a baseline vyrax.yaml that you can customize.

Example:

rules:
  future_inside_build:
    enabled: true
    severity: error
  widget_tree_complexity:
    enabled: false

output:
  format: text
  report:
    enabled: true

Rule keys support aliases (for example VYX001 or future_inside_build), but the recommended approach is to use canonical rule keys.

Available Rules

Use these keys under rules: to enable/disable each check.

Key ID What it checks Why it exists
future_inside_build VYX001 FutureBuilder/future usage patterns inside build Avoid repeated async work and unnecessary rebuild cost
network_inside_build VYX002 HTTP/network calls executed from build Prevent duplicate requests and UI jank
multiple_public_classes VYX003 More than one public class in a file Improve file ownership and maintainability
build_complexity VYX004 Large/complex widget build blocks Keep UI code easier to reason about and test
large_consumer_scope VYX005 High-level Consumer/BlocBuilder wrapping big UI sections Reduce broad reactive rebuilds
set_state_with_state_management VYX006 setState use when app-wide state management is configured Keep state strategy consistent across the app
unbounded_scrollable_in_column VYX007 Scrollables inside Column without proper constraints Prevent overflow/layout exceptions
clean_architecture_without_use_cases VYX008 Clean architecture selected but use-case layer not detected Enforce expected domain boundaries
presentation_depends_on_data_layer VYX009 Presentation/UI importing from data layer directly Reduce layer coupling
direct_external_package_in_presentation VYX010 UI imports external infra packages directly Improve testability through abstractions
singleton_overuse VYX011 Singleton-style implementations in app code Limit global shared state risk
missing_internationalization VYX012 No clear i18n setup detected Encourage localization-ready projects
broad_reactive_rebuild_scope VYX013 Reactive subscriptions inside very large build subtrees Minimize unnecessary subtree rebuilds
error_model_without_factory_mapper VYX014 Error/failure models with no mapper/factory constructor Standardize error translation and testing
hardcoded_ui_text VYX015 User-facing strings hardcoded in UI Improve localization and copy management
repeated_magic_numbers VYX016 Repeated numeric literals in the same file Improve readability with named constants
large_file VYX017 Files exceeding configured max lines Keep modules focused and reviewable
solid_single_responsibility VYX018 Classes that appear to mix too many responsibilities Encourage SRP and separation of concerns
solid_open_closed VYX019 Large branching structures that are hard to extend Encourage OCP-friendly extension patterns
solid_dependency_inversion VYX020 High-level modules instantiating concrete dependencies Promote dependency inversion and mocking
solid_opportunity VYX021 General SOLID opportunities at file level Surface broad maintainability improvements
widget_lifecycle VYX022 Risky lifecycle patterns in Flutter State classes Prevent leaks and timing-related bugs
widget_tree_complexity VYX023 Deep or wrapper-heavy widget trees Improve UI readability and rendering stability

Enable Or Disable Rules

rules:
  future_inside_build:
    enabled: true

  network_inside_build:
    enabled: false

  large_file:
    enabled: true
    severity: warning

Notes:

  • enabled: false disables that rule.
  • severity is optional and supports: info, warning, error, critical.
  • If a rule is omitted, it stays enabled by default.

Report config notes:

  • output.report.enabled: false disables report file creation globally for that project.
  • output.report.path: reports/latest.txt writes to a fixed path instead of timestamped files.

Monorepo Scope

  • vyrax analyze --project <path> analyzes Dart files recursively under that path.
  • If your app includes independent modules inside the same directory tree, they are included.
  • Excluded folders include .dart_tool, build, .git, and .idea.
  • In monorepos with multiple Flutter apps, run with the exact app path using --project to scope analysis to one app.

Troubleshooting

Command not found

If vyrax is not found after global activation, verify your Dart pub global binary path is exported in your shell profile.

CLI Version Mismatch (missing rules or old behavior)

Symptoms:

  • vyrax init does not include recently added rules.
  • vyrax --help does not show newer commands/options.

Recovery steps:

dart pub global deactivate vyrax_cli
dart pub global activate vyrax_cli
vyrax --version

Expected after recovery:

  • vyrax --version prints the latest published version.
  • vyrax init prints Default rules enabled: 23.

If your environment still behaves like an old version after re-activate, clear stale snapshots once and retry:

rm -f ~/.pub-cache/bin/vyrax
dart pub global activate vyrax_cli
vyrax --version

Not a Flutter project

Run commands from a Flutter app directory (must contain a valid pubspec.yaml with Flutter SDK dependency), or pass --project <path>.

License

See LICENSE.

Libraries

vyrax_cli
CLI utilities for rendering command help and executing commands.