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/<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.

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/<project>/
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<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.

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<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).

MCP Server

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:

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:

// .artisan/mcp.json
{
  "packages": { "deny": ["fluttersdk_telescope"] }
}

# 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_stop

Result: 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 the host is Windows, where the POSIX shim never applies), mcp:install writes {"command": "dart", "args": ["run", ":dispatcher", "mcp:serve"]} instead. Pass --invocation=<executable> to override the fallback entry point: mcp:install then writes {"command": "dart", "args": ["run", "<executable>", "mcp:serve"]}, which is the correct shape when the consumer's entry point is a plugin wrapper rather than the generic :dispatcher (for example, dart run fluttersdk_artisan mcp:install --invocation=fluttersdk_dusk). Precedence: if the host is POSIX and bin/fsa is present then bin/fsa wins, otherwise --invocation wins when supplied, otherwise the :dispatcher default applies.

When no session is recorded for the project 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.

Architecture

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.

AI Agent Integration

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.

Documentation

Full docs with live examples at fluttersdk.com/artisan.

Contributing

git clone https://github.com/fluttersdk/artisan.git
cd artisan && dart pub get
dart test && dart analyze

The 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 archive

The 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

License

MIT, see LICENSE for details.

_{Built with care by FlutterSDK
If Artisan saves you time, give it a star, it helps others discover it.}