Flutcn UI CLI #

Flutcn UI is a command-line interface (CLI) tool designed to streamline Flutter development by automating the setup of UI themes and the addition of pre-defined widgets. It integrates with your Flutter project to provide a consistent design system, leveraging customizable themes and a widget registry.

Features #

• Project Initialization: Set up your Flutter project with a theme directory, widget directory, and configuration file.
• Smart Widget Management:
  • Add individual widgets or select multiple from an interactive list
  • Remove installed widgets (single or batch, with --force flag)
  • Update widgets to latest registry version (single, batch, or --all)
  • Overwrite confirmation for existing files
  • Batch operations for multiple components
• Widget Versioning: Tracks installed widgets in flutcn.lock.json with SHA-256 content hashes — detects changes on update, shows install status on list.
• Customizable Themes: Choose from base color palettes (e.g., Zinc, Slate, Gray) and styles (e.g., New York).
• Interactive Experience:
  • Visual spinners for long operations
  • Conflict resolution prompts
  • Color-coded output messages

Prerequisites #

• Dart SDK: Version 3.6.2 or higher.
• Flutter: Installed and configured (required for Flutter projects where the CLI is used).

Installation #

From Source #

Clone the repository and install locally:

git clone https://github.com/OmarElhassaniAlaoui/flutcn_ui.git
cd flutcn_ui
dart pub get
dart pub global activate --source path .

From Pub #

Install globally with:

dart pub global activate flutcn_ui

Ensure the Dart pub cache bin directory (e.g., ~/.pub-cache/bin) is in your system's PATH.

Usage #

Run flutcn_ui commands from the root of your Flutter project (where pubspec.yaml exists).

Initialize a Project #

Set up Flutcn UI in your project:

flutcn_ui init [--default]

• Without --default: Prompts for:
  • Theme Path: Where theme files are stored (default: lib/themes)
  • Widgets Path: Where widget files are stored (default: lib/widgets)
  • Style: UI style (options: new-york, default)
  • Base Color: Color palette (options: zinc, slate, gray, etc.)
• With --default: Uses defaults:
  • Theme Path: lib/themes
  • Widgets Path: lib/widgets
  • Style: new-york
  • Base Color: zinc

Output:

• Creates theme files with selected palette and theme
• Generates configuration file flutcn.config.json

Examples:

# Interactive setup
flutcn_ui init

# Quick start with defaults
flutcn_ui init --default

Add Widgets #

Add components from the registry:

Single Widget:

flutcn_ui add <widget-name>

Multiple Widgets (Interactive):

flutcn_ui add
# Then select from the widget list using spacebar

Features:

• Automatically detects existing files
• Prompts to overwrite, skip, or cancel
• Preserves your customizations when skipping

Examples:

# Add a single widget
flutcn_ui add button

# Multi-select interface
flutcn_ui add
? Select widgets: (Use space to choose)
✔ [•] button
  [ ] card
  [•] avatar

Remove Widgets #

Remove installed widgets:

Single Widget:

flutcn_ui remove <widget-name>

Multiple Widgets (Interactive):

flutcn_ui remove
# Then select from installed widgets using spacebar

Options:

• --force / -f: Skip confirmation prompt

Examples:

# Remove with confirmation
flutcn_ui remove button

# Remove without confirmation
flutcn_ui remove button --force

# Interactive multi-select
flutcn_ui remove

Update Widgets #

Re-download widgets from the registry to get the latest version:

Single Widget:

flutcn_ui update <widget-name>

All Widgets:

flutcn_ui update --all

Interactive:

flutcn_ui update
# Then select from installed widgets using spacebar

Output (color-coded per widget):

• ✔ up-to-date — no changes in registry
• ↑ updated — new content downloaded
• ⚡ newly tracked — widget now tracked in lockfile

List Available Widgets #

Browse the registry and install widgets:

flutcn_ui list

Output:

• Shows install status per widget: [installed], [modified locally], or [installed - untracked]
• Interactive multi-select interface
• Batch download capability
• Shows download progress and results

Configuration #

The flutcn.config.json file controls project settings:

{
  "widgetsPath": "lib/widgets",
  "themePath": "lib/themes",
  "style": "new-york",
  "baseColor": "zinc"
}

Note: Manual edits are possible, but re-running init is recommended for major changes.

Lock File #

The flutcn.lock.json file tracks installed widgets with content hashes:

{
  "lockfileVersion": 1,
  "widgets": {
    "button": {
      "style": "new-york",
      "contentHash": "sha256:a3f5e8c9...",
      "installedAt": "2026-02-14T10:30:00.000Z"
    }
  }
}

This file is created automatically by init and updated by add, remove, and update commands. It enables change detection during updates and install status markers in list.

Dependencies #

The generated theme requires the google_fonts package. Add to pubspec.yaml:

dependencies:
  google_fonts: ^6.0.0

Run flutter pub get after adding this dependency.

Troubleshooting #

• Existing File Conflicts:
  • Use overwrite/skip prompts during add operations
  • Delete existing files manually if needed
• Component Not Found:
  • Verify registry connectivity
  • Check available widgets with flutcn_ui list
• Configuration Issues:
  • Re-initialize with flutcn_ui init
  • Validate JSON syntax in flutcn.config.json
• Update Shows "newly tracked":
  • Widget was installed before lockfile existed — this is normal, the widget is now tracked

Development #

Project Structure #

• bin/: CLI entry points and commands
• lib/src/core/: Utilities and constants
• lib/src/data/: Data layer services
• lib/src/domain/: Business logic and entities

Recent Improvements (v1.2.0) #

• ✔ remove command — uninstall widgets (single, batch, --force)
• ✔ update command — refresh widgets from registry (single, batch, --all)
• ✔ Widget versioning — SHA-256 content hashing in flutcn.lock.json
• ✔ Install status markers in list command
• ✔ Change detection during updates (up-to-date / updated / newly tracked)
• ✔ 64 unit tests
• ✔ CI/CD pipeline (analysis, release tagging, pub.dev publishing)

Roadmap ✨ #

• ❌ --path option on add command — override default widget directory
• ❌ Dependency resolution for widget inter-dependencies
• ❌ Template override support

Contributing #

We welcome contributions! To contribute:

1. Fork the repository
2. Create a feature branch (git checkout -b feature-name)
3. Commit changes (git commit -m "Add feature")
4. Push to branch (git push origin feature-name)
5. Open a Pull Request

For major changes, please open an issue first to discuss proposed changes.

License #

MIT License - see LICENSE for details.

Acknowledgments #

• Inspired by Shadcn UI's design philosophy
• Built with Dart's powerful CLI capabilities
• Supported by the Flutter community's innovations

Maintainers ✨ #

Omar Elhassani Alaoui