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.11.0	dart --version
Flutter SDK	>= 3.41.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

Expected output:

Archipelago Doctor
==================
[✓] Dart SDK (3.11.0)
[✓] Flutter SDK (3.41.0)
[✓] Git
[✓] Mason CLI
[✓] Melos

All checks passed!

Fix any issues reported 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 — Core bricks (monorepo scaffold, basic features)
• Pro — All bricks + priority updates
• Enterprise — Source access + shared git repo for customization

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. An initial config JSON is generated with your project settings
2. Your default editor opens with the config for review
3. Edit any values, save, and close the editor
4. Press Enter to confirm
5. The project is generated and the config file is cleaned up

Configuration Options

Here is an example configuration:

{
  "@org": "Your organization name (used for package prefixes)",
  "org": "acme",

  "@app_name": "The Flutter app name (snake_case)",
  "app_name": "my_app",

  "@app_display_name": "Human-readable app name shown to users",
  "app_display_name": "My App",

  "@bundle_id_prefix": "Reverse domain for iOS/Android bundle ID",
  "bundle_id_prefix": "com.acme",

  "@features": "Initial features to generate (comma-separated)",
  "features": "auth,home,settings"
}

What gets generated?

my_app/
├── apps/
│   └── my_app/              # Flutter app
├── packages/
│   ├── core/                # Shared utilities, extensions, constants
│   ├── design_system/       # Widgets, themes, tokens
│   ├── networking/          # HTTP client, interceptors, API models
│   ├── storage/             # Local storage abstractions
│   └── ...
├── features/
│   ├── auth/                # Auth feature module
│   ├── home/                # Home feature module
│   └── settings/            # Settings feature module
├── devtools/                # Monorepo toolkit (affected, coverage, etc.)
├── fastlane/                # iOS + Android build/deploy automation
├── .github/workflows/       # CI/CD pipelines
├── melos.yaml               # Monorepo management
└── pubspec.yaml             # Workspace root

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.

Next Steps

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

• Architecture — Understand the patterns and design decisions
• CLI Reference — Full command documentation
• Brick Catalog — Browse all available bricks
• Enterprise — Source access and customization options