Getting Started

Falcon is a Rust-powered static analysis CLI tool for Flutter and Dart projects. This guide walks you through installation, your first analysis, configuration, and presets.

Installation

Install Falcon using one of these methods:

From source (Cargo)

cargo install --git https://github.com/viveky259259/falcon

From pub.dev

dart pub global activate falcon_cli

Verify installation

falcon --version

Tip

Ensure your PATH includes the Cargo or Dart pub global bin directory so the falcon command is available.

Your First Analysis

Follow these steps to run Falcon on a Flutter or Dart project.

Step 1: Navigate to your project

cd /path/to/flutter/app

Step 2: Run AI score

falcon score .

Example output:

$ falcon score .
Analyzing project...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Overall Score:  78/100
  Maintainability: 82
  Performance:     71
  Best Practices: 80
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
3 suggestions found. Run falcon check for details.

Step 3: Run full analysis

falcon check .

Example output:

$ falcon check .
Analyzing lib/...
error lib/main.dart:12:5 — Avoid using print in production
warning lib/widgets/card.dart:45:10 — Prefer const constructors
info lib/utils/helper.dart:8:1 — Consider extracting to a separate file
Found 3 issues (1 error, 1 warning, 1 info)

Configuration

Falcon uses a falcon.yaml file in your project root to customize analysis. Here's a complete example:

# falcon.yaml — Falcon configuration

metrics:
  max_complexity: 15
  max_file_lines: 500
  max_function_params: 5

rules:
  avoid_print: error
  prefer_const_constructors: warning
  use_key_in_widget_constructors: warning
  avoid_dynamic: info

unused:
  check_imports: true
  check_variables: true
  check_functions: true

exclude:
  - "**/generated/**"
  - "**/*.g.dart"
  - "**/*.freezed.dart"
  - "test/**"

Section overview

metrics — Thresholds for complexity, file size, and function parameters. Issues are reported when limits are exceeded.
rules — Rule IDs mapped to severity (error, warning, info, or off).
unused — Enable or disable checks for unused imports, variables, and functions.
exclude — Glob patterns for files or directories to skip during analysis.

Generate and validate config

Create a default config file:

falcon x init

Validate your configuration:

falcon x validate

Tip

Run falcon x init in a new project to get a sensible starting config, then customize falcon.yaml as needed.

Presets

Presets are quick rule sets for common use cases. Use --preset <name> to apply one:

Preset	Description
`recommended`	Balanced set of rules for most projects
`strict`	Maximum enforcement; good for greenfield projects
`flutter`	Flutter-specific best practices and widget rules
`ai-generated`	Rules tuned for AI-generated or assisted code
`performance`	Focus on performance and efficiency
`riverpod`	Riverpod state management patterns
`bloc`	BLoC pattern and event handling

Example:

falcon check --preset ai-generated .

What's Next

CLI Reference — Full command-line options and subcommands
Rule Catalog — All available rules and how to configure them
CI/CD Integration — Add Falcon to your continuous integration pipeline