Archipelago #

Ship your Flutter app in days, not weeks.

About Archipelago #

Archipelago is a CLI toolkit that generates production-ready Flutter apps from a modular monorepo template. Like its namesake — a chain of islands connected by water — each feature is a self-contained island, connected by shared infrastructure.

You generate a full workspace once with archipelago create, then drop in features and capabilities on demand with archipelago generate <brick>. Every brick is a Mason template validated against a living reference app.

Getting Started #

# Install the CLI globally
dart pub global activate archipelago_cli

# Check system requirements
archipelago doctor

# Sign in: your browser opens, you type the code and click Authorize (create does this too)
archipelago auth login

# Scaffold a new project
archipelago create --output ./my_app

The Free plan includes the CLI, the Free bricks and 3 project scaffolds per calendar month. Run archipelago brick list to see what your plan can use.

Then bootstrap the workspace:

cd my_app
dart pub get
melos bootstrap

Core Workflow #

1. Create a project #

archipelago create scaffolds the whole modular monorepo (it is a shortcut for archipelago generate flutter_modular_monorepo). Run it interactively and the CLI opens an ephemeral config file for you to fill in (app name, organization, state management, network library, vendors, etc.), or pass a pre-filled config for CI.

# Interactive — edit the generated config, save, continue
archipelago create --output ./my_app

# CI / non-interactive
archipelago create --config ci_config.json --output ./my_app

The --provision-* flags are opt-in and informational only. The CLI never runs firebase init, supabase init, or any cloud auth flow — those require interactive authentication and are left to you.

2. Generate features into an existing project #

archipelago generate <brick> (alias gen) adds a feature or capability into an already-generated project. The brick's post-generation hooks wire it into the workspace, the app DI graph, and pubspec.yaml for you.

# Add features
archipelago generate auth_sdk
archipelago generate home_sdk
archipelago generate paywall_sdk
archipelago generate webview_sdk

# CI / non-interactive
archipelago gen auth_sdk --config auth_config.json

Run archipelago brick list to see every brick available for your subscription tier.

3. Upgrade a brick you changed #

A brick stops instead of overwriting packages you changed. archipelago upgrade <brick> regenerates the new version in a scratch copy and 3-way merges it into your project with git merge-file, against the base the brick stored when it generated the packages. Conflicts keep standard markers and are listed per file (exit code 1); run upgrade again after resolving them.

archipelago upgrade app_debugger --dry-run
archipelago upgrade app_debugger

A project generated before records has none. archipelago adopt <brick> writes one from a git revision that holds the brick's files as it generated them: by default the commit that first added the brick's dirs (it prints which), or the one you pass with --base-ref <rev> (your files are not touched), and upgrade then keeps your edits. The package dirs come from the brick; --dir (repeatable) overrides them. adopt --dry-run previews it; upgrade on a brick with no record prints the adopt command to run, with the dirs filled in. --local-bricks reads the dirs from a local checkout. If none of the dirs exist in the project (one package instead of _api and _impl), adopt says so and lists what is there; pass --dir. upgrade warns when the layout changed so much that it is a migration, not a patch. With --local-bricks, no login or 401 message prints.

See Upgrading generated packages.

Exit codes and offline behaviour #

Commands use these exit codes, so scripts and agents can tell failures apart.

When the server cannot be reached (no network, timeout, or a 5xx), the CLI keeps your saved login, prints one line (Could not reach the Archipelago server. Using saved login; some commands need a connection.) and carries on with the saved account. A trial is refreshed from the server on every command, so upgrading during a trial keeps your bricks; nothing is removed while the server is unreachable. Only a server rejection of the token (HTTP 401) signs you out and removes ~/.archipelago/credentials.json; the message names the next step (expired token, token bound to another device, or invalid token).

Brick Source #

By default, bricks are fetched from Archipelago's Cloudflare R2 catalog. Two persistent overrides are available via archipelago config set:

# Default: download bricks from the hosted R2 catalog
archipelago config set source r2

# Enterprise: resolve bricks from your own git fork
archipelago config set source git
archipelago config set repo https://github.com/your-org/archipelago-fork.git

# Inspect the resolved configuration
archipelago config show

When source is git, every create/generate clones (and caches) the configured repo and stages bricks from bricks/<slug>/ instead of R2 — so Enterprise users can customize brick source while keeping the same workflow.

For a one-off override without changing the persistent config, pass --local-bricks <repo> to generate:

archipelago generate auth_sdk --local-bricks ../archipelago

Featured Bricks #

Authentication & onboarding #

• auth_sdk — login/register flow with event-driven listeners and scoped DI.
• social_auth_sdk, biometric_auth_sdk — social and biometric sign-in.
• introduction_sdk — onboarding/intro carousel.

Monetization #

• paywall_sdk — pricing UI, mock purchase flow, subscription management.
• rating_review_sdk — in-app rating prompts.

WebView & mini-apps #

Archipelago splits WebView into two bricks:

archipelago generate webview_sdk           # free, basic
archipelago generate webview_sdk_advanced  # Pro: JS bridge + mini-app container

The mini-app container ships inside webview_sdk_advanced — there is no longer a standalone mini-app brick. webview_sdk_advanced requires webview_sdk to be installed first.

AI #

• ai_chat_sdk — Pro streaming chat UI with multi-provider support (OpenAI, Anthropic).

Infrastructure & capabilities #

network_sdk, websocket_sdk, monitoring_sdk, analytics_sdk, feature_flag_sdk, connectivity_sdk, push_notification_sdk, feedback_sdk, permission_guard, launch_tracker_sdk, shorebird_sdk, and more.

Monorepo Toolkit (devtools/) #

Every generated project ships a free monorepo toolkit at devtools/, exposed through a monorepo_toolkit CLI. The most-used commands for day-to-day flavored development:

# From the project root, via the devtools toolkit:
dart run monorepo_toolkit <command>

The toolkit also bundles affected change detection, coverage, graph (dependency-graph enforcement), deps, app/workspace scaffolding, and asset/size tooling.

All Commands #

Project #

Authentication #

Archipelago uses device-bound API tokens — your token is pinned to the device that logged in.

archipelago auth login --token <your-api-token>
archipelago auth activate --promo LAUNCH2026

Configuration #

archipelago config telemetry --disable
archipelago config show

Brick management #

Utilities #

Cloud CLI checks (archipelago doctor) #

archipelago doctor includes an optional Cloud CLIs section. These checks (Firebase, gcloud, Supabase) are never fatal — they are informational so you know what to install before using the --provision-* flags.

Cloud CLIs (optional — required for --provision-*)

  ✓ firebase  13.0.0
  ! gcloud    not installed (https://cloud.google.com/sdk/docs/install)
  ✓ supabase  1.131.7

Generated Project Includes #

• Dual-GetIt DI — global scope for SDKs/infrastructure, local scope per feature.
• FeatureSDK + Registry — features self-register and contribute routes before the router is built.
• Two-phase init — blocking pre-launch (DI, routes) + non-blocking post-launch (analytics, flags).
• build_prepare — swap debug/release dependencies to strip debug-only code from release builds.
• Fastlane — iOS + Android build/deploy lanes.
• CI/CD — GitHub Actions or GitLab CI workflows.
• AI agent support — generated CLAUDE.md / AGENTS.md so AI coding assistants understand the architecture.

Philosophy #

• Modularity: independent yet connected packages, like islands in an archipelago.
• Scalability: from small apps to enterprise solutions.
• Maintainability: clear structure and consistent patterns.
• Developer Experience: efficient workflows and tooling.

Documentation #

• Getting Started
• Architecture Guide
• Brick Catalog
• Tutorials

License #

Archipelago is available under the MIT License. See the LICENSE file for more info.

Support #

• Documentation
• Discord Community
• Issue Tracker