Mono

The fast, flexible CLI for managing Dart and Flutter monorepos

Mono helps teams scan, organize, and operate large workspaces with consistent, repeatable workflows. It pairs intelligent target selection and dependency-aware ordering with simple commands you already know.

Install

Run from your workspace root:

dart pub get
dart pub global activate mono

Quick start

# 1) Create config and scaffolding
mono setup

# 2) Detect packages by pubspec and cache list
mono scan

# 3) Inspect what was detected
mono list packages

# 4) Get dependencies across all packages (dependency order by default)
mono get all

Table of Contents

setup | scan | list | get | format | test | tasks | group | ungroup | version | help

Why mono?

  • Simple, composable CLI that mirrors Dart/Flutter tooling
  • Smart target selection (names, globs, and groups) and dependency-aware ordering
  • Safe grouping for higher-level workflows
  • Extensible task system via plugin: exec

Usage

mono <command> [targets] [options]

Targets are optional for built-ins (get, format, test) and required for external exec tasks. See Target selection.

Commands

setup

What it does: Creates base config files and folders if they don't exist.

mono setup

Notes

  • Creates mono.yaml if missing
  • Creates monocfg/ with mono_projects.yaml, tasks.yaml, and groups/ if missing

scan

What it does: Scans the workspace for projects and caches the results.

mono scan
  • Scans the workspace for pubspec.yaml using include/exclude globs
  • Writes the cache to monocfg/mono_projects.yaml

list

What it does: Lists cached packages, defined groups, or merged tasks.

mono list packages|groups|tasks
  • packages: Prints cached projects (falls back to a quick scan if empty)
  • groups: Prints groups from monocfg/groups/*.list with members
  • tasks: Prints merged tasks from mono.yaml + monocfg/tasks.yaml

Examples

mono list packages
mono list groups
mono list tasks

get

What it does: Runs flutter pub get for Flutter packages and dart pub get for Dart packages.

mono get [targets]
  • Targets are optional; omit them to run on all packages

Options

Flag Description Default Example
-j, --concurrency <n> Max parallel executions auto -j 8
`--order dependency none` Execution order dependency --order none
--dry-run Print plan without running false --dry-run

Examples

mono get
mono get all
mono get :apps
mono get core_*

format

What it does: Formats Dart code in each target package.

mono format [targets] [--check]
  • Runs dart format . on each target (write by default)
  • --check runs dart format --output=none --set-exit-if-changed .

Options

Flag Description Default Example
-j, --concurrency <n> Max parallel executions auto -j 8
`--order dependency none` Execution order dependency --order none
--check Validate formatting only (no writes) false --check
--dry-run Print plan without running false --dry-run

Examples

mono format all
mono format :apps --check

test

What it does: Runs tests using flutter test or dart test based on package type.

mono test [targets]

Options

Flag Description Default Example
-j, --concurrency <n> Max parallel executions auto -j 8
`--order dependency none` Execution order dependency --order none
--dry-run Print plan without running false --dry-run

Examples

mono test
mono test ui

tasks

What it does: Prints all merged tasks with their configured plugin.

mono tasks

group

What it does: Interactively create a named group and select member packages.

mono group <name>
  • Interactively select packages for the group and save to monocfg/groups/<name>.list
  • Prevents conflicts (cannot use a package name as a group name)
  • Prompts to overwrite if the group already exists

Examples

mono group apps

ungroup

What it does: Remove a previously created group after confirmation.

mono ungroup <name>
  • Confirms and removes monocfg/groups/<name>.list

version

What it does: Prints the CLI version.

  • Alias: -v, --version

Examples

mono version
mono -v
mono --version

Run mono with no arguments to see help

Compact command reference

Command Summary
setup Create mono.yaml and monocfg/ defaults if missing.
scan Scan for pubspec.yaml and write cache to monocfg/mono_projects.yaml.
list packages Print cached projects (quick scan fallback if empty).
list groups Print groups from monocfg/groups/*.list with members.
list tasks Print merged tasks from mono.yaml + monocfg/tasks.yaml.
get [targets] Run pub get across targets (Flutter/Dart aware).
format [targets] [--check] Format code; --check validates only.
test [targets] Run tests across targets.
tasks Show all merged tasks with plugin.
group <name> Interactively create a group.
ungroup <name> Delete a group after confirmation.
version Print CLI version.
help Show usage instructions.

Target selection

Targets can be mixed and comma‑separated:

Examples

mono get all
mono get :apps
mono get core_*
mono get app,ui,core
mono build :apps
mono get app,core_*,:apps --order none
  • Default order is dependency-based; disable with --order none
  • Tokens:
    • all – all packages
    • :group – named group from monocfg/groups/<name>.list
    • glob* – glob match by package name
    • name – exact package name

Note: Dependency order ensures dependents see up-to-date local changes. Use --order none to preserve your input order when you need strict sequence control.

Configuration

Root file mono.yaml (created by mono setup):

settings:
  monocfgPath: monocfg
  concurrency: auto
  defaultOrder: dependency
include:
  - "**"
exclude:
  - "monocfg/**"
  - ".dart_tool/**"
groups: {}
tasks: {}
Key Meaning Default
settings.monocfgPath Path to the config folder monocfg
settings.concurrency Default concurrency auto
settings.defaultOrder Default execution order dependency
include Globs to include when scanning for pubspec.yaml ["**"]
exclude Globs to exclude when scanning ["monocfg/**", ".dart_tool/**"]
groups Map of groupName -> selectors (names, globs, or :group) {}
tasks Task definitions (merged with monocfg/tasks.yaml) {}

monocfg folder

  • monocfg/mono_projects.yaml
packages:
  - name: app
    path: apps/app
    kind: flutter
  • monocfg/tasks.yaml (optional)
build:
  plugin: exec
  run:
    - dart run build_runner build --delete-conflicting-outputs

Notes:

  • Tasks are merged on top of mono.yaml tasks
  • plugin: exec lets you define arbitrary shell commands per package

Concurrency and order

  • -j, --concurrency <n> overrides settings.concurrency; auto picks a heuristic based on available CPUs
  • Order:
    • dependency (default): topological order using local path/name deps
    • none: keep input/selection order

Project groups

Define named groups under monocfg/groups/ with one package name per line.

Example file monocfg/groups/apps.list:

app
ui

Usage examples:

mono list groups
mono get :apps
mono get :mobile --order none

Notes:

  • Group files are simple lists; blank lines and # comments are ignored
  • Group names are derived from filenames: <name>.list using lowercase slugs [a-z0-9][a-z0-9-_]*

Tip: Keep group names short and stable, avoid overlapping membership across groups, and prefer lowercase slugs for consistent anchors.

Custom tasks (exec plugin)

You can define reusable tasks under tasks in mono.yaml or monocfg/tasks.yaml. These are merged, with monocfg/tasks.yaml taking precedence. Tasks are runnable as top‑level commands: mono <task> [targets].

Example (monocfg/tasks.yaml):

build:
  plugin: exec
  run:
    - dart run build_runner build --delete-conflicting-outputs

lint:
  plugin: exec
  run:
    - dart analyze .

format:
  plugin: exec
  run:
    - dart format .

Discover tasks:

mono list tasks

Notes:

  • External (exec) tasks require explicit targets; use all to run on all packages
  • Built-in commands like get, format, and test run on all packages when no targets are given
  • You can set environment variables with env: and express dependencies between tasks with dependsOn: in mono.yaml
  • Tasks in monocfg/tasks.yaml override/extend those in mono.yaml

Tip: External (exec) tasks often work best when combined with named groups (e.g., mono build :apps). Use --dry-run first to verify the execution plan.

Notes and tips

  • Use mono help (or run mono with no arguments) anytime to see usage
  • Combine selectors in one run, e.g. mono get app,core_*,:apps
  • Tune parallelism with -j, --concurrency; auto uses a CPU-based heuristic
  • For tasks using plugin: exec, pass explicit targets (e.g., all or :group)
  • Run mono list packages|groups|tasks to confirm what will be affected before executing

Libraries

mono
mono_cli