FlutterSDK Artisan

Artisan

Composable CLI framework and stdio MCP server for Flutter and Dart.

Scaffolding, code generation, transactional plugin installs, hot reload orchestration, REPL, and AI agent tool surfaces in one binary.

Documentation · pub.dev · Issues

---

Why Artisan?

Dart's CLI surface is fragmented. Every package invents its own install ritual, its own scaffold script, its own hand-edited entry point. A team that adopts five tools ends up with five bin/*.dart wrappers, five README install sections, and five chances for a bad merge to silently break the build. AI agents that want to drive the running app reach for ad hoc shell scripts because there is no shared tool surface.

Artisan fixes this. One binary registers every command, one protocol describes every plugin install, and one stdio MCP server exposes the whole stack to AI agents.

# Before, the painful manual setup ritual

edit pubspec.yaml # add the plugin dependency edit bin/ .dart # wire the provider edit lib/main.dart # register the config factory edit android/app/src/AndroidManifest.xml # add the permission edit ios/Runner/Info.plist # add the entry write .env stub # remember which keys restart the app and hope nothing collided

# After, the Artisan way

dart pub add fluttersdk_artisan dart run fluttersdk_artisan install dart run fluttersdk_artisan plugin:install

If you know php artisan, you already know the verb shape. The implementation is pure Dart 3.4+, no Flutter runtime dependency in the framework core.

Features

Quick Start

1. Install and scaffold

dart pub add fluttersdk_artisan

dart run fluttersdk_artisan install

install writes bin/dispatcher.dart (the consumer entry that calls runArtisan(...)) plus barrels (lib/app/_plugins.g.dart, lib/app/commands/_index.g.dart), then auto-chains make:fast-cli so bin/fsa is ready immediately. Re-running is idempotent, pass --force to overwrite.

After scaffold, run any built-in command via the consumer wrapper:

dart run artisan list

dart run artisan doctor dart run artisan start --device=chrome

2. Install a plugin

dart pub add awesome_plugin

dart run fluttersdk_artisan plugin:install awesome_plugin

Plugins ship either an install.yaml manifest (declarative, walked by ManifestInstaller) or a procedural ArtisanInstallCommand subclass that drives PluginInstaller directly. Either way, the registry records every applied operation so a future plugin:uninstall can reverse them safely.

Plugin commands surface automatically. After installing fluttersdk_dusk, dart run artisan list shows the new dusk:* entries under their own namespace section.

3. Wire the MCP server for your AI agent

./bin/fsa mcp:install

or, on Windows / when bin/fsa is absent:

dart run fluttersdk_artisan mcp:install

mcp:install writes (or updates) the mcpServers.fluttersdk entry in .mcp.json. After install, reconnect the MCP client once (for Claude Code: /mcp reconnect fluttersdk). The server boots in stdio JSON-RPC mode and exposes 10 substrate tools (artisan_start, artisan_stop, artisan_status, artisan_logs, artisan_restart, artisan_reload, artisan_hot_restart, artisan_doctor, artisan_list, artisan_tinker) plus any plugin-contributed tools.

Read the full setup walkthrough at MCP setup guide.

Commands

Artisan ships 22 built-in commands across 6 namespaces. Every command is a final class X extends ArtisanCommand with a signature string and a handle() method.

Highlights:

# Lifecycle

dart run artisan start --device=chrome # spawn flutter run, record the session under ~/.artisan/sessions/ / dart run artisan reload # send r (hot reload) via FIFO bridge to detached process dart run artisan hot-restart # send R (hot restart, drops Dart state)

Scaffolding

dart run artisan make:plugin awesome # 7-file plugin skeleton, auto-upgrades to magic-mode when applicable dart run artisan make:command Greet # context-aware: plugin vs consumer context, auto-registers in provider dart run artisan make:fast-cli # compile artisan to native binary at bin/fsa (~50ms startup vs ~3s)

Introspection

dart run artisan tinker # connected REPL against the running VM dart run artisan tinker --eval='1 + 1' # one-shot evaluation flag for automation dart run artisan doctor # preflight checks: flutter + dart on PATH, default port availability

Full command catalog and per-command flag reference at commands catalog.

Writing your own command

make:command scaffolds a final class extending ArtisanCommand and auto-registers it in the nearest service provider. The signature DSL parses arguments and flags from one string, the handle() method receives a typed ArtisanContext:

final class GreetCommand extends ArtisanCommand {

@override String get signature => 'greet {name} {--shout}';

@override String get description => 'Greet a person by name.';

@override Future handle(ArtisanContext context) async { final name = context.input.argument('name'); final shout = context.input.option('shout') == 'true'; final greeting = shout ? 'HELLO, ${name.toUpperCase()}!' : 'Hello, $name'; context.output.success(greeting); return 0; } }

For cases the signature DSL cannot express (positional rest, mutually exclusive flag groups), override void configure(ArgParser parser) and read from context.input.results directly. Signature DSL grammar at signature DSL reference.

Plugin Protocol

Artisan plugins declare their install footprint in install.yaml, a declarative manifest walked by ManifestInstaller. The manifest supports publish (files to copy), magic.provider plus magic.configFactory plus magic.routes (framework wiring), native.android (permissions, metaData, gradle plugins, gradle dependencies), native.ios and native.macos (plist entries, pod entries), native.web (head injections, meta tags), env (environment variable declarations with defaults), prompts (interactive install prompts), placeholders (token resolution from prompt answers), and bootstrap_command (post-install hint). Schema reference at install.yaml schema.

A minimal install.yaml looks like this:

publish:

• from: stubs/config.dart to: lib/config/awesome.dart

magic: provider: package:awesome/awesome_provider.dart configFactory: package:awesome/config.dart

native: android: permissions:

• android.permission.INTERNET ios: plistEntries: NSCameraUsageDescription: "We need the camera to scan codes."

env: AWESOME_API_KEY: default: "" comment: "API key for awesome.example.com"

bootstrap_command: "Run dart run artisan awesome:bootstrap after install."

For plugins that need runtime branching the YAML schema cannot express, subclass ArtisanInstallCommand and drive PluginInstaller directly. The DSL exposes file operations (writeFile, publishConfig, mergeJson), source-injection operations (injectImport, injectBefore, injectAfter, injectProvider, injectConfigFactory, injectRoute), native operations (injectAndroidPermission, injectIosPlistEntry, and friends), and environment operations (injectEnvVar). Every operation is deferred and batched, nothing writes until commit(dryRun:, force:) fires:

final class AwesomeInstallCommand extends ArtisanInstallCommand {

@override String get signature => 'awesome:install';

@override Future handle(ArtisanContext context) async { final apiKey = await installer.ask('Enter the awesome API key:'); installer ..injectImport('lib/main.dart', 'package:awesome/awesome.dart') ..injectConfigFactory('Awesome.configFactory') ..injectEnvVar('AWESOME_API_KEY', defaultValue: apiKey) ..injectAndroidPermission('android.permission.INTERNET');

final result = await installer.commit(dryRun: false, force: false); return result is Success ? 0 : 1; } }

Full DSL reference at PluginInstaller DSL reference.

Operations are idempotent (lookahead-anchored regex skips when the target code is already present), atomic (every write goes through .tmp plus atomic rename so concurrent readers never see partial state), and re