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
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/<custom>.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 <name>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.
| Feature | Description | |
|---|---|---|
| 🎼 | Command Registry | ArtisanRegistry collects commands from every registered ArtisanServiceProvider, collision-detected at boot |
| 🧰 | 22 Built-in Commands | Lifecycle, scaffolding, plugin management, MCP, introspection, codegen, one binary |
| ✍️ | Signature DSL | String get signature => 'cmd:name {arg} {--flag}', Dart 3 record-style parser, ArgParser fallback when needed |
| 🤖 | MCP Server | Stdio JSON-RPC server built on dart_mcp, exposes substrate and plugin tools to AI agents |
| 🌳 | Magic-Free Path | install writes a canonical wrapper for plain Flutter and Dart projects, no framework dependency |
| 🔌 | Plugin Protocol | install.yaml declarative manifest plus PluginInstaller fluent DSL escape hatch |
| 🔄 | Idempotent Installs | Lookahead-anchored regex injection, replace-by-name registry, re-running an install is a safe no-op |
| ↩️ | Reversible Ops | Every applied operation is recorded under .artisan/installed/<plugin>.json, plugin:uninstall walks it in reverse |
| 🪞 | VM Service Hooks | tinker, reload, hot-restart drive the running Flutter VM directly over ext.* extensions |
| 🎯 | Context-Aware Generators | make:command detects plugin vs consumer context, make:plugin upgrades to magic-mode automatically |
| 🧪 | Testable Primitives | VirtualFs plus InMemoryFs, InstallContext.test, ArtisanContext.bare, BufferedOutput capture |
dart pub add fluttersdk_artisan
dart run fluttersdk_artisan installinstall 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=chromedart pub add awesome_plugin
dart run fluttersdk_artisan plugin:install awesome_pluginPlugins 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.
./bin/fsa mcp:install
# or, on Windows / when bin/fsa is absent:
# dart run fluttersdk_artisan mcp:installmcp: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.
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.
| Namespace | Count | Commands |
|---|---|---|
| Lifecycle | 7 | start, stop, status, logs, restart, reload, hot-restart |
| Scaffolding | 4 | make:plugin, make:command, make:fast-cli, install |
| Plugin Management | 3 | plugin:install, plugin:uninstall, plugins:refresh |
| MCP | 3 | mcp:serve, mcp:install, mcp:uninstall |
| Introspection | 4 | help, list, doctor, tinker |
| Codegen | 1 | commands:refresh |
Highlights:
# Lifecycle
dart run artisan start --device=chrome # spawn flutter run, record VM Service URI to ~/.artisan/state.json
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 availabilityFull command catalog and per-command flag reference at commands catalog.
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<int> 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.
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<int> 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 reversible (each applied operation is recorded under .artisan/installed/<plugin>.json with a content hash for tamper detection on uninstall).
The same binary that runs CLI commands also serves Model Context Protocol tools over stdio JSON-RPC. No separate process, no extra package. The server is built on the official dart_mcp SDK and surfaces two tool layers.
Substrate tools (10 always-on). A curated subset of the artisan CLI surfaces as MCP tools so an AI agent can bootstrap the Flutter app without leaving the chat: artisan_start, artisan_stop, artisan_status, artisan_logs, artisan_restart, artisan_reload, artisan_hot_restart, artisan_doctor, artisan_list, artisan_tinker. Dispatch runs in-process via the registry; only artisan_tinker requires a running VM Service. Per-command inputSchema is byte-verified against the underlying command's configure(ArgParser) so the wire contract cannot drift from the CLI surface.
Plugin tools. Contributed by ArtisanServiceProvider.mcpTools() overrides. Dispatch routes through ext.* VM Service extensions. The official sibling plugins maintain their own MCP tool catalogs on dedicated reference pages:
| Plugin | MCP tool reference |
|---|---|
fluttersdk_dusk |
fluttersdk.com/dusk/mcp/tool-reference |
fluttersdk_telescope |
fluttersdk.com/telescope/mcp/tool-reference |
A three-layer filter pipeline (.artisan/mcp.json file, ARTISAN_MCP_* env vars, CLI flags on mcp:serve) lets operators allow or deny tools and packages with Cargo-style precedence, deny wins at every layer. Worked example:
# Env (process-scoped, overrides file)
export ARTISAN_MCP_PACKAGES_DENY=fluttersdk_telescope
# CLI (session-scoped, overrides env)
dart run fluttersdk_artisan mcp:serve --exclude-tool artisan_stopResult: the Telescope package is removed by the file, also denied by the env (union is idempotent), and artisan_stop is removed by the CLI flag for this session.
After mcp:install writes the client config entry, every MCP-capable agent can spawn the server on demand:
// .mcp.json (managed by mcp:install)
{
"mcpServers": {
"fluttersdk": {
"command": "./bin/fsa",
"args": ["mcp:serve"],
"cwd": "."
}
}
}When bin/fsa is absent or on Windows, mcp:install writes {"command": "dart", "args": ["run", ":dispatcher", "mcp:serve"]} instead.
When ~/.artisan/state.json is absent at initialize time (no Flutter app running), the server stays online with the 10 substrate tools available and 0 plugin tools registered. On the next tools/call requiring VM Service, the server lazy-reconnects via a memoized in-flight future so MCP clients survive the natural dev cycle of starting and stopping the Flutter app without reconnecting.
Setup walkthrough at MCP setup guide. Full tool reference at tool reference.
Artisan is subsystem-first under lib/src/, every directory owns a single concern:
lib/
├── artisan.dart # Single barrel, re-exports the full public API
├── fluttersdk_artisan.dart # Convention sibling, re-exports the same surface
└── src/
├── console/ # ArtisanApplication, ArtisanRegistry, CommandSignature DSL, ArtisanContext
├── commands/ # 21 built-in commands, one final class per file
├── installer/ # PluginInstaller DSL, ManifestInstaller, InstallTransaction, sealed InstallOperation
├── mcp/ # McpServer, McpToolDescriptor, McpFilterConfig (3-layer filter pipeline)
├── helpers/ # FileHelper, ConfigEditor, MainDartEditor, EnvEditor, PlistWriter, StringHelper
├── stubs/ # StubLoader, asset bundle plus filesystem resolution
├── state/ # StateFile, JSON persistence for start, stop, status, mcp:serve discovery
├── tinker/ # Connected REPL primitives over ext.tinker.evaluate
└── vm/ # VmServiceClient, wraps package:vm_service, DDS-aware, no isolate-id cache
Flow at boot:
runArtisan(args)
↓
ArtisanApplication.create(providers, builtins)
↓
ArtisanRegistry.registerAll(providers + builtins) # collision-detected
↓
[CLI path] dispatch by signature OR [MCP path] collectMcpTools then serve stdio
↓
ArtisanCommand.handle(ArtisanContext)
Every public type is a final class. Sealed dispatch over Dart 3 exhaustiveness wherever an op set or result set is closed (InstallOperation has 26 sealed subclasses, TransactionResult has 4). New ops or result variants force every dispatcher to update, no silent drift.
Use Artisan with AI coding assistants like Claude Code, Cursor, or GitHub Copilot. The MCP server gives the agent direct tool access: start the Flutter app, drive widget interactions over Dusk, inspect HTTP traffic over Telescope, evaluate Dart expressions over Tinker, all without spawning shells or pattern-matching log output.
A typical agent session looks like this:
[agent] artisan_doctor // verify toolchain
[agent] artisan_start { device: chrome } // launch the app
[agent] <fluttersdk_dusk tool> // capture Semantics tree, drive interaction
[agent] <fluttersdk_telescope tool> // inspect HTTP, logs, exceptions
[agent] artisan_tinker { eval: "User.find(1)" } // poke the running VM
[agent] artisan_stop // tear down
See each plugin's MCP tool reference for the current tool catalog (fluttersdk_dusk, fluttersdk_telescope).
For agents that read structured project context at attach time, the canonical entry point is llms.txt at the repo root (also published at https://fluttersdk.com/artisan/llms.txt). It enumerates the command surface, the plugin protocol, and the MCP tool catalog in agent-readable form.
Skill files and per-agent setup recipes: fluttersdk/ai.
Full docs with live examples at fluttersdk.com/artisan.
| Topic | |
|---|---|
| Getting Started | Overview, requirements, first command |
| Installation | dart pub add fluttersdk_artisan plus consumer scaffold |
| Quickstart | The 3-step path from empty repo to running MCP server |
| Commands | The 21 built-in commands, grouped by namespace |
| Signature DSL | Argument and flag declaration grammar |
| Plugin Authoring | The 5-step plugin authoring flow |
| install.yaml Schema | Every section, every key, every example |
| PluginInstaller DSL | The procedural escape hatch reference |
| MCP Overview | Substrate plus plugin tool layers, soft-fail lifecycle |
| MCP Setup | Per-client install (Claude Code, Cursor, Continue) |
| MCP Tool Reference | Every tool, every input schema, every example call |
git clone https://github.com/fluttersdk/artisan.git
cd artisan && dart pub get
dart test && dart analyzeThe baseline is roughly 1070 tests green on the touched-files scope. New behavior ships with the matching test (red, green, refactor). dart format lib/ test/ bin/ must produce no diff and dart analyze must report zero issues across lib/, test/, and bin/.
Before opening a pull request, also run:
dart format lib/ test/ bin/ # zero diff
dart analyze # zero issues
dart pub publish --dry-run # validate the publish archiveThe publish archive must stay under 500 KB compressed. The .pubignore excludes example/, example_magic/, build/, coverage/, and editor scaffolding from the pub archive, extend it if you add new top-level directories that should not ship.
Report a bug · Request a feature
MIT, see LICENSE for details.
Built with care by FlutterSDK
If Artisan saves you time, give it a star, it helps others discover it.