CLI Reference

Full reference

This page is a quick-start overview. For the complete, up-to-date CLI reference — including all flags, subcommands, and the config command family — see CLI Reference.

The Archipelago CLI (archipelago_cli) is a Dart command-line tool for generating and managing Flutter monorepo projects.

Installation

dart pub global activate archipelago_cli

Commands

archipelago create

Create a new Archipelago project with interactive configuration.

archipelago create

Writes a JSON config file into the current directory. Open it in any editor, set the project name, package name, flavors, features and more, save it, then press Enter in the terminal. The CLI generates the full monorepo and deletes the config file. In CI, pass a filled-in file with --config.

archipelago generate <brick>

Add a brick to an existing project (alias gen).

archipelago generate auth_sdk
archipelago gen auth_sdk --config auth_config.json --output .

Running generate again for a brick that is already installed upgrades it. A brick stops when you changed its packages, and the first upgrade in a project generated before the record stops once; see Upgrading generated packages.

archipelago upgrade <brick>

Merge a newer brick version into packages you changed (3-way merge with git merge-file, conflicts reported per file, exit code 1 on conflict).

archipelago upgrade app_debugger --dry-run
archipelago upgrade app_debugger

See Upgrading generated packages.

archipelago adopt <brick>

Write the generation record a project lacks, from a git revision that holds the brick's files as it generated them (by default, the commit that first added the brick's directories; the command prints which one). Your files are not touched; archipelago upgrade then merges against that revision.

archipelago adopt shared_dependencies --dry-run
archipelago adopt shared_dependencies --base-ref <rev>   # override the revision

--dry-run previews the adoption without writing. The package directories come from the brick; --dir (repeatable) overrides them. upgrade on a brick with no record prints this command with the directories filled in. --local-bricks reads the directories from a local checkout. If none of the directories exist (a feature that is one package, not _api and _impl), it says so and lists what is there. upgrade --dry-run warns when the layout changed so much that the upgrade is a migration, not a patch.

See Upgrading generated packages.

archipelago brick

List, download, update and inspect bricks: brick list (alias ls), brick download <name> or --all, brick update, brick info <name>.

archipelago doctor

Check system health and validate all required dependencies.

# Basic check
archipelago doctor

# Auto-install missing tools
archipelago doctor --fix

# Check brick-specific dependencies
archipelago doctor --brick auth_sdk

Checks for: Dart SDK, Flutter SDK, Git, FVM, Mason CLI, Melos, Rename, PubViz, FlutterGen, FlutterFire CLI, cached bricks, API connectivity and authentication. --brick <name> also checks the system tools that brick needs (for example svgo and pngquant for asset_optimizer). The firebase, gcloud and supabase CLIs are reported for information only.

archipelago config

config show, config set source|repo <value> (enterprise fork) and config telemetry --enable|--disable.

archipelago update

Update the CLI from pub.dev.

archipelago --version

Show current CLI version.

Shell completion

zsh and bash completion installs itself on the first run. Reinstall it with archipelago install-completion-files.

Configuration

The CLI uses an ephemeral JSON config flow:

1. The brick's config template is written to <brick>_config.json in the current directory
2. You edit it in any editor and press Enter in the terminal
3. The CLI reads the config, strips comments, and generates the project
4. The config file is deleted

Authentication

For Pro/Enterprise features, authenticate with your API token:

# Prompts to paste your token (hidden input)
archipelago auth login

# Opens the authorization page in your browser, then prompts for the token it shows
archipelago auth login --interactive

# Pass the token directly (for CI)
archipelago auth login --token <your_api_token>

Get your API token from the dashboard. The token is not auto-copied — you paste it at the CLI prompt.

Licence record

When the CLI loads a brick from the brick store, the server signs a short claim: an opaque licence id, the brick, its version, the time and a random nonce. The CLI appends it to .archipelago/origin.json (existing entries are never rewritten) and puts one comment line at the top of up to three barrel files of that brick, for example:

// Archipelago licence lic_3f2a... (auth_sdk). See .archipelago/origin.json.

The licence id is a keyed hash, not your email or account id. Commit the file with your project. The header is part of the generated content, so it does not count as your edit when you upgrade the brick. Bricks loaded with --local-bricks or from an Enterprise fork (config set source git) get no claim and no header, and generation never fails because a claim is missing.

Bundle Cache

Downloaded bricks are cached at ~/.archipelago/bundles/. The CLI checks for updates on each run with a TTL-based cache.

Environment Variables

Variable	Description
ARCHIPELAGO_API_URL	Override API base URL (default: production)
CI	Plain output: no colours and no banner art
ARCHIPELAGO_FORCE	1 lets a brick overwrite packages you changed since it generated them; archipelago upgrade merges instead (Upgrading generated packages)