Moose CLI #

Moose CLI is a lightweight, globally installable tool that surfaces metadata about the Moose ecosystem and proxies common workflows (e.g., bootstrapping Moose starter templates via manifests) in an AI-friendly manner.

Install #

# Verify Flutter is on PATH (required because the CLI bootstraps Flutter projects)
# macOS/Linux:
flutter --version >/dev/null 2>&1
# Windows (PowerShell):
flutter --version > $null 2>&1

# If the command above fails, install Flutter first: https://docs.flutter.dev/get-started/install

dart pub global activate moose_cli

Once activated you can run the CLI from anywhere. The snippet below walks through the most common flows:

# Print the installed version
moose version

# Scaffold an empty Flutter project (no manifest needed)
moose init my_app

# Bootstrap from a named built-in template
moose init my_app --template shopify

# Bootstrap a Moose starter project using a manifest on disk
moose init my_app --manifest ./starter_manifest.json

# Or point to a remote manifest (GitHub raw, CDN, etc.)
moose init my_app --manifest https://raw.githubusercontent.com/greymooseinc/moose_templates/refs/heads/main/shopify.json

What happens during moose init? #

# verbose mode streams git output as repositories are cloned
moose init storefront --manifest ./manifests/shopify.json --verbose

1. Manifest download – reads shopify.json from disk or an HTTPS URL.
2. Base repo clone – clones the base.repository into storefront, strips .git, and prepares the project.
3. Extensions clone – pulls the extensions.repository, copies the requested plugins/adapters into lib/plugins and lib/adapters, and merges any dependency overrides.
4. Registration – updates lib/main.dart by adding import statements and appending adapter/plugin entries to MooseBootstrapper.run(adapters: [...], plugins: [...]) using classes from each module’s moose.manifest.json.
5. Configuration – writes plugin/adapter config blocks into assets/config/environment.json.
6. Localization merge – copies plugin ARB keys from lib/plugins/<name>/l10n/*.arb into all existing app ARB locale files (for example lib/l10n/app_en.arb, app_fr.arb, app_si.arb) without overwriting existing keys. If a plugin is missing a locale, the CLI falls back to template locale keys (typically English), then runs flutter gen-l10n.
7. Dependencies – merges module dependencies into pubspec.yaml and runs dart pub get.

When init finishes you’ll see a cd <project> hint, so you can immediately start building inside the new workspace.

Commands #

# Add a plugin from a remote extensions repo
moose plugin add loyalty --git https://github.com/greymooseinc/moose_extensions.git

# Add an adapter from a local extensions checkout
moose adapter add stripe --path ./extensions/lib/adapters

# Add Sinhala localization scaffold from app_en.arb
moose locale add si

Non-interactive / CI mode with --configurations #

All three scaffolding commands (init, plugin add, adapter add) accept a --configurations (-c) flag for supplying environment.json values on the command line. This lets you scaffold projects in CI pipelines or any automated context without answering interactive prompts.

Values use a dotted-path key=value format that mirrors the structure of environment.json:

plugins.<moduleName>.<field>=<value>
adapters.<moduleName>.<field>=<value>

The flag can be repeated, or multiple pairs can be passed as separate arguments:

# Init with pre-filled plugin configuration — no prompts shown
moose init my_app --template shopify \
  --configurations plugins.loyalty.apiKey=abc123 \
  --configurations "plugins.loyalty.storeName=My Shop"

# Plugin add with pre-filled config
moose plugin add loyalty \
  --configurations plugins.loyalty.apiKey=abc123

# Adapter add with pre-filled config
moose adapter add stripe \
  --configurations adapters.stripe.secretKey=sk_test_xxx \
  --configurations adapters.stripe.webhookSecret=whsec_yyy

Behaviour:

• If a supplied path matches a $REPLACE_THIS$ placeholder in the scaffolded config, the value is written automatically and the interactive prompt for that field is suppressed.
• If a supplied path does not exist in the scaffolded config, it is created (intermediate maps are added as needed).
• Any placeholders not covered by --configurations are still prompted interactively as usual.

Tips:

• Use --template <name> for built-in templates; use --manifest for a local file or custom URL. They are mutually exclusive.
• Templates are defined by manifest JSON files. Use --manifest to point to those manifests, either on disk or via an HTTPS URL.
• Command output is color-coded with emoji markers so you can follow progress at a glance.
• Use moose plugin add or moose adapter add to pull individual modules without re-running init.
• If you omit --git when running moose plugin|adapter add, the CLI defaults to https://github.com/greymooseinc/moose_extensions.git.
• Running moose plugin add or moose adapter add on a module that is already installed prints a warning and exits — remove the directory first if you want to reinstall.
• moose locale add <code> accepts ISO 639-1 language codes (optionally with a region like pt-BR) and creates locale ARB files from your template ARB.
• The manifest must specify the base repository and optional extensions repository; git must be installed and available on PATH.
• When plugins or adapters are present in the manifest, lib/main.dart is automatically updated to import and register them.
• Plugin/adapter configs defined in manifests are merged into assets/config/environment.json under their respective sections.
• Each plugin can ship its own moose.manifest.json describing required imports and dependencies. These dependencies are merged into your project’s pubspec.yaml before dart pub get runs.
• dart pub get runs automatically after cloning the template and installing extensions so dependencies stay in sync.

Development #

dart test