Getting Started

This guide walks you through installing Archipelago, authenticating, and creating your first Flutter monorepo project.

Prerequisites

Before you begin, make sure you have the following installed:

Tool	Minimum Version	Check Command
Dart SDK	>= 3.13.0 (the CLI itself needs 3.12.0)	dart --version
Flutter SDK	>= 3.47.0	flutter --version
Git	Any recent version	git --version

TIP

Archipelago uses Mason under the hood for code generation. The CLI handles Mason installation automatically — you do not need to install it separately.

Install the CLI

Install the Archipelago CLI globally via Dart's package manager:

dart pub global activate archipelago_cli

Verify the installation:

archipelago --version

WARNING

Make sure ~/.pub-cache/bin is in your PATH. If you see "command not found", add it:

export PATH="$PATH":"$HOME/.pub-cache/bin"

Run Doctor

The doctor command checks your environment and reports any missing dependencies:

archipelago doctor

It checks the Dart and Flutter SDKs, Git, the Dart tools the project uses (FVM, Mason CLI, Melos and more), the brick cache, API connectivity and your login. Run archipelago doctor --fix to install missing Dart tools. Fix any other issues before continuing.

Authenticate

Archipelago uses tier-based authentication to manage access to bricks:

archipelago auth login

This prompts you to paste your API token (input is hidden). Get your token from the dashboard.

To open the browser automatically, use the --interactive flag:

archipelago auth login --interactive

This opens the Archipelago authorization page in your browser. Copy the token shown there and paste it at the CLI prompt when asked.

For CI or scripted use, pass the token directly:

archipelago auth login --token <your_api_token>

Tiers

• Free — The monorepo scaffold, the core SDKs and features, and 3 project scaffolds per calendar month
• Pro — Unlimited scaffolds and the Pro bricks (debugger, AI chat, coverage and size tooling, and more)
• Enterprise — Every brick, including the Blackbox recorder and cloud sync, plus access to the brick source repository

See Account & Billing for prices and quotas.

You can check your current auth status at any time:

archipelago auth status

Create a Project

Generate a new Flutter monorepo project:

archipelago create

The CLI launches an ephemeral configuration flow:

1. It writes flutter_modular_monorepo_config.json into the current directory
2. Open it in any editor, edit the values and save
3. Press Enter in the terminal
4. The project is generated and the config file is deleted

Pass --output <dir> to choose where the project goes, and --config <file> to skip the prompt in CI.

Configuration Options

Here is an example configuration:

{
  "appName": "MyApp",
  "organization": "Acme",
  "domain": "com",
  "prefix": "App",
  "prefixCasing": "pascalCase",
  "gitProvider": "github",
  "networkLibrary": "dio",
  "isUsingWebSocket": false,
  "websocketLibrary": "dart",
  "isUsingFirebase": false,
  "analyticsVendors": ["firebase"],
  "isUsingFeatureFlags": false,
  "featureFlagVendor": "none",
  "stateManagement": "bloc",
  "includeGenerated": false,
  "includeIntegrationTest": true,
  "integrationTestFramework": "patrol",
  "monitoringVendors": ["sentry"],
  "initializeGitRepo": true,
  "starterFeatures": ["introduction_sdk", "auth_sdk", "home_sdk", "paywall_sdk"]
}

App and Bundle IDs

domain, organization and appName build the app's store IDs. One rule applies in every generated file (Gradle, Xcode project, flavors.yaml, flavorizr.yaml, Fastlane, .well-known, Patrol, Maestro and archipelago.yaml):

Platform	Rule	com + BanuaCoder + MinimalCi
Android applicationId	<domain>.<organization>.<appName>, each segment lowercase snake_case ([a-z][a-z0-9_]*). Other characters become _. A segment that starts with a digit gets an x prefix (3M becomes x3m).	com.banua_coder.minimal_ci
iOS bundle identifier	The Android ID with every underscore dropped and the app name in lowerCamelCase. Apple allows only letters, digits, hyphens and dots. This is also what flutter create --org does.	com.banuacoder.minimalCi

Flavors add .dev and .stg to both IDs (production has no suffix). archipelago.yaml records both IDs as project.package_name (Android) and project.ios_bundle_id.

Projects generated before this rule

Before flutter_modular_monorepo 5.0.0 and app_scaffold 2.0.0, an organization with more than one word (BanuaCoder) put an underscore in the iOS bundle ID (com.banua_coder.minimalCi). App Store Connect rejects it. The Android ID did not change. The fix applies only when a project is generated, so existing projects keep their IDs. To fix one by hand, replace the iOS ID (and its .dev/.stg forms) in flavors.yaml, apps/<app>/flavorizr.yaml, ios/Runner.xcodeproj/project.pbxproj, fastlane/Appfile, fastlane/Matchfile, fastlane/Fastfile, the patrol: section of pubspec.yaml and .well-known/apple-app-site-association. Do this before the first App Store upload: a published bundle ID cannot change. Do not change the Android ID of a published app.

stateManagement is one of bloc, cubit, provider or riverpod. gitProvider picks GitHub Actions or GitLab CI. The flutter_modular_monorepo page explains every option.

What gets generated?

my_app/
├── apps/
│   └── my_app/                                   # Flutter app, with fastlane/ for iOS + Android
├── features/                                     # Feature modules (auth, home, introduction, paywall, ...)
├── infrastructure/                               # SDKs: network, analytics, monitoring, storage, ...
├── shared/                                       # feature_sdk, router_registry, consent, app config, dependencies, l10n
├── packages/                                     # UI kit and asset packages
├── utilities/                                    # app_utilities, app_lints
├── devtools/                                     # Monorepo toolkit (build-prepare, affected, coverage, ...)
├── .github/workflows/                            # CI (or .gitlab-ci.yml)
├── CLAUDE.md, AGENTS.md, .cursorrules, .claude/  # AI agent instructions
├── build_prepare.yaml                            # Debug tooling swap by flavor
├── flavors.yaml                                  # Flavor definitions
└── pubspec.yaml                                  # Dart workspace root, with the melos config

Generate a Feature

Add a new feature module to an existing project using the feature_monorepo_skeleton brick:

archipelago generate feature_monorepo_skeleton

You will be prompted to fill in a config file with the feature name and options. The CLI generates:

• Feature package with clean architecture layers
• FeatureSDK with self-registration
• Route configuration
• DI setup (GetIt module)
• Unit test scaffolding

Interactive

archipelago generate feature_monorepo_skeleton

Non-interactive (CI)

archipelago generate feature_monorepo_skeleton --config feature_config.json

Run Your App

After project creation, bootstrap the monorepo and run:

cd my_app
melos bootstrap
flutter run

TIP

melos bootstrap links all local packages and runs pub get across the entire monorepo. You only need to run it once after cloning or after adding new packages.

A debug run also lets an AI agent drive the app through Marionette MCP: run dart pub global activate marionette_mcp once, then give the agent the VM service URI that flutter run prints. Release and profile builds never contain Marionette. See AI Agent Support.

Firebase Setup

Crashlytics monitoring, FCM push, Firebase Analytics and the Remote Config feature-flag vendor all need a Firebase project. When you pick any of them, the generator adds a guarded Firebase.initializeApp() to apps/<app>/lib/bootstrap.dart, before initializeInjector(). It reads the native config files, so connect the app once per flavor:

dart pub global activate flutterfire_cli
cd apps/my_app
flutterfire configure --project=<your-firebase-project>

This writes android/app/google-services.json and ios/Runner/GoogleService-Info.plist. For one Firebase project per flavor, run it once per flavor with --android-package-name/--ios-bundle-id and place each file in the flavor's source set.

Until you do this, the app still boots. You see Firebase not configured; Firebase-backed vendors disabled. Run flutterfire configure. in the debug console, and the Firebase-backed vendors are skipped. Other vendors (Sentry, Mixpanel, OneSignal, ...) keep working.

If you prefer the Dart-options file (lib/firebase_options.dart from flutterfire configure --out), change the call to Firebase.initializeApp(options: DefaultFirebaseOptions.currentPlatform).

Next Steps

Now that your project is set up, explore these topics:

• Architecture — Understand the patterns and design decisions
• CLI Reference — Full command documentation
• Blackbox — Record debug sessions and open them in the viewer
• Brick Catalog — Browse all available bricks
• Enterprise — Source access and customization options