Commands

Catalog of every user-facing command shipped by fluttersdk_dusk. Thirty-four commands, grouped by intent.

Every command is invoked as dart run fluttersdk_dusk (Flutter-free wrapper at bin/fluttersdk_dusk.dart), or via the consumer-side artisan dispatcher (./bin/fsa / dart run artisan ) once the project has run dusk:install. Commands are auto-discovered through DuskArtisanProvider; nothing wires by hand.

Need a quick reminder of what a command does without leaving the terminal? Run dart run artisan list for the full registry grouped by namespace, or dart run artisan help for the per-command flag surface. This page exists for the deeper view: the boot mode, the backing VM Service extension, and the grouping rationale.

Snapshot and screenshot
Gestures
Inputs
Navigation
Find
Diagnostics
Install
CDP
Click variants
Focus and blur
Console and exceptions
Observe
Hot reload and snap

How to read this page

Each group section ships a single table with four columns:

Command is the canonical name you type after dart run fluttersdk_dusk (or via the artisan dispatcher).
Description is the one-line summary returned by the command's description getter; the same string surfaces in dart run artisan list.
Boot Mode is the CommandBoot value the dispatcher reads before invoking handle(). none means pure CLI: no VM Service connection. connected means the command dials ~/.artisan/state.json and fails fast if no app is running.
VM Extension is the ext.dusk.* method the command calls over the VM Service. none for commands that operate purely on the consumer filesystem.

Deep-dive pages exist for the seven commands whose flag surface, return shape, or composition rules outgrow a single table row. The remaining twenty-five commands share this index page; reach for dart run artisan help for their full flag surface.

Snapshot and screenshot

The two foundational read commands. dusk:snap walks the Semantics tree and emits YAML with [ref=eN] tokens that every subsequent action command consumes. dusk:screenshot captures the rendered pixel buffer over Chrome DevTools Protocol (web) or RepaintBoundary.toImage (desktop, mobile).

Command	Description	Boot Mode	VM Extension
`dusk:snap`	Capture Semantics tree YAML of the running Flutter app with [ref=eN] tokens.	connected	ext.dusk.snap
`dusk:screenshot`	Capture a screenshot of the running Flutter app to a file.	connected	ext.dusk.screenshot

Gestures

Pointer-driven actions that synthesise touch, mouse, or pen events at a widget located by ref token. All four route through the actionability gate (enabled, zero-rect, off-viewport) before the event leaves the VM.

Command	Description	Boot Mode	VM Extension
`dusk:tap`	Tap a widget by ref token (from prior dusk:snap).	connected	ext.dusk.tap
`dusk:hover`	Hover the pointer over a widget by ref token (from prior dusk:snap).	connected	ext.dusk.hover
`dusk:drag`	Drag from one widget to another using ref tokens from a prior dusk:snap.	connected	ext.dusk.drag
`dusk:scroll`	Scroll inside a scrollable widget by ref token from a prior dusk:snap.	connected	ext.dusk.scroll

Inputs

Keyboard-shaped actions. dusk:type emits a character sequence; dusk:press_key synthesises a single hardware-key event; dusk:clear empties the focused text field; dusk:select_option drives DropdownButton / PopupMenuButton; dusk:set_checkbox drives Checkbox / Switch.

Command	Description	Boot Mode	VM Extension
`dusk:type`	Type text into a focused widget by ref token.	connected	ext.dusk.type
`dusk:fill`	Focus, clear, type, and settle a text field by ref in one call (retries once on a stale handle).	connected	ext.dusk.fill
`dusk:press_key`	Synthesise a hardware-key event on the currently focused widget.	connected	ext.dusk.press_key
`dusk:clear`	Empty the text content of the focused widget by ref.	connected	ext.dusk.clear
`dusk:select_option`	Select an option in a DropdownButton or PopupMenuButton by ref token.	connected	ext.dusk.select_option
`dusk:set_checkbox`	Set the checked state of a Checkbox or Switch widget by ref.	connected	ext.dusk.set_checkbox
`dusk:wait`	Wait for a text, text-gone, or expression condition in the running app.	connected	ext.dusk.wait_for
`dusk:wait_for_network_idle`	Wait until the running app reports zero in-flight HTTP requests for a contiguous idleMs window.	connected	ext.dusk.wait_for_network_idle

Route-table manipulation against the active Navigator. dusk:modal dismisses any open modal, sheet, or dialog. dusk:close_app ends the session via SystemNavigator.pop().

Command	Description	Boot Mode	VM Extension
`dusk:navigate`	Navigate the running app to a named route via the active Navigator.	connected	ext.dusk.navigate
`dusk:navigate_back`	Pop the topmost route off the active Navigator (mirrors browser back).	connected	ext.dusk.navigate_back
`dusk:get_routes`	Print the active Navigator's route table + current location as JSON.	connected	ext.dusk.get_routes
`dusk:modal`	Dismiss all open modals, bottom sheets, and dialogs in the running app.	connected	ext.dusk.dismiss_modals
`dusk:reset_overlays`	Reset to a clean screen: dismiss modals + Escape + Cancel-tap fallback (idempotent).	connected	ext.dusk.reset_overlays
`dusk:close_app`	Gracefully close the running app via SystemNavigator.pop().	connected	ext.dusk.close_app

Find

The Playwright Locator surface: mint a re-resolvable q handle backed by text, semanticsLabel, or key predicates. Every action call against a q handle re-walks the live tree, so the handle survives intermediate rebuilds.

Command	Description	Boot Mode	VM Extension
`dusk:find`	Mint a re-resolvable q-handle by text / semanticsLabel / key (Playwright Locator pattern).	connected	ext.dusk.find

Diagnostics

Pure-CLI checks that verify the consumer wiring and the running session health. Neither command dials the VM Service.

Command	Description	Boot Mode	VM Extension
`dusk:doctor`	Verify dusk plugin runtime + consumer wiring health	none	none

Install

The one-shot bootstrap. Injects three lines into the consumer's lib/main.dart and is otherwise idempotent. No bin/artisan.dart scaffold; fluttersdk_dusk ships its own Flutter-free CLI entry point.

Command	Description	Boot Mode	VM Extension
`dusk:install`	Wire DuskPlugin.install() into lib/main.dart AND chain artisan install + plugin:install so ./bin/fsa surfaces all 34 dusk:* commands (idempotent on re-run; Phase 2 chain is best-effort).	none	none

CDP

Chrome DevTools Protocol commands that manipulate the browser viewport directly. Web target only; desktop and mobile no-op gracefully.

Command	Description	Boot Mode	VM Extension
`dusk:device`	Emulate a device profile (viewport + DPR + touch + user agent) via Chrome DevTools Protocol.	connected	none (CDP direct)
`dusk:resize`	Resize the running Flutter web app viewport via Chrome DevTools Protocol.	connected	none (CDP direct)

Click variants

Pointer gestures that go beyond the primary tap. All four route through the actionability gate.

Command	Description	Boot Mode	VM Extension
`dusk:dblclick`	Fire a double-click at the widget identified by a snapshot ref.	connected	ext.dusk.tap
`dusk:triple_click`	Fire three primary clicks (~100ms apart) at the widget identified by --ref.	connected	ext.dusk.tap
`dusk:right_click`	Fire a right (secondary mouse button) click at the widget identified by --ref.	connected	ext.dusk.tap

Focus and blur

Keyboard-focus shaping. dusk:focus requests focus on a ref; dusk:blur releases the currently focused widget.

Command	Description	Boot Mode	VM Extension
`dusk:focus`	Request keyboard focus on the widget identified by --ref.	connected	ext.dusk.focus
`dusk:blur`	Remove keyboard focus from the currently-focused widget.	connected	ext.dusk.blur

Console and exceptions

Diagnostics readers backed by dusk's own in-package capture plus an optional telescope augmentation.

dusk:console reads from dusk's in-package debugPrint ring buffer (populated by installLogCapture(), wired by DuskPlugin.install()). This buffer captures every call that routes through the debugPrint global callback (debugPrint(...), print(...), and any Flutter framework path that calls debugPrint). It does NOT capture direct dart:developer log() calls that bypass debugPrint; those require fluttersdk_telescope's LogWatcher. When telescope is wired the two sources are merged and deduped; telescope also adds package:logging (Logger.root.onRecord) and any other watcher it ships.

dusk:exceptions is similar: dusk's own FlutterError.onError capture (non-fatal errors including overflow) is always present; telescope augments when wired.

The --since= flag on dusk:exceptions (and the matching since param on dusk_exceptions MCP) lets agents compute true before/after deltas: record the time before an action, then call dusk:exceptions --since= afterwards to see only exceptions raised by that action.

Command	Description	Boot Mode	VM Extension
`dusk:console`	Read recent log entries (in-package debugPrint capture; augmented by telescope when wired).	connected	ext.dusk.console
`dusk:exceptions [--limit=] [--since=]`	Read recent exception entries (in-package FlutterError capture + telescope when wired). Optionally filter to entries strictly after `--since`.	connected	ext.dusk.exceptions

Observe

The Stagehand observe-once-act-many surface. Returns a structured candidate list of every interactive widget on screen; the agent decides which refs to act on. No server-side LLM.

Command	Description	Boot Mode	VM Extension
`dusk:observe`	Return a structured candidate list of every interactive widget on screen (Stagehand observe-once-act-many; no server-side LLM).	connected	ext.dusk.observe

Hot reload and snap

The single-round-trip composite that hot-reloads the running app and then captures snapshot, screenshot, and recent exceptions in one shot. Dispatched via the artisan: substrate routing prefix to avoid a same-isolate deadlock.

Command	Description	Boot Mode	VM Extension
`dusk:hot_reload_and_snap`	Hot reload the running app, then capture snapshot + screenshot + recent exceptions in a single round-trip.	connected	artisan:reload + ext.dusk.snap

Boot mode and deep-dives

Two of thirty-four commands run with CommandBoot.none (dusk:install, dusk:doctor). Every other command is CommandBoot.connected: it dials the VM Service URI in ~/.artisan/state.json and fails fast when the running app cannot be reached.

Nine commands earn their own pages: dusk:install, dusk:snap, dusk:tap, dusk:fill, dusk:reset_overlays, dusk:screenshot, dusk:find, dusk:doctor, dusk:observe. Slug rule: the URL replaces the : separator with -. The remaining twenty-five commands share this index page; reach for dart run artisan help for their full flag surface.