███████╗ █████╗ ██████╗ ██╗     ███████╗███████╗
██╔════╝██╔══██╗██╔══██╗██║     ██╔════╝██╔════╝
█████╗  ███████║██████╔╝██║     █████╗  ███████╗
██╔══╝  ██╔══██║██╔══██╗██║     ██╔══╝  ╚════██║
██║     ██║  ██║██████╔╝███████╗███████╗███████║
╚═╝     ╚═╝  ╚═╝╚═════╝ ╚══════╝╚══════╝╚══════╝

📖 Table of Contents

• Why Fables?
• Features
• Installation
• Quick Start
• Commands
  • Core Commands
  • Build & Deploy
  • Device & Testing
  • Assets & Resources
  • Configuration & Secrets
  • Quality & Analysis
  • Release & CI/CD
  • AI Integration
• Comprehensive Guide
  • Building for Android
  • Building for iOS
  • Managing Signing Keys
  • Build Flavors & Environments
  • App Icons & Splash Screens
  • Dependency Management
  • Secrets & Environment Variables
  • Internationalization (i18n)
  • Permissions Management
  • ProGuard/R8 Configuration
  • Device Logs & Debugging
  • Version Management
• AI Agent Integration
  • Supported Agents
  • OpenClaw
  • Claude Code
  • Cursor
  • VS Code / GitHub Copilot
  • Windsurf (Codeium)
  • Cline
  • Continue.dev
  • Aider
  • Zed Editor
  • JetBrains IDEs
  • LangChain
  • CrewAI
  • AutoGen (Microsoft)
  • Semantic Kernel
  • LlamaIndex
  • Haystack (deepset)
  • OpenAI Agents SDK
  • Google ADK
  • Amazon Bedrock
  • n8n
  • Dify
  • Coze (ByteDance)
  • FastGPT
  • Flowise
  • Generic MCP Client
  • MCP Protocol Reference
  • MCP Tools Reference
• CI/CD Integration
  • GitHub Actions
  • GitLab CI
  • CircleCI
  • Bitbucket Pipelines
• Docker Support
• Configuration Reference
• Project Structure
• Testing
• Contributing
• License

🤔 Why Fables?

Setting up Flutter for Android builds is a nightmare:

Fables is a single CLI that replaces Android Studio, manages your SDK, handles signing, generates icons, creates CI/CD pipelines, and integrates with every major AI agent — all from your terminal.

✨ Features

Core 🏗️

• 🚀 Build APK, AAB, Split APKs — no Android Studio
• 🍎 iOS builds — IPA generation on macOS
• 🐳 Docker-powered SDK — auto-manages Android SDK
• 🔐 Keystore management — generate & manage signing keys
• 🔒 Code obfuscation — protect your app (on by default)
• ⚡ Build flavors — dev, staging, production
• 📊 Beautiful CLI — gradient ASCII art, book-themed spinners

Assets & Resources 🎨

• 🖼️ App icon generator — one 1024x1024 image → all platforms
• 🌊 Splash screen generator — Android + iOS launch screens
• 📦 Asset optimization — size analysis & recommendations

Quality & Analysis 📊

• 📏 APK/AAB size analysis — with optimization tips
• 📋 Permission manager — list, add, remove, auto-suggest
• 📄 Manifest viewer — AndroidManifest.xml inspection
• 🛡️ ProGuard helper — rule templates & validation
• 🧪 Test runner — beautiful Flutter test output

Developer Experience 💻

• 📱 Device deployment — install APK via ADB
• 🖥️ Emulator management — create, list, launch emulators
• 📜 Log viewer — colorized, filtered device logs
• 🔄 Version bumping — sync pubspec + Android + iOS
• 📝 Changelog generation — from git history
• 🌍 i18n support — localization setup & string extraction
• 📦 Dependency auditor — security & update checks
• 🔐 Secrets manager — per-environment .env files

AI Agent Integration 🤖

• 🔌 MCP Protocol — Model Context Protocol server
• 🤖 26 supported agents — Claude, Cursor, LangChain, CrewAI, and more
• 📡 stdio & HTTP transports — for CLI and remote agents
• 🛠️ 19 MCP tools — every Fables command as an AI tool

CI/CD 🔧

• 🐙 GitHub Actions — one-command workflow generation
• 🦊 GitLab CI — Docker-based pipeline
• ⭕ CircleCI — multi-stage builds
• 🔵 Bitbucket Pipelines — ready-to-push config

📦 Installation

Prerequisites

• Node.js 16 or later → Download
• Flutter SDK 3+ → Download

Install Fables

# Install globally (recommended)
npm install -g fables

# Or use with npx (no install)
npx fables --help

Verify Installation

fables --version
# → 0.1.0

fables doctor
# → Checks Flutter, SDK, Docker, Xcode, Java

🚀 Quick Start

# 1. Navigate to your Flutter project
cd my_flutter_app

# 2. Initialize Fables
fables init

# 3. Check your environment
fables doctor

# 4. Build your app!
fables build --target apk

# 5. Deploy to device
fables deploy build/fables/app-release.apk

That's it. No Android Studio. No SDK configuration. Just Fables. 📖✨

📖 Commands

Core Commands

Build & Deploy

Device & Testing

Assets & Resources

Configuration & Secrets

Quality & Analysis

Release & CI/CD

AI Integration

📖 Comprehensive Guide

Building for Android

APK (Installable)

# Universal APK
fables build --target apk

# Per-architecture APKs (smaller download per device)
fables build --target apk --split-per-abi

# Debug build
fables build --target apk --mode debug

# Profile build (performance testing)
fables build --target apk --mode profile

AAB (Play Store)

# App Bundle for Google Play
fables build --target aab

# With flavor
fables build --target aab --flavor production

Build Options

fables build --target apk \
  --mode release \           # release | profile | debug
  --flavor production \      # Build flavor
  --split-per-abi \          # Per-architecture APKs
  --obfuscate \              # Code obfuscation (default: on)
  --dart-define ENV=prod \   # Dart defines
  --dart-define API_KEY=xxx \
  --clean \                  # Clean before build
  --output build/fables \    # Output directory
  --yes                      # Skip confirmation

Building for iOS

# Build IPA (requires macOS with Xcode)
fables build --target ios

# With flavor
fables build --target ios --flavor staging

# Without code signing (for CI/CD)
fables build --target ios --no-sign

Requirements:

• macOS 12+ (Monterey or later)
• Xcode 14+
• CocoaPods (sudo gem install cocoapods)

Managing Signing Keys

# Generate a new keystore
fables sign generate

# Interactive prompts for:
# - Key alias
# - Certificate details (CN, O, OU, L, ST, C)
# - Password

# List signing profiles
fables sign list

Keystores are stored in .fables/keystores/ (gitignored by default).

Build Flavors & Environments

# Initialize flavors interactively
fables flavors init

# Creates configurations for:
# - dev (Development)
# - staging (Staging)
# - prod (Production)

# List configured flavors
fables flavors list

# Build a specific flavor
fables build --target apk --flavor production

Flavors are saved in .fables/fables.yaml and auto-generate Android product flavors.

App Icons & Splash Screens

Icons

# Generate all icons from a single 1024x1024 image
fables icon path/to/icon.png

# Android only
fables icon path/to/icon.png --android

# With adaptive icons
fables icon path/to/icon.png --adaptive --background "#FF6B35"

# iOS only
fables icon path/to/icon.png --ios

# Web (PWA + favicon)
fables icon path/to/icon.png --web

Generates:

• Android: 5 density buckets (mdpi → xxxhdpi) + adaptive icons
• iOS: 15 sizes including App Store icon
• Web: 192px, 512px, maskable, favicon

Splash Screens

# Generate splash screens
fables splash path/to/splash.png

# With custom background
fables splash path/to/splash.png --background "#FFFFFF"

# With dark mode support
fables splash path/to/splash.png --dark-background "#1A1A1A"

Dependency Management

# List all dependencies
fables deps list

# Include dev dependencies
fables deps list --dev

# Audit for issues
fables deps audit
# Checks: unpinned versions, git deps, supply chain risks

# Add packages
fables deps add http dio provider

# Remove packages
fables deps remove http

# Check for updates
fables deps update --dry-run

Secrets & Environment Variables

# Initialize secrets management
fables secrets init
# Creates .env files for dev, staging, production

# List environments
fables secrets list

# Set a secret
fables secrets set API_KEY sk_live_xxxxx --env production

# Load secrets as dart-defines
fables secrets load production

# Generate encryption key
fables secrets keygen

File structure:

.fables/secrets/
├── development.env
├── staging.env
└── production.env

Internationalization (i18n)

# Initialize i18n with locales
fables i18n init --locales en,es,fr,de,ja,zh

# List configured locales
fables i18n list

# Extract hardcoded strings from Dart code
fables i18n extract

# Validate translations
fables i18n validate

Permissions Management

# List current permissions
fables permissions list

# Add a permission
fables permissions add CAMERA

# Remove a permission
fables permissions remove READ_CONTACTS

# Auto-suggest permissions based on dependencies
fables permissions suggest

ProGuard/R8 Configuration

# List available rule categories
fables proguard list

# Add rules for common libraries
fables proguard add flutter
fables proguard add firebase
fables proguard add gson
fables proguard add okhttp

# Show current rules
fables proguard show

# Validate configuration
fables proguard validate

Device Logs & Debugging

# View all logs
fables logs

# Flutter-only logs
fables logs --flutter

# Filter by tag
fables logs --filter FlutterEngine

# Filter by level (V/D/I/W/E)
fables logs --level E

# Search for text
fables logs --search "error"

# Last 50 lines
fables logs --lines 50

Version Management

# Show current version
fables release version

# Bump version
fables release bump patch    # 1.0.0 → 1.0.1
fables release bump minor    # 1.0.0 → 1.1.0
fables release bump major    # 1.0.0 → 2.0.0
fables release bump build    # 1.0.0+1 → 1.0.0+2

# Bump + create git tag
fables release bump minor --tag

# Bump + generate changelog
fables release bump patch --changelog

# Generate changelog from git history
fables release changelog

Updates version in:

• pubspec.yaml
• android/app/build.gradle (versionCode + versionName)
• ios/Runner/Info.plist (CFBundleVersion + CFBundleShortVersionString)

🤖 AI Agent Integration

Fables implements the Model Context Protocol (MCP), making it compatible with every major AI coding assistant and agent framework.

Supported Agents

Setup Commands

# One command to configure any agent
fables mcp setup <agent>

# Examples:
fables mcp setup claude
fables mcp setup cursor
fables mcp setup langchain
fables mcp setup crewai

# List all available MCP tools
fables mcp tools

# Start MCP server
fables mcp serve --stdio    # For CLI agents
fables mcp serve --port 3000  # For remote agents

OpenClaw

fables mcp setup openclaw

Creates TOOLS.md with Fables integration. Add to your OpenClaw workspace.

Usage in OpenClaw:

Build my Flutter app as an APK
→ OpenClaw calls fables_build tool with target: "apk"

Claude Code

fables mcp setup claude

Creates .claude/mcp.json:

{
  "mcpServers": {
    "fables": {
      "command": "fables",
      "args": ["mcp", "serve", "--stdio"]
    }
  }
}

Usage in Claude Code:

User: "Build my Flutter app for Android release"
Claude: [calls fables_build with target: "apk", mode: "release"]

Cursor

fables mcp setup cursor

Creates .cursor/mcp.json. Fables tools appear in Cursor's AI panel.

VS Code / GitHub Copilot

fables mcp setup vscode

Creates .vscode/mcp.json. Works with GitHub Copilot Chat and VS Code extensions.

Windsurf (Codeium)

fables mcp setup windsurf

Creates .windsurf/mcp.json.

Cline

fables mcp setup cline

Creates .cline/mcp.json.

Continue.dev

fables mcp setup continue

Creates .continue/mcp.json with stdio transport.

Aider

fables mcp setup aider

Creates .aider.conf.yml with MCP server configuration.

Zed Editor

fables mcp setup zed

Creates .zed/settings.json.

JetBrains IDEs

fables mcp setup jetbrains

Creates .idea/mcp.json for IntelliJ, Android Studio, WebStorm, etc.

LangChain

fables mcp setup langchain

Creates langchain_mcp_config.json for use with LangChain's MCP adapter.

Python usage:

from langchain_mcp import MCPServer

server = MCPServer.from_config("langchain_mcp_config.json")
tools = server.get_tools()

# Use in LangChain agent
agent = create_react_agent(llm, tools)
agent.invoke({"input": "Build my Flutter app as an APK"})

CrewAI

fables mcp setup crewai

Creates crewai_mcp_config.json with capabilities metadata.

Python usage:

from crewai import Agent, Task, Crew
from crewai_tools import MCPServerToolKit

toolkit = MCPServerToolKit.from_config("crewai_mcp_config.json")

developer = Agent(
    role="Mobile Developer",
    goal="Build and deploy Flutter apps",
    tools=toolkit.get_tools(),
    backstory="Expert Flutter developer"
)

task = Task(
    description="Build the Flutter app as a release APK",
    agent=developer
)

crew = Crew(agents=[developer], tasks=[task])
crew.kickoff()

AutoGen (Microsoft)

fables mcp setup autogen

Creates autogen_mcp_config.json.

Semantic Kernel

fables mcp setup semantickernel

Creates semantickernel_mcp.json.

LlamaIndex

fables mcp setup llamaindex

Creates llamaindex_mcp.json.

Haystack (deepset)

fables mcp setup haystack

Creates haystack_mcp.yaml.

OpenAI Agents SDK

fables mcp setup openai

Creates openai_mcp_config.json.

Google ADK

fables mcp setup google

Creates google_adk_mcp.json.

Amazon Bedrock

fables mcp setup bedrock

Creates bedrock_mcp_config.json.

n8n

fables mcp setup n8n

Creates n8n_mcp.json for n8n workflow automation.

Dify

fables mcp setup dify

Creates dify_mcp.json.

Coze (ByteDance)

fables mcp setup coze

Creates coze_mcp.json.

FastGPT

fables mcp setup fastgpt

Creates fastgpt_mcp.json.

Flowise

fables mcp setup flowise

Creates flowise_mcp.json.

Generic MCP Client

For any MCP-compatible client:

fables mcp setup generic

Creates mcp_config.json with standard MCP configuration.

MCP Protocol Reference

stdio Transport (for CLI agents):

fables mcp serve --stdio

HTTP/SSE Transport (for remote agents):

fables mcp serve --port 3000 --host localhost

Endpoints:

• GET /sse — Server-Sent Events stream
• POST / — JSON-RPC requests

MCP Tools Reference

🔧 CI/CD Integration

GitHub Actions

fables ci generate github

Creates .github/workflows/fables-build.yml with:

• Android APK + AAB builds
• iOS build
• Size analysis
• Artifact uploads
• Manual dispatch with target selection

GitLab CI

fables ci generate gitlab

Creates .gitlab-ci.yml with Docker-based builds.

CircleCI

fables ci generate circleci

Creates .circleci/config.yml with multi-stage pipeline.

Bitbucket Pipelines

fables ci generate bitbucket

Creates bitbucket-pipelines.yml.

🐳 Docker Support

Fables can auto-manage the Android SDK via Docker — no Android Studio needed:

# First build sets up Docker SDK (may take a few minutes)
fables build --target apk

# Subsequent builds are fast ⚡

Docker image includes:

• Ubuntu 22.04
• Java 17 (OpenJDK)
• Android SDK (API 34)
• Android Build Tools (34.0.0)
• Flutter SDK (stable)

⚙️ Configuration Reference

.fables/fables.yaml:

name: my_app
version: 0.1.0

android:
  enabled: true
  targets:
    - apk
    - aab

ios:
  enabled: true

signing:
  autoSign: true

build:
  mode: release
  obfuscate: true
  splitDebugInfo: true

flavors:
  - name: dev
    appName: My App Dev
    bundleId: com.example.app.dev
    environment: dev
  - name: staging
    appName: My App Staging
    bundleId: com.example.app.staging
    environment: staging
  - name: prod
    appName: My App
    bundleId: com.example.app
    environment: production

📁 Project Structure

my_flutter_app/
├── .fables/
│   ├── fables.yaml          # Fables configuration
│   ├── keystores/           # Signing keystores (gitignored)
│   ├── profiles/            # Signing profiles (gitignored)
│   ├── secrets/             # Environment files (gitignored)
│   │   ├── development.env
│   │   ├── staging.env
│   │   └── production.env
│   └── .gitignore
├── lib/                     # Your Flutter code
├── pubspec.yaml
├── l10n.yaml                # i18n config (if initialized)
├── lib/l10n/                # Localization files (if initialized)
└── build/
    └── fables/              # Build output
        ├── app-release.apk
        ├── app-release.aab
        └── Runner.ipa

🧪 Testing

Fables has a comprehensive test suite:

# Run all tests
npm test

# Run with coverage
npm test -- --coverage

# Run specific test suite
npx jest --testNamePattern="fables mcp"

Test coverage:

• 50 test cases
• All 24 commands tested
• MCP tool handlers tested
• Error handling tested
• Edge cases covered

🤝 Contributing

Contributions welcome! 🎉

# 1. Fork the repo
# 2. Clone your fork
git clone https://github.com/YOUR_USERNAME/fables.git

# 3. Install dependencies
cd fables && npm install

# 4. Create a branch
git checkout -b feature/amazing-feature

# 5. Make your changes
# 6. Run tests
npm test

# 7. Commit
git commit -m 'feat: add amazing feature'

# 8. Push
git push origin feature/amazing-feature

# 9. Open a PR 🎉

Development

# Run locally
node bin/fables.js --help

# Run tests
npm test

# Watch mode
npx jest --watch

📄 License

MIT © Fables Contributors