Skip to content

install

View raw .md

Scaffold the canonical Flutter consumer project structure and install the fast-CLI wrapper in a single step. Running install produces bin/dispatcher.dart, the two generated barrels, and bin/dowel, then injects dowel into pubspec.yaml so every future plugin:install and make:command invocation resolves cleanly.

On this page

Prerequisites#

Add dowel to the project before invoking install. The package needs to resolve from pubspec.yaml so the substrate CLI is discoverable via dart run:

bash
dart pub add dowel

install checks the dependency at scaffold time and adds it only when the pubspec has no dowel entry (see Pubspec Injection), so the pub-add step never conflicts with the scaffold's own pubspec writes.

A project that still carries files generated by fluttersdk_artisan is a migration, not a fresh install: see Migrating from fluttersdk_artisan.


Basic Usage#

bash
dart run dowel install

Run once in a new Flutter project root. The command reads the project name from pubspec.yaml, writes the artefacts listed below, and prints a summary. After this completes, use the consumer wrapper alias:

bash
dart run dowel <cmd>

or, after the fast-CLI build finishes:

bash
./bin/dowel <cmd>

Synopsis#

Full signature as declared in lib/src/commands/install_command.dart:

text
install
  {--force : Overwrite files even when they already exist}
Flag Effect
--force Overwrite bin/dispatcher.dart, the two generated barrels, and bin/dowel even when they are already present, and skip the stop on a file generated by fluttersdk_artisan. Does not re-inject already-present pubspec entries.

Exit code 0 on success, 1 when pubspec.yaml has no name: or when a generated file still comes from fluttersdk_artisan (see below), otherwise the exit code of the chained make:fast-cli.

Stops on files from fluttersdk_artisan#

When bin/dispatcher.dart, lib/app/_plugins.g.dart or lib/app/commands/_index.g.dart still imports package:fluttersdk_artisan/, or names a class the old package exported (ArtisanCommand, ArtisanServiceProvider and the rest dowel renamed) or runArtisan, install writes nothing and exits 1. It prints every leftover it found and the migration steps, because each of those files would otherwise be skipped as already present and the build that follows would fail on its imports. install runs from the substrate itself, never through the project's bin/dispatcher.dart, so the old dispatcher cannot intercept it. The real message is quoted in Migrating from fluttersdk_artisan.


What It Writes#

install produces these artefacts in this order:

1. bin/dispatcher.dart#

A generated CLI entry point that wires the consumer's own commands and plugin providers into the dowel runtime. The file is written from the dispatcher.dart.stub template with {{ name }} substituted to the pubspec.yaml project name. Header comment: GENERATED by the `install` command. DO NOT EDIT.

Structure:

  • imports package:<name>/app/commands/_index.g.dart as consumer_commands
  • imports package:<name>/app/_plugins.g.dart as plugins
  • defines _ConsumerCommandsProvider extends DowelServiceProvider registering the consumer barrel
  • main(List<String> args) calls runDowel(args, baseProviders: [_ConsumerCommandsProvider(), ...plugins.autoDiscoveredProviders()], delegateToConsumer: false, collectMcpTools: args.isNotEmpty && args.first == 'mcp:serve')

The collectMcpTools parameter is conditionally enabled only when the command is mcp:serve, so plugin providers' MCP tools register for the server without overhead on non-MCP CLI invocations.

2. lib/app/_plugins.g.dart#

The plugins codegen barrel. Written as an empty-but-valid barrel on first install. plugin:install and plugins:refresh regenerate this file when plugins are added or removed. Never edit by hand: the source of truth is .dowel/plugins.json.

3. lib/app/commands/_index.g.dart#

The commands codegen barrel. Written as an empty-but-valid barrel on first install. make:command and commands:refresh regenerate this file as new command files appear under lib/app/commands/. Never edit by hand.

4. bin/dowel (via Fast-CLI Auto-Chain)#

A POSIX shell wrapper written by the make:fast-cli sub-command, which install calls in-process at the end of the scaffold phase. See Fast-CLI Auto-Chain for details.


Pubspec Injection#

install injects a dowel dependency into pubspec.yaml after writing the artefacts, unless dependencies or dev_dependencies already declares dowel: an existing entry keeps its constraint, whatever it is. Two injection modes when there is none:

Path-dep mode (monorepo)

When .dart_tool/package_config.json lists dowel with a relative rootUri (sibling-package monorepo workflow), install resolves the path against the consumer root and writes a path: dependency:

yaml
dependencies:
  dowel:
    path: ../dowel

A file:// absolute URI or any other absolute rootUri (the shape pub-cache produces) skips this branch and falls through to pub.dev mode.

Pub.dev mode

When no local relative-rootUri entry resolves, install injects a caret constraint on the dowel version that is running (dowel: ^<running version>), so the next dart pub get (or flutter pub get) resolves the same release.

The injection is idempotent: if pubspec.yaml already contains a dowel: key under dependencies: or dev_dependencies:, neither form is written again (regardless of --force). A plugin's pubspec section follows the same rule for its own dependencies, and plugin:uninstall leaves a dependency the project already declared in place.


Idempotency#

Re-running install without --force is a no-op when the artefacts already exist. Each file goes through a _shouldWrite(path, force) guard: if the file exists and force is false, the write is skipped and a [skip] line is printed for that artefact. The pubspec injection is always idempotent (key presence check, independent of --force).

Pass --force to overwrite all the artefacts unconditionally. Useful after renaming the project or updating the stub template to a newer version:

bash
dart run dowel install --force

--force is forwarded to the make:fast-cli auto-chain as well, so bin/dowel is rewritten and the AOT binary is recompiled from scratch.


Fast-CLI Auto-Chain#

At the end of scaffoldInto, install calls MakeFastCliCommand.scaffoldInto(root, force, ctx) in-process. This produces bin/dowel, compiles the AOT binary under .dowel/cli-bundle/, and patches .gitignore with the cache entries only (.dowel/cli-bundle*, .dowel/build.stamp* and .dowel/.dowel.lock/; a bare .dowel/ line is replaced by them, so .dowel/plugins.json and .dowel/installed/ stay trackable). The call happens only after all scaffold writes and pubspec injection succeed, so a partial failure in the scaffold phase does not leave a compiled binary that references a missing dispatcher.

The fast-CLI step is not separately gated: if dart build cli fails (e.g. the toolchain is missing or the build itself errors), make:fast-cli returns a non-zero exit code and install propagates that failure. The scaffold artefacts written before the failure remain on disk so the project is still usable via dart run dowel <cmd> (the slower fallback). Re-running install --force after fixing the underlying issue recompiles bin/dowel and the AOT cache.

See make:fast-cli for the full performance profile, cache-hit behaviour, and POSIX-only caveat.


Examples#

1. Fresh install in a new Flutter project#

bash
flutter create my_app
cd my_app
dart pub add dowel
dart run dowel install

Output (colour codes omitted):

text
✓ Created: /path/to/my_app/bin/dispatcher.dart
✓ Created: /path/to/my_app/lib/app/_plugins.g.dart
✓ Created: /path/to/my_app/lib/app/commands/_index.g.dart
 ℹ Install scaffold complete (3 written, 0 skipped). Chaining make:fast-cli for bin/dowel setup.
✓ Created: /path/to/my_app/bin/dowel
Compiling dispatcher...
Generating snapshot for dispatcher...
Generated: /path/to/my_app/.dowel/cli-bundle/bundle/bin/dispatcher

✓ dowel: ready. Run ./bin/dowel <cmd> for a startup of about 0.2 s.

2. Force-overwrite after project rename#

bash
dart run dowel install --force

Regenerates bin/dispatcher.dart with the updated project name and recompiles bin/dowel.

3. Monorepo path-dep install#

In a monorepo where dowel lives at ../dowel, run flutter pub get once to populate .dart_tool/package_config.json, then:

bash
dart run dowel install

The path-dep form is detected automatically and written to pubspec.yaml. No flag needed.


  • make:command: scaffold a single DowelCommand subclass under lib/app/commands/ and regenerate _index.g.dart.
  • plugin:install: register a third-party plugin after flutter pub add; requires the lib/app/_plugins.g.dart barrel that install writes.
  • make:fast-cli: the sub-command auto-chained by install; run it standalone to rebuild bin/dowel without touching the scaffold artefacts.
  • Getting Started: Installation: step-by-step walkthrough from dart pub add to first ./bin/dowel status for both vanilla Flutter and magic-stack projects.
  • Migrating from fluttersdk_artisan: what install stops on and the steps it prints.
esc

Search index did not load.

No match for "".

Try a class like rounded-lg or a widget like WButton.