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
| Flag | Description |
|---|---|
--config, -c |
Path to a pre-filled config JSON file (CI mode — skips the interactive prompt). |
--output, -o |
Output directory. Defaults to .. |
--provision-firebase |
After generation, print Firebase setup steps and write a provision-firebase.sh script (.cmd on Windows). |
--provision-supabase |
After generation, print Supabase setup steps and write a provision-supabase.sh script. |
The
--provision-*flags are opt-in and informational only. The CLI never runsfirebase 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
| Flag | Description |
|---|---|
--config, -c |
Path to a pre-filled config JSON file (CI mode). |
--output, -o |
Output directory (project root). Defaults to .. |
--local-bricks |
Path to a local Archipelago repo. Bypasses the R2 download and loads the brick from bricks/<slug>/ or bundles/<slug>.bundle. |
--on-conflict |
What to do when an existing file differs from the template: prompt (default), overwrite or skip. Without a terminal, pass overwrite or skip; a conflict with no choice stops with a usage error. |
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.
| Code | Meaning |
|---|---|
| 0 | Success |
| 64 | Usage error (bad flags or arguments) |
| 67 | Not logged in: the server rejected the token (auth login, create, generate, upgrade) |
| 69 | The Archipelago server could not be reached (auth login while offline) |
| 70 | Any other failure |
| 76 | create, generate: this CLI is too old for the server; upgrade the CLI |
| 77 | create, generate: blocked by your plan (free generation limit reached, a brick outside your plan, or your licence no longer covers new brick versions) |
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:
| Brick | Tier | Capabilities |
|---|---|---|
webview_sdk |
Free | Basic WebView: URL loading, navigation controls, progress tracking, one-way JS calls, and URI-scheme interception. No JS bridge. |
webview_sdk_advanced |
Pro | Everything in webview_sdk plus a bidirectional JS bridge (typed handlers + Promises), request/response interceptors for auth-header injection, deeplink routing back to native, and a full mini-app container — a manifest registry, bridge dispatcher, lifecycle state machine, and capability handlers, config-driven via assets/config/mini_apps.yaml. |
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_advancedrequireswebview_sdkto 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>
| Command | Description |
|---|---|
build-prepare <debug|release> |
Swap debug/release dependencies (e.g. monitoring_impl → monitoring_noop) at the pubspec.yaml level before a build, then restore. |
env switch <flavor> |
Switch the active environment (.env := .env.<flavor>) for the selected flavor. Also: env init, env add <KEY>, env sync. |
flavor |
Manage flavors defined in flavors.yaml (flavor list, flavor add, flavor sync, flavor generate). |
run |
Interactive runner — pick an app, flavor, and device, then launch flutter run with the right --flavor and entry point. Pass --app, --flavor, --device to skip the prompts in CI. |
The toolkit also bundles affected change detection, coverage, graph (dependency-graph enforcement), deps, app/workspace scaffolding, and asset/size tooling.
All Commands
Project
| Command | Flags | Description |
|---|---|---|
archipelago create |
--config, --output, --provision-firebase, --provision-supabase |
Scaffold a new modular-monorepo project. |
archipelago generate (alias gen) |
--config, --output, --local-bricks |
Generate a brick into an existing project. |
archipelago doctor (alias dr) |
--verbose, --brick, --fix |
Check system health, dependencies, and brick compatibility. |
archipelago update |
Update the Archipelago CLI to the latest version (via pub). |
Authentication
Archipelago uses device-bound API tokens — your token is pinned to the device that logged in.
| Command | Flags | Description |
|---|---|---|
archipelago auth login |
--token |
Sign in through your browser: the CLI prints a code, you type it on the page and click Authorize, and the CLI signs in by itself. --token is for scripts and CI. |
archipelago auth logout |
Sign out and clear stored credentials. | |
archipelago auth status |
Show current authentication and subscription status. | |
archipelago auth activate |
--promo |
Activate a free trial with a promo code. |
archipelago auth rotate-key |
Rotate your device-bound API key. |
archipelago auth login --token <your-api-token>
archipelago auth activate --promo LAUNCH2026
Configuration
| Command | Description |
|---|---|
archipelago config show |
Print the resolved CLI configuration (source, repo, telemetry). |
archipelago config set <key> <value> |
Set source (r2/git) or repo (enterprise fork URL). |
archipelago config telemetry |
--enable, --disable, --status — manage anonymous usage telemetry. |
archipelago config telemetry --disable
archipelago config show
Brick management
| Command | Flags | Description |
|---|---|---|
archipelago brick list (alias ls) |
List all bricks available for your tier. | |
archipelago brick download |
--all |
Download a specific brick (or all bricks) into the cache. |
archipelago brick update |
Update cached bricks to the latest versions. | |
archipelago brick info |
Show detailed information about a brick. |
Utilities
| Command | Description |
|---|---|
archipelago --version |
Show the current CLI version. |
archipelago completion install |
Install shell completion. |
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.mdso 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.
Agent skills
The package ships four skills for AI coding agents (Claude Code, Cursor, Copilot and others): archipelago-cli-create, archipelago-cli-bricks, archipelago-cli-upgrade and archipelago-cli-troubleshooting. They teach an agent to drive this CLI with real flags and to avoid the usual mistakes (generating into an existing workspace, overwriting your edits, printing tokens).
Install them from your own project, with archipelago_cli as a dependency:
dart run skills@ get
Pick the skills you want in the prompt. They are installed into your project's .agents/skills/ directory. See Agent skills.
Documentation
License
Archipelago is available under the MIT License. See the LICENSE file for more info.
Support
Built with love for the Flutter community
Libraries
- archipelago_cli
- Archipelago CLI — toolkit for generating production-ready Flutter projects.