flutter_copilot_cli

npm package: https://www.npmjs.com/package/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.

Command reference

All app-driving commands accept the global flag --uri <ws://...> for explicit targeting, plus --json to emit machine-readable output. If --uri is omitted, the CLI uses FLUTTER_COPILOT_URI or the nearest .vm_service_uri. Run fcc <command> --help for per-command details, or fcc help-ai for the full machine-readable surface.

Target & session

Inspect & capture

Gestures & input

App lifecycle & automation

Install

Requires Node.js >= 18.

From npm (recommended)

# npm
npm install -g flutter_copilot_cli

# pnpm
pnpm add -g flutter_copilot_cli

# yarn
yarn global add flutter_copilot_cli

Verify the install:

fcc --version          # 1.0.3
fcc --help
flutter_copilot_cli --help    # same binary, full name

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

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

Help output reflects whichever name you invoke.

From source (for contributors)

git clone https://github.com/dust365/flutter_copilot.git
cd flutter_copilot/packages/flutter_copilot_cli
pnpm install
pnpm build
pnpm link --global    # adds both `flutter_copilot_cli` and `fcc` to your PATH

Upgrade

# npm
npm update -g flutter_copilot_cli
# or pin a specific version
npm install -g flutter_copilot_cli@latest

# pnpm
pnpm update -g flutter_copilot_cli
# or
pnpm add -g flutter_copilot_cli@latest

# yarn
yarn global upgrade flutter_copilot_cli

Check the installed version against the latest on npm:

fcc --version
npm view flutter_copilot_cli version

Uninstall

# npm
npm uninstall -g flutter_copilot_cli

# pnpm
pnpm remove -g flutter_copilot_cli

# yarn
yarn global remove flutter_copilot_cli

If you installed from source via pnpm link --global, unlink it instead:

cd packages/flutter_copilot_cli
pnpm unlink --global

Usage

Start an app with flutter_copilot_claw initialised:

void main() {
  FlutterCopilotBinding.captureLogs(() {
    FlutterCopilotBinding.ensureInitialized();
    runApp(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. FLUTTER_COPILOT_URI env var
3. .vm_service_uri in the current directory or any ancestor

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
fcc doctor                                 # auto-picks the URI from that file
fcc --uri "$(cat .vm_service_uri)" doctor  # probes only this explicit URI
fcc tap --text "点击"

Manual connection

fcc connect --uri ws://127.0.0.1:8181/abc/ws
fcc doctor
fcc get-interactive-elements
fcc tap --text "点击"
fcc take-screenshots -o /tmp/shot.png
fcc disconnect

Real-time stream

fcc 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):

fcc --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 is ignored when --uri was used).

Interactive REPL

fcc repl
fc[auto:.vm_service_uri]> tap text="点击"
fc[auto:.vm_service_uri]> enter-text focused input="demo user"
fc[auto:.vm_service_uri]> take-screenshots output=/tmp/s.png
fc[auto:.vm_service_uri]> hot-reload

YAML playbook

# smoke.yaml
name: smoke-home
stopOnFailure: true
steps:
  - action: assert-element
    text: Flutter Copilot 功能演示
  - action: tap
    text: 点击
  - action: wait
    ms: 300
  - action: take-screenshots
    output: /tmp/fcc-smoke.png
  - action: assert-element
    text: 点击

fcc run smoke.yaml

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

JSON output for scripting

fcc --json get-interactive-elements | jq '.elements'

Help for AI agents

fcc help-ai

Outputs the full command surface and script schema as JSON.