testing-with-marionette

Marionette CLI — AI Agent Reference

Marionette CLI controls Flutter apps running in debug mode. It supports multiple simultaneous app instances via a named instance registry, or direct URI connections for fully stateless operation.

Workflow

Option A: Named Instances (stateful)

1. Start your Flutter app(s) in debug mode and note VM service URI(s) (printed in console, e.g., ws://127.0.0.1:XXXXX/ws).
2. Register each app: marionette register <name> <uri>
3. Interact using: marionette -i <name> <command> [args]
4. Clean up when done: marionette unregister <name>

Option B: Direct URI (stateless)

1. Start your Flutter app in debug mode and note the VM service URI.
2. Interact directly: marionette --uri <ws-uri> <command> [args]

No registration, no cleanup, no files on disk. Each command opens a fresh WebSocket connection, executes, and disconnects.

Global Options

-i, --instance Target instance (required unless --uri is used) --uri VM service WebSocket URI — bypasses registry, mutually exclusive with --instance --timeout Connection timeout (default: 5)

Commands

register

Register a Flutter app instance.

Arguments: name Alphanumeric identifier [a-zA-Z0-9_-]+ uri VM service WebSocket URI (e.g., ws://127.0.0.1:8181/ws)

Example: marionette register my-app ws://127.0.0.1:8181/ws

Output (stdout): Registered instance "my-app" → ws://127.0.0.1:8181/ws

Output if overwriting (stderr): Updated existing instance "my-app" → ws://127.0.0.1:8181/ws

Exit codes: 0 success, 64 invalid name/usage

---

unregister

Remove a registered instance.

Arguments: name Instance name to remove

Example: marionette unregister my-app

Output (stdout): Unregistered instance "my-app".

Output if not found (stderr, exit 1): Instance "my-app" not found.

---

list

List all registered instances.