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: