flutter_copilot_cli

TypeScript CLI that drives a running Flutter app via the ext.flutter.flutter_copilot.* VM service extensions registered by flutter_copilot_claw.

Think of it as an alternative to flutter_copilot_mcp that is designed for humans at a terminal and CI pipelines, not just for LLM tool-use.

Highlights (vs flutter_copilot_mcp)

Install

cd packages/flutter_copilot_cli
pnpm install
pnpm build
# optionally: pnpm link --global
# (adds both `flutter_copilot_cli` and `fcl` to your PATH)

The package exposes two bin names that point at the same binary:

• flutter_copilot_cli — full name, matches the package identifier
• fcl — short alias used throughout the docs and examples

Help output reflects whichever name you invoke.

Usage

Start an app with flutter_copilot_claw initialised:

void main() => FlutterCopilotBinding.runAppWithConfig(const MyApp());

Target resolution — no --uri needed

The CLI picks a VM Service URI from the first source that matches:

1. --uri <ws://...> — explicit
2. -i <name> — from the instance registry
3. FLUTTER_COPILOT_URI env var
4. .vm_service_uri in the current directory or any ancestor

Use --no-auto-uri to disable #3/#4 if needed.

Recommended: scripts/flutter_run.sh

The repo ships a helper that wraps flutter run and writes the detected URI to <repo_root>/.vm_service_uri:

./scripts/flutter_run.sh -d macos          # starts the app; writes .vm_service_uri
fcl doctor                                 # auto-picks the URI from that file
fcl tap --text Counter

Alternative: manual registry

fcl register demo ws://127.0.0.1:8181/abc/ws
fcl -i demo doctor
fcl -i demo elements
fcl -i demo tap --text "Increment"
fcl -i demo screenshot -o /tmp/shot.png

Real-time stream

fcl -i demo watch --logs --rebuilds --interval 500

Add --watch-uri to survive flutter run restarts — the CLI tails .vm_service_uri and transparently reconnects (with 100ms→1.6s backoff):

fcl --watch-uri watch --rebuilds
# in another terminal: ctrl-c flutter, restart it → CLI auto-reconnects

The same flag works for repl too. It's a no-op for one-shot commands and requires URI auto-detection (it refuses when --uri / -i was used).

Interactive REPL

fcl -i demo repl
fc[demo]> tap text="Increment"
fc[demo]> enter-text key=UsernameField input="demo user"
fc[demo]> screenshot output=/tmp/s.png
fc[demo]> reload

YAML playbook

# smoke.yaml
name: smoke-login
stopOnFailure: true
steps:
  - action: tap
    key: LoginBtn
  - action: enter-text
    key: UsernameField
    input: demo
  - action: wait
    ms: 300
  - action: screenshot
    output: /tmp/after-login.png
  - action: assert-element
    text: Welcome

fcl -i demo run smoke.yaml

Each step may carry a retry: { attempts, delay } block.

Android: bridge VM Service over adb reverse

When the app runs on an Android device but the VM Service is bound to the host's loopback, expose it to the device with:

fcl adb-reverse 8181
# ... later
fcl adb-reverse 8181 --remove

Fails fast if adb is not on PATH.

JSON output for scripting

fcl --json -i demo elements | jq '.elements'

Help for AI agents

fcl help-ai

Outputs the full command surface and script schema as JSON.

Roadmap (not in v1)

• record-video — needs a screencast extension on the flutter_copilot_claw side.
• pinch-zoom, press-back-button — also need claw additions.
• Process / DDS auto-discovery of VM Service URI.
• Embedded MCP server subcommand.