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
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
- 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, oroff). - 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
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