CLI

CLI Reference

The Archipelago CLI (archipelago) manages brick templates, scaffolds new projects, and keeps your development environment healthy.

Installation

bash

dart pub global activate archipelago_cli

Verify your installation:

bash

archipelago --version

`doctor`

Check system health and validate the development environment.

Usage:

bash

archipelago doctor [flags]

Flags:

Flag	Short	Description
`--verbose`	`-v`	Show additional diagnostic information
`--fix`		Auto-fix missing external dependencies
`--brick <name>`	`-b`	Check dependencies for a specific brick only

Examples:

Basic CheckVerbose OutputCheck Specific BrickAuto-Fix

bash

archipelago doctor

bash

archipelago doctor --verbose

bash

archipelago doctor --brick auth

bash

archipelago doctor --fix

The doctor checks:

Dart SDK, Flutter SDK and Git
Dart tools: FVM, Mason CLI, Melos, Rename, PubViz, FlutterGen and FlutterFire CLI (--fix installs missing ones with dart pub global activate)
Cached bricks
API connectivity and authentication status
Brick-specific system dependencies (with --brick)
Cloud CLIs (optional — informational only, does not affect exit code):
- firebase — Firebase CLI for FCM / Crashlytics setup
- gcloud — Google Cloud SDK for Firebase App Distribution / Play integration
- supabase — Supabase CLI for database migrations and edge functions

TIP

Run archipelago doctor after initial setup to ensure all prerequisites are met before generating code.

`auth`

Manage authentication with the Archipelago API. Authentication determines which brick tier (Free, Pro, Enterprise) you can access.

`auth login`

Authenticate with the Archipelago API.

Usage:

bash

archipelago auth login [flags]

Flags:

Flag	Short	Description
`--token <token>`	`-t`	API token for authentication
`--interactive`	`-i`	Interactive login flow (opens browser)

Examples:

Token AuthInteractive Login

bash

archipelago auth login --token your_api_token_here

bash

archipelago auth login --interactive

With no flag, auth login asks you to paste a token (the input is hidden).

--interactive opens https://archipelago.banuacoder.com/cli/authorize in your browser with this device's name and platform. Sign in, copy the token the page shows, and paste it at the CLI prompt. The token is bound to this device.

TIP

Use --token in CI. Create the token in Dashboard → CLI Tokens (/dashboard/cli-tokens) and keep it in a CI secret.

`auth logout`

Clear stored authentication credentials.

Usage:

bash

archipelago auth logout

`auth status`

Check current authentication status and tier information.

Usage:

bash

archipelago auth status

Output example:

✓ Authenticated
User: Jane Doe (jane@example.com)
Tier: pro

Cache: 12 bundle(s), 3.4 MB
Cache location: /Users/you/.archipelago/bundles

When you are not logged in, auth status prints how to log in. It always exits with 0.

`auth activate`

Activate a free trial using a promo code.

Usage:

bash

archipelago auth activate --promo <code>

Flags:

Flag	Short	Description
`--promo <code>`	`-p`	The promo code to activate

Examples:

bash

archipelago auth activate --promo LAUNCH2025

TIP

Promo codes grant a free trial of a paid tier. Run archipelago auth status after activation to confirm your trial tier and expiry date.

`auth rotate-key`

Rotate the request signing key of your current token. The CLI signs its API requests with this key. Rotate it if you think the key leaked. You must be logged in.

Usage:

bash

archipelago auth rotate-key

Output example:

✓ Signing key rotated.

The CLI saves the new key with your credentials and uses it at once.

`config`

Manage persistent CLI configuration stored at ~/.archipelago/config.json.

`config set`

Set a configuration value.

Usage:

bash

archipelago config set <key> <value>

Supported keys:

Key	Values	Description
`source`	`r2`, `git`	Brick download source. `r2` = official Cloudflare R2 (default); `git` = enterprise fork.
`repo`	`<git-url>`	Enterprise fork URL. Only used when `source` is `git`.

Examples:

Switch to Enterprise ForkRevert to Official Source

bash

archipelago config set source git
archipelago config set repo https://github.com/your-org/archipelago-enterprise.git

bash

archipelago config set source r2

TIP

After setting source git, run archipelago config set repo <url> to specify your fork. The first archipelago generate will clone the fork; subsequent runs fetch and reset to HEAD.

`config show`

Print the resolved CLI configuration.

Usage:

bash

archipelago config show

Output example:

Archipelago CLI configuration
  Config file:     /Users/you/.archipelago/config.json
  Telemetry:       enabled
  Brick source:    git
  Brick repo URL:  https://github.com/your-org/archipelago-enterprise.git

`config telemetry`

Enable, disable, or inspect anonymous usage telemetry.

Usage:

bash

archipelago config telemetry [flags]

Flags:

Flag	Description
`--enable`	Opt in to anonymous telemetry
`--disable`	Opt out of telemetry

With no flag, the command prints the current setting: enabled, disabled or not set. When it is not set, the CLI asks once, on the first interactive run. It never asks in a non-interactive shell.

Examples:

EnableDisableCheck Status

bash

archipelago config telemetry --enable

bash

archipelago config telemetry --disable

bash

archipelago config telemetry

`brick`

Manage brick templates — list available bricks, download them, check for updates, and view details.

`brick list`

List all available bricks for your subscription tier.

Usage:

bash

archipelago brick list

Aliases: ls

Output example:

Available Bricks (Pro tier)

Name                          Version  Category       Size    Cached
flutter_modular_monorepo      1.2.0    scaffold       45 KB   ✓
feature_monorepo_skeleton     1.0.3    feature        12 KB   ✓
flutter_ui_kit                1.1.0    package        8 KB    ✗
flutter_l10n                  1.0.0    package        5 KB    ✗
app_scaffold                  1.0.1    scaffold       15 KB   ✗

`brick download`

Download a brick bundle to the local cache.

Usage:

bash

archipelago brick download <name> [flags]

Flags:

Flag	Description
`--all`	Download all available bricks

Examples:

Single BrickAll Bricks

bash

archipelago brick download auth

bash

archipelago brick download --all

`brick update`

Check all cached bricks for updates and download newer versions.

Usage:

bash

archipelago brick update

Output example:

✓ 2 update(s) available
  flutter_modular_monorepo  1.1.0 → 1.2.0  ✓ Updated
  feature_monorepo_skeleton 1.0.2 → 1.0.3  ✓ Updated

`brick info`

Show detailed information about a brick.

Usage:

bash

archipelago brick info <name>

Example:

bash

archipelago brick info flutter_modular_monorepo

Output example:

flutter_modular_monorepo v1.2.0

  Category:      scaffold
  Description:   Full Flutter modular monorepo with DI, routing, and CI/CD
  Tier:          Free
  Size:          45 KB
  Dependencies:  flutter, melos, mason_cli
  Cached:        Yes (downloaded 2d ago)

`create`

Create a new Flutter modular monorepo project. This is a shortcut for archipelago generate flutter_modular_monorepo.

Usage:

bash

archipelago create [flags]

Flags:

Flag	Short	Description
`--config <path>`	`-c`	Path to a pre-filled config JSON file (CI mode)
`--output <dir>`	`-o`	Output directory (default: `.`)
`--provision-firebase`		Print Firebase setup commands and write a `provision-firebase.sh` helper script into the generated project
`--provision-supabase`		Print Supabase setup commands and write a `provision-supabase.sh` helper script into the generated project

Examples:

InteractiveCI ModeWith Firebase ProvisioningWith Supabase Provisioning

bash

archipelago create

bash

archipelago create --config project_config.json --output ./my_app

bash

archipelago create --provision-firebase --output ./my_app

bash

archipelago create --provision-supabase --output ./my_app

The --provision-firebase flag prints a checklist of Firebase setup commands (firebase login, flutterfire configure, etc.) and writes a provision-firebase.sh script into the project root. The --provision-supabase flag does the same for Supabase (supabase login, supabase init, supabase link).

How the config flow works

When run without --config, the CLI:

Creates a config template file in the current directory
Opens it for you to fill in project values (name, org, features, etc.)
Waits for you to save and press Enter
Generates the project from your config
Cleans up the temporary config file

In CI mode (--config), it reads the JSON file directly and skips the interactive step.

Free-tier quota

Each archipelago create counts as one project scaffold. The Free plan includes 3 scaffolds per calendar month; Pro and Enterprise are unlimited. generate (adding bricks to a project) does not count. See Account & Billing.

Enterprise fork

When archipelago config set source git is active, create and generate sync your enterprise fork first and load the bricks from it instead of the official bundle store.

`generate`

Generate code from a brick template. This is the general-purpose generation command.

Usage:

bash

archipelago generate <brick-name> [flags]

Aliases: gen

Flags:

Flag	Short	Description
`--config <path>`	`-c`	Path to a pre-filled config JSON file (CI mode)
`--output <dir>`	`-o`	Output directory (default: `.`)
`--local-bricks <path>`		Path to a local Archipelago repo. Bypasses R2 download and loads the brick from `bricks/<slug>/` or `bundles/<slug>.bundle`.
`--on-conflict <mode>`		What to do when a generated file already exists and differs: `prompt` (default), `overwrite` or `skip`.

Without a terminal (CI, scripts, agents) there is nobody to answer the overwrite prompt, and the config prompt cannot run. Pass --config and, if files may already exist, --on-conflict overwrite or --on-conflict skip. When a conflict still hits with no terminal, the command exits with a usage error that names the flag instead of a stack trace. The ephemeral <brick>_config.json is removed even when the run fails.

Examples:

bash

archipelago generate my_custom_brick
archipelago generate my_custom_brick -c vars.json --on-conflict overwrite
archipelago gen my_custom_brick --config vars.json
archipelago generate feature_monorepo_skeleton --output ./features
archipelago generate webview_sdk_advanced --local-bricks ../archipelago

Running generate for an installed brick upgrades it. Every brick that generates its own packages keeps a generation record and stops before writing when you changed them; run upgrade to merge the new version into your changes, or set ARCHIPELAGO_FORCE=1 to overwrite them. In a project generated before the record, the first upgrade of each brick stops once for this reason. See Upgrading generated packages.

create and generate also append a signed licence claim to .archipelago/origin.json and add a one-line licence comment to a few barrel files of the brick; see Licence record.

Common Brick Slugs

generate accepts a raw brick slug — there are no alias subcommands. Pass the exact slug shown in archipelago brick list:

Slug	Description
`feature_monorepo_skeleton`	Feature module scaffold
`flutter_ui_kit`	Flutter UI kit package
`flutter_l10n`	Localization package
`app_scaffold`	App in an existing workspace
`webview_sdk`	WebView SDK (flutter_inappwebview)
`webview_sdk_advanced`	Pro WebView add-on (JS bridge, interceptors, mini-app)
`auth_sdk`	Auth feature module

TIP

Run archipelago brick list to see all available slugs for your subscription tier. Pass any slug directly to archipelago generate <slug>.

WARNING

Before generation, the CLI checks for external dependencies required by the brick. If any are missing, you'll see a warning suggesting archipelago doctor --brick <name> for details.

`upgrade`

Merge a newer brick version into the packages you changed since the brick generated them (3-way merge against the base the brick stored in .archipelago/base/<brick>/).

Usage:

bash

archipelago upgrade <brick> [flags]

<brick> is the record name: the brick slug, or feature_monorepo_skeleton/<feature>.

Flags:

Flag	Short	Description
`--dry-run`		Report what would be added, replaced, merged and in conflict; write nothing
`--config <path>`	`-c`	JSON vars that override the recorded ones (secrets are never recorded)
`--base-ref <rev>`		Git revision with the files as the previous version generated them, for a record without a stored base
`--with-deps`		First upgrade the recorded bricks this brick generates for itself
`--local-bricks <path>`		Load the new version from a local Archipelago repo
`--output <dir>`	`-o`	Project directory (default: `.`)

Examples:

bash

archipelago upgrade app_debugger --dry-run
archipelago upgrade app_debugger
archipelago upgrade app_blackbox_recorder --with-deps
archipelago upgrade feature_monorepo_skeleton/home --base-ref v1.4.0

Exit code 0: merged, and the record, base and brick_versions in archipelago.yaml now name the new version. Exit code 1: files conflict; they keep conflict markers, the record stays at the old version, and running upgrade again after resolving them finishes the upgrade. Shared files and files outside the brick's packages are never written; files deleted upstream are reported, not deleted. Needs git on the PATH. See Upgrading generated packages.

`affected` (generated devtool) Enterprise

Run CI tasks scoped to git-affected packages. There is no archipelago affected CLI command. The affected command lives in the generated devtools/ directory of your project and is run with:

bash

dart run monorepo_toolkit affected <subcommand>

Install the affected brick first to get this tool in your workspace. See the full reference at Affected Package Detection.

`affected list`

List packages affected by git changes.

bash

dart run monorepo_toolkit affected list
dart run monorepo_toolkit affected list --base develop
dart run monorepo_toolkit affected list --json   # for GitHub Actions matrix

`affected analyze`

Run flutter analyze lib on affected packages.

bash

dart run monorepo_toolkit affected analyze --base develop

`affected test`

Run flutter test on affected packages with optional coverage. Golden-tagged tests are excluded unless you pass --goldens; packages with no tests (exit 79) count as passed.

bash

dart run monorepo_toolkit affected test --coverage --base develop

`affected run`

Run an arbitrary command on affected packages.

bash

dart run monorepo_toolkit affected run -- "dart format --set-exit-if-changed ."

TIP

For the complete flag reference, see Affected Package Detection.

`update`

Update the Archipelago CLI to the latest version from pub.dev.

Usage:

bash

archipelago update

Output example:

✓ Checked for updates
✓ Updated to <latest>

When you already have the latest version, it prints CLI is already at the latest version.

TIP

The CLI also checks for updates automatically when you run any command. If a newer version is available, you'll see a notification.

Global Flags

These flags are available on all commands:

Flag	Description
`--help`, `-h`	Show usage information
`--version`, `-v`	Show the current CLI version
`--verbose`	Enable noisy logging, including all shell commands executed

Shell Completion

The CLI installs tab completion for zsh and bash on its first run. To install it again, or to remove it:

bash

archipelago install-completion-files
archipelago uninstall-completion-files

Files and Environment

Path or variable	Use
`~/.archipelago/config.json`	CLI settings: telemetry, brick source, enterprise repo URL
`~/.archipelago/bundles/`	Downloaded brick bundles. `archipelago auth status` shows the size
`ARCHIPELAGO_API_URL`	Override the API base URL. Use it only for a local test
`CI`	When set (and not `false` or `0`), the CLI drops colours and the banner art from its output

Exit Codes

Code	Meaning
`0`	Success
`64`	Usage error (invalid arguments)
`70`	Software error (internal failure)

CLI Reference ​

Installation ​

doctor ​

auth ​

auth login ​

auth logout ​

auth status ​

auth activate ​

auth rotate-key ​

config ​

config set ​

config show ​

config telemetry ​

brick ​

brick list ​

brick download ​

brick update ​

brick info ​

create ​

generate ​

Common Brick Slugs ​

upgrade ​

affected (generated devtool) Enterprise ​

affected list ​

affected analyze ​

affected test ​

affected run ​

update ​

Global Flags ​

Shell Completion ​

Files and Environment ​

Exit Codes ​

CLI Reference

Installation

`doctor`

`auth`

`auth login`

`auth logout`

`auth status`

`auth activate`

`auth rotate-key`

`config`

`config set`

`config show`

`config telemetry`

`brick`

`brick list`

`brick download`

`brick update`

`brick info`

`create`

`generate`

Common Brick Slugs

`upgrade`

`affected` (generated devtool) Enterprise

`affected list`

`affected analyze`

`affected test`

`affected run`

`update`

Global Flags

Shell Completion

Files and Environment

Exit Codes