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:

Install script on macOS or Linux (recommended)

curl -fsSL https://raw.githubusercontent.com/viveky259259/falcon/master/scripts/install.sh | sh

Downloads the release for your platform from GitHub Releases, verifies it against SHA256SUMS, and installs falcon, falcon-lsp and falcon-mcp to ~/.local/bin. No Rust toolchain needed. Supports macOS (Apple Silicon and Intel) and Linux x64. Pass --version vX.Y.Z or --install-dir DIR after sh -s -- to change the defaults.

With Rust installed

cargo binstall falcon-flutter   # prebuilt binary, seconds
cargo install falcon-flutter    # builds from source, a few minutes

Verify installation

falcon --version
Tip

Make sure your PATH includes ~/.local/bin (install script) or ~/.cargo/bin (Cargo) so the falcon command is available. The install script prints the exact line to add if it is missing.

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

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