mono_cli

Internal implementations powering the Mono CLI.

This package contains the parser, config loader/validator, target selector, planner, runner, and built-in plugins used by the mono command.

If you are an end user of the CLI, see the mono package README instead.

Who is this for?

End users: use the mono CLI; see the mono package docs.
Library/CLI developers: import mono_cli to embed or extend Mono’s behavior.

Install / Develop

In a Dart workspace, add mono_cli as a dependency for library usage.
Developing in this repo: run the CLI through the mono package during development.

dart run mono:mono <args>

For CLI installation and full user docs, see the mono package README.

Commands (overview)

setup: Create mono.yaml if missing and scaffold monocfg/.
scan: Detect packages and write monocfg/mono_projects.yaml.
list packages|groups|tasks: List detected packages, file-based groups, or merged tasks.
get targets: Run flutter pub get (Flutter) or dart pub get (Dart).
- Options: -j, --concurrency <n>, --order dependency|none, --dry-run.
format targets: Format code across targets; add --check to verify only.
- Options: --check, plus common options above.
test targets: Run tests across targets (common options supported).
group
ungroup
tasks: List merged tasks (root mono.yaml + monocfg/tasks.yaml).
task
version: Print CLI name and version.

Target selection

You can select targets using names, groups, and globs:

mono get all
mono get :apps
mono get core_*
mono get app,ui,core

Default ordering is dependency-based. Disable with --order none.

Configuration (mono.yaml)

mono setup creates a starter mono.yaml. Key fields:

settings:
  monocfgPath: monocfg
  concurrency: auto
  defaultOrder: dependency
  shellWindows: powershell
  shellPosix: bash
include:
  - "**"
exclude:
  - "monocfg/**"
  - ".dart_tool/**"
packages: {} # optional name -> relative path overrides
tasks: {}

settings.monocfgPath: path to the config folder (monocfg by default).
settings.concurrency: number or auto.
settings.defaultOrder: dependency or none.
settings.shellWindows/shellPosix: default shells used by the exec plugin.
include/exclude: globs for scanning pubspec.yaml.
packages: map of name → relative path overrides (optional).
tasks: task definitions (merged with monocfg/tasks.yaml).

monocfg folder

monocfg/mono_projects.yaml: cache of detected packages (written by scan).

packages:
  - name: app
    path: apps/app
    kind: flutter

monocfg/tasks.yaml (optional): user-defined tasks that override/extend root tasks.

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

Notes:

Tasks defined in monocfg/tasks.yaml override/extend those in mono.yaml.
plugin: exec runs shell commands per package directory.

Groups management (file-based)

Groups are stored as files under monocfg/groups/ and are managed via commands:

mono group <name>     # interactive selection and save to monocfg/groups
mono ungroup <name>   # remove file-backed group
mono list groups      # inspect groups and members

Group expansion supports nesting (use :groupName).
Globs match against package names (not paths).

Tasks and plugins

Built-in plugins:

pub: supports get (and clean when invoked via tasks).
exec: runs shell commands (run: lines) in each package.
format: runs formatter; supports --check.
test: runs test suites.

Tasks can be defined in mono.yaml or monocfg/tasks.yaml and merged (with monocfg taking precedence). You can use env: and dependsOn:. Top-level task execution maps task names to plugins and commands:

format:
  plugin: format

get:
  plugin: pub

lint:
  plugin: exec
  run:
    - dart fix --apply

Discover tasks:

mono list tasks

Run a task directly as a command (requires explicit targets for external tasks):

mono lint all

Library usage examples

Tokenizer and parser:

final tokenizer = ArgsTokenizer();
final tokens = tokenizer.tokenize('list all --check -t app');
final parser = ArgsCliParser();
final invocation = parser.parse(['list', '--check', 'all', '-t', 'app']);

YAML loader and validator:

const yamlText = '''
include:
  - packages/*
tasks:
  build:
    run: [dart, compile]
''';
const loader = YamlConfigLoader();
final config = loader.load(yamlText);

const validator = YamlConfigValidator();
final issues = validator.validate(config);

Planning and running (conceptual):

final planner = DefaultCommandPlanner();
final task = TaskSpec(id: const CommandId('get'), plugin: const PluginId('pub'));
final plan = planner.plan(task: task, targets: targets);

final plugins = PluginRegistry({
  'pub': PubPlugin(),
  'exec': ExecPlugin(),
  'format': FormatPlugin(),
  'test': TestPlugin(),
});

final runner = Runner(
  processRunner: const DefaultProcessRunner(),
  logger: const StdLogger(),
  options: const RunnerOptions(concurrency: 4),
);
await runner.execute(plan as SimpleExecutionPlan, plugins);