plugin:install
Register a third-party dowel plugin into the consumer project. After adding a
package to pubspec.yaml and running flutter pub get, plugin:install wires
the plugin's DowelServiceProvider without requiring manual edits to
bin/dispatcher.dart or lib/app/_plugins.g.dart.
On this page
Basic Usage#
dart run dowel plugin:install <name>
<name> is the plugin's pubspec package name (e.g. magic_logger). The
package must be listed in pubspec.yaml and resolved via flutter pub get
before this command runs.
Pre-flight checks: the package must appear in pubspec.yaml, and
.dart_tool/package_config.json must contain the package name. Any failure
exits with code 1 before any write is attempted. A plugin without an
install.yaml also needs the scaffold from dart run dowel install
(lib/app/_plugins.g.dart); without it the command exits with code 1 and
tells you to run install first.
The command also refuses to run, with exit code 1, when
lib/app/_plugins.g.dart registers providers but .dowel/plugins.json, the
registry the barrel is generated from, is missing. Installing then would
regenerate the barrel with a single plugin and drop the rest:
lib/app/_plugins.g.dart registers providers from <imports>, but .dowel/plugins.json, the registry it is generated from, is missing. Installing now would regenerate the barrel without them. Restore .dowel/plugins.json from version control (commit it; only .dowel/cli-bundle*, .dowel/build.stamp* and .dowel/.dowel.lock/ are cache), then retry. Or delete lib/app/_plugins.g.dart, run `dart run dowel install` to write an empty one, and run plugin:install again for each plugin.
Commit .dowel/plugins.json and .dowel/installed/; only the AOT cache under
.dowel/ is gitignored.
Synopsis#
Full signature as declared in
lib/src/commands/plugin_install_command.dart:
plugin:install
{name : Plugin pubspec package name (e.g. magic_logger)}
{--bootstrap-command= : Plugin install sub-command to chain after registration}
{--use-yaml-only : Fail if install.yaml not found instead of registering the plugin directly}
{--force : Bypass conflict detection (inherited from DowelInstallCommand)}
{--dry-run : Print staged ops without writing (inherited)}
{--non-interactive : Skip prompts, use defaults (inherited)}
{--no-bootstrap : Skip post-install bootstrap hint message (inherited)}
The four inherited flags come from DowelInstallCommand.baseFlags and are
available on every install command, not only plugin:install.
| Flag | Effect |
|---|---|
--bootstrap-command=cmd |
Overrides the post-registration bootstrap hint (e.g. logger:install). |
--use-yaml-only |
Error out when no install.yaml found; no direct registration (Mode 2). |
--force |
Bypass conflict detection; overwrite user-modified files. |
--dry-run |
Print every staged op without touching disk. |
--non-interactive |
Skip interactive prompts; use defaults. Required in non-TTY environments. |
--no-bootstrap |
Suppress the post-install bootstrap hint message. |
Two Routing Modes#
The core of handle dispatches through two code paths. Mode 1 wins when an
install.yaml manifest is present; Mode 2 runs otherwise, and needs the
scaffold barrel from dart run dowel install.
Mode 1: install.yaml Manifest Flow#
Condition: resolveInstallYaml(name) returns a non-null path. The resolver
checks <plugin_root>/install.yaml first, then <plugin_root>/assets/install.yaml
(resolveInstallYaml in lib/src/commands/plugin_install_command.dart).
ManifestParser.parseFile parses the YAML into an InstallManifest.
ManifestInstaller stages InstallOperation objects on an InstallTransaction.
InstallTransaction.commit writes every file to a .tmp path first; on full
success, all .tmp files are renamed atomically. The result is one of four
classes: InstallSuccess, InstallDryRun, InstallConflict (exit code 2) and
InstallError (exit code 1). A conflict lists each file with its reason
(modified-since-last-known-stub, unmanaged-file or
unsupported-install-record); --force bypasses the check, which also switches
off every other conflict check, so read git diff afterwards. A .tmp write
failure deletes all staged temps and returns InstallError(rolledBack: true),
unless an editor-backed operation (a dependency addition, an injection) already
changed a file: those write directly while staging and sit outside the .tmp
rollback, so the result then says rolledBack: false and a partial install
record ("partial": true) lists the edits that landed, for plugin:uninstall
to reverse what it can. On InstallSuccess, the plugin entry is written to
.dowel/plugins.json and PluginsRefreshCommand regenerates
lib/app/_plugins.g.dart in-process.
Preferred authoring path: declarative, conflict-checked, dry-run-capable, and
partially reversible via plugin:uninstall (see Reversibility).
Mode 2: Direct Registration#
Condition: No install.yaml found AND lib/app/_plugins.g.dart exists at
the project root. Without that barrel the command exits with code 1 and asks
you to run dart run dowel install first.
_registerDowelProvider runs directly: writes a PluginEntry to
.dowel/plugins.json and regenerates _plugins.g.dart. No wrapper edit
occurs. Covers plugins without a manifest. Naming convention: my_plugin maps
to package:my_plugin/cli.dart and class MyPluginDowelProvider. Pass
--use-yaml-only to error out instead of reaching this path.
Examples#
1. Manifest-based plugin install (Mode 1)#
flutter pub add magic_logger
dart run dowel plugin:install magic_logger
Output:
Success: applied 4 ops; record at .dowel/installed/magic_logger.json
Bootstrap with: dowel logger:install
2. Canonical scaffold, no install.yaml (Mode 2)#
flutter pub add awesome_plugin
dart run dowel plugin:install awesome_plugin
Output:
Registered "awesome_plugin" via the dowel scaffold (no install.yaml needed).
3. Dry-run preview#
dart run dowel plugin:install magic_logger --dry-run
Output:
DryRun: previewed 4 ops; no changes written
WriteFile lib/config/logger.dart
InjectImport lib/main.dart
InjectAfterPattern lib/app/providers/app_service_provider.dart
AddPubspecAsset assets/logging/
Idempotency#
Re-running plugin:install for the same plugin is safe in both modes.
PluginsRegistryFile.addPlugin replaces by name so .dowel/plugins.json
always contains exactly one entry per plugin. ConfigEditor.addImportToFile
and insertCodeAfterPattern skip injection when the target content is already
present.
All InstallTransaction file writes use .tmp + atomic rename: concurrent
readers never observe partial state. A mid-commit .tmp write failure deletes
all staged temps and returns InstallError(rolledBack: true) before any rename
occurs, except after an editor-backed edit (see Mode 1).
A dependency the project already declares keeps its constraint: the manifest's
pubspec entries are added only when the pubspec does not list them.
Reversibility#
plugin:uninstall <name> is the complement to plugin:install. A Mode 1
manifest commit writes .dowel/installed/<name>.json, through a temp file and
a rename:
| Key | Content |
|---|---|
version |
The record format, 1. A record without it, or with absolute stubHashes keys, is not read. |
stubHashes |
The content hash of every file the install wrote, under project-relative, forward-slash keys, so a moved or re-cloned project still matches. |
ops |
Every operation with its typed payload. A dependency addition carries preExisting, true when the project declared that dependency before the install. |
partial |
Present and true only for the record of an install that failed after its editor-backed edits landed. |
Reversibility is partial: plugin:uninstall reverses the files an install
created (WriteFile, PublishFile, CopyFile) and the dependency additions
the project did not declare before (a preExisting one stays in
pubspec.yaml, and the command says which). It deletes those files without
comparing them with stubHashes, so a file edited after the install goes with
its edits: commit or copy it first. Every other operation,
each Inject* among them, is logged as skipped: remove those edits by hand.
plugin:uninstall then removes the plugin from .dowel/plugins.json and
regenerates lib/app/_plugins.g.dart. Mode 2 installs write no record, so
plugin:uninstall cannot reverse them. plugin:uninstall --dry-run previews
only the WriteFile and CopyFile deletions, so it lists fewer reversals than
the real run performs (that also covers PublishFile files and dependencies).
A record written by an older dowel is refused by both commands: plugin:install
reports a conflict on the record (unsupported-install-record) and
plugin:uninstall exits 1 with The install record <path> has no "version" (an older dowel wrote it). Re-run the install with --force to rewrite it. Run
plugin:install <name> --force once; it rewrites the record.
Related Documentation#
- plugin:uninstall: removes a plugin registered via
plugin:install, using the.dowel/installed/<name>.jsonrecord. - plugins:refresh: regenerates
lib/app/_plugins.g.dartfrom.dowel/plugins.jsonwhen the codegen barrel drifts out of sync. - install.yaml schema: full reference for the declarative manifest format consumed by Mode 1.