using-fdb

name	using-fdb
description	Uses fdb (Flutter Debug Bridge) CLI to interact with running Flutter apps on devices and simulators. Launches, hot reloads, screenshots, reads app logs (`fdb logs`) and native system logs (`fdb syslog` — Android logcat, iOS syslog, macOS log), fetches OS-level crash records (`fdb crash-report` — jetsam, LMK, native .ips), inspects widget trees, describes screens including off-screen GridView/ListView children, taps/inputs/scrolls/swipes/navigates, and forces garbage collection (`fdb gc`). Use when launching a Flutter app on device, hot reloading, taking screenshots, reading app or native system logs, diagnosing native crashes (jetsam, LMK), fetching post-mortem crash reports, inspecting or describing the UI, interacting with widgets via fdb, or forcing a GC to disambiguate live-retained vs unreachable-but-uncollected memory.
license	MIT
compatibility	opencode

Overview - skill version 1.6.4

Version check: Run fdb --version. This skill may describe unreleased branch behavior, so do not assume the published 1.6.4 release includes every command example below. To use the latest behavior from this repository, update with dart pub global activate --source git https://github.com/andrzejchm/fdb.git and refresh this skill with fdb skill.

Install

dart pub global activate --source git https://github.com/andrzejchm/fdb.git

Verify: fdb status

fdb_helper setup (required for tap, double-tap, longpress, input, scroll, scroll-to, back)

The tap, double-tap, longpress, input, scroll, scroll-to, and back commands require fdb_helper to be added to the Flutter app under test.

pubspec.yaml:

dev_dependencies:
  fdb_helper: ^1.6.4

main.dart:

import 'package:fdb_helper/fdb_helper.dart';
import 'package:flutter/foundation.dart';

void main() {
  if (!kReleaseMode) {
    FdbBinding.ensureInitialized();
  }
  runApp(MyApp());
}

After adding fdb_helper, run flutter pub get and relaunch the app.

Commands

List devices

fdb devices

Output (one line per device):

DEVICE_ID=<id> NAME=<name> PLATFORM=<targetPlatform> EMULATOR=<true|false>

Lists all devices Flutter can target: physical phones, emulators, simulators, desktop, and web.

Launch app

fdb launch --device <device_id> --project <path> [--flavor <flavor>] [--target <target>]

Output on success: APP_STARTED, VM_SERVICE_URI=..., PID=..., LOG_FILE=...

Output on failure (process exited before VM service appeared):

ERROR: flutter process exited unexpectedly
LAUNCH_ERROR=<CATEGORY>
LAUNCH_ERROR_CAUSE=<one-line description>
HINT: <remediation hint>          # omitted when category is UNKNOWN
--- log context ---
L42: <most informative log lines>
---

Known LAUNCH_ERROR categories and their meanings:

Category	Meaning
IOS_BUNDLE_ID_CLAIMED	Bundle ID registered to a different team — change or reclaim it
IOS_NO_ACCOUNT_FOR_TEAM	Apple ID for the Xcode team is not signed in on this Mac
IOS_CODESIGN_PROVISIONING	Code signing or provisioning profile failure (may include keychain issues)
IOS_BUILD_SCRIPT	An Xcode build script phase failed (CocoaPods embed, etc.)
ANDROID_INSTALL_ADB	ADB install failed — incompatible signatures, storage, or device offline
SDK_TOOLCHAIN	Flutter SDK, Android SDK, or Xcode toolchain is missing or misconfigured
FLUTTER_BUILD	Dart/Gradle compile error — fix the first error and retry
UNKNOWN	No recognised pattern matched — open LOG_FILE for full output

Find device IDs: fdb devices

Doctor pre-flight check

fdb doctor

Run this before an interaction session when you need to validate that the app is running and the environment is usable. It checks the app process, VM service, fdb_helper, platform tools, and stored device state, then prints DOCTOR_SUMMARY=pass|fail CHECKS=<n> FAILED=<n>.

Example output:

DOCTOR_CHECK=app_running STATUS=pass
DOCTOR_CHECK=vm_service STATUS=pass VM_SERVICE_URI=ws://127.0.0.1:56789/ws
DOCTOR_CHECK=fdb_helper STATUS=pass
DOCTOR_CHECK=platform_tools STATUS=warn TOOLS=xcrun,screencapture MISSING=adb HINT=adb missing — Android screenshots and interactions will fail. Install Android platform-tools.
DOCTOR_CHECK=device STATUS=pass DEVICE_ID=macos PLATFORM=darwin-x64
DOCTOR_SUMMARY=pass CHECKS=5 FAILED=0

Warnings do not make the summary fail. Failed checks include HINT=... remediation text. The command always exits 0, so parse the summary instead of relying on the process exit code.

Hot reload / restart

fdb reload    # SIGUSR1 - preserves state
fdb restart   # SIGUSR2 - resets state

Screenshot

fdb screenshot [--output <path>] [--full]

Dispatches to the right capture tool per platform: adb (Android), xcrun simctl (iOS simulator), screencapture (macOS), xdotool+import (Linux X11), Chrome DevTools Protocol (web), or fdb_helper VM extension (physical iOS, Windows, Wayland). Default output: <project>/.fdb/screenshot.png. Output is downscaled so the longest side fits within 1200px — pass --full to skip. Read the file with the Read tool to view it.

Logs

fdb logs --tag "MyTag" --last 50
fdb logs --tag "DEBUG" --last 100

Reads from the tee'd log file. Use --tag to grep for specific tags.

Native system logs (Android logcat / iOS syslog / macOS log)

fdb syslog --since 5m --last 50            # last 50 lines from the past 5 minutes
fdb syslog --predicate jetsam              # filter by substring
fdb syslog --follow                        # stream live, exits on Ctrl-C

Use this to diagnose native crashes that don't reach Crashlytics or appear in fdb logs — iOS jetsam kills, Android low-memory-killer events, kernel-level errors. Dispatches per platform: adb logcat (Android), xcrun simctl spawn <udid> log (iOS simulator), idevicesyslog (iOS physical, requires brew install libimobiledevice), or host log (macOS).

Flags:

• --since <duration> — time window (30s, 5m, 1h); default 5m. Not valid with --follow.
• --predicate <substring> — substring match across platforms (post-filtered for adb / idevicesyslog, native NSPredicate for log show).
• --last <n> — cap output to last N lines. Not valid with --follow.
• --follow — stream live, exit cleanly on Ctrl-C.

Output is the raw native log format — not parsed into fdb tokens. Errors print ERROR: ... (e.g. ERROR: idevicesyslog not found. Install: brew install libimobiledevice).

OS-level crash and OOM records

fdb crash-report                           # most recent record, last 1h
fdb crash-report --last 30m               # custom time window
fdb crash-report --all                    # all crash sources in window
fdb crash-report --app-id com.example.app # explicit bundle id / package name

Fetches jetsam kills, Android LMK events, and native crash files that never reach Crashlytics. Works after the app has died — no running session required, only .fdb/platform.txt.

App id auto-read from .fdb/app_id.txt (written by fdb launch). Pass --app-id to override.

Output tokens: CRASH_REPORT_FOUND ENTRIES=N (followed by --- / LABEL= / optional FILE= / raw text per entry) or CRASH_REPORT_NONE. Errors include install hints when a required platform tool is missing.

Widget tree

fdb tree --depth 5
fdb tree --depth 3 --user-only

Connects to VM service, prints indented widget tree. --user-only filters to project widgets.

NOTE: If this returns empty/unknown, fall back to raw websocat (see Fallback section).

Describe the current screen

Requires fdb_helper in the app (see setup section above).

fdb describe

Returns a compact, text-based snapshot of what's on screen - interactive elements with stable refs, ancestor breadcrumbs for context, and all visible text. Use this instead of a screenshot when you need to understand the UI and interact with it.

Example output:

SCREEN: Permissions
ROUTE: /settings/permissions

INTERACTIVE:
  @1 ElevatedButton "Save" key=save_btn
  ListTile "Camera · granted"
    @2 ElevatedButton "Request" key=perm_request_camera
  ListTile "Location · denied"
    @3 ElevatedButton "Request" key=perm_request_location
  Card(key=contact_card) > ListTile "John Doe"
    @4 IconButton key=call_john
    @5 IconButton key=delete_john
  @6 ListTile "Notifications · enabled" key=notif_tile

VISIBLE TEXT:
  "Manage your app permissions"
  "Permissions"

Breadcrumbs: When an interactive widget is nested inside a container that has a key or text (like a ListTile, Card, Tab), its parent context is printed above it. This tells you which list item or card a button belongs to. Widgets with no meaningful parent show no breadcrumb.

ListTile handling:

• ListTile with onTap is surfaced as its own interactive entry (e.g. @6 above)
• ListTile without onTap is NOT surfaced, but its interactive children are (e.g. @2, @3 above get their own refs with the tile as breadcrumb context)
• Display-only tiles (no onTap, no interactive children) appear only in VISIBLE TEXT

Refs are NOT stable across navigation changes - re-run fdb describe after navigating.

Widget selection

fdb select on     # enable tap-to-select overlay on device
fdb select off    # disable overlay
fdb selected      # get what widget was tapped

Tap native UI (system dialogs, permission sheets)

fdb native-tap --at 200,400    # tap at device coordinates (x,y)
fdb native-tap --x 200 --y 400 # same, two-flag form

Output: NATIVE_TAPPED=<platform> X=<x> Y=<y>

Platform dispatch:

• Android — adb shell input tap X Y. Reaches all on-screen UI including system dialogs.
• iOS simulator — falls back to fdb tap --at (in-process). Prints WARNING: to stderr. Reaches UIAlertController and other in-app native overlays. Cannot reach SpringBoard dialogs (URL scheme confirmations, OS permission prompts).
• iOS physical — not supported. Use fdb tap --at.
• macOS — not supported. Use fdb tap --at.

For iOS in-app alerts (UIAlertController):

fdb screenshot                 # locate button coordinates
fdb tap --at 285,508           # tap at those coordinates
fdb screenshot                 # verify dismissed

Tap a widget

Requires fdb_helper in the app (see setup section above).

fdb tap --key "increment_button"      # tap by widget key
fdb tap --text "Submit"               # tap by visible text
fdb tap --type "FloatingActionButton" # tap by widget type
fdb tap --at 200,400                   # tap absolute screen coordinates
fdb tap @3                            # tap by describe ref (from fdb describe)

Output: TAPPED=<type|coordinates> X=<x> Y=<y>

Long-press a widget

Requires fdb_helper in the app (see setup section above).

fdb longpress --key "photo_card"              # long-press by widget key (default 500ms)
fdb longpress --text "Hold me"               # long-press by visible text
fdb longpress --type "GestureDetector"       # long-press by widget type
fdb longpress --key "item" --duration 1000   # long-press for 1 second
fdb longpress --at 200,400 --duration 1000   # long-press coordinates for 1 second

Output: LONG_PRESSED=<type|coordinates> X=<x> Y=<y>

Double-tap a widget

Requires fdb_helper in the app (see setup section above).

fdb double-tap --key "map_widget"         # double-tap by widget key
fdb double-tap --text "Zoom here"         # double-tap by visible text
fdb double-tap --type "InteractiveViewer" # double-tap by widget type
fdb double-tap --type "InteractiveViewer" --index 1 # choose a specific match
fdb double-tap --x 200 --y 400             # double-tap at screen coordinates
fdb double-tap --at 200,400                # shorthand for --x/--y

Output: DOUBLE_TAPPED=<type> X=<x> Y=<y>

Enter text

Requires fdb_helper in the app (see setup section above).

fdb input --key "search_field" "flutter"   # type into field by key
fdb input --text "Search" "query text"     # type into field by label text
fdb input "fallback text"                  # type into focused field

Output: INPUT=<type> VALUE=<text>

Scroll

Requires fdb_helper in the app (see setup section above).

fdb scroll down              # scroll down
fdb scroll up                # scroll up
fdb scroll left              # scroll left
fdb scroll right             # scroll right
fdb scroll down --at 200,400 # scroll at specific screen coordinates

Output: SCROLLED=<DIR> DISTANCE=<n>

Scroll to widget

Requires fdb_helper in the app (see setup section above).

Scrolls the nearest Scrollable until the target widget becomes visible. Works for lazy lists (ListView.builder) where off-screen widgets don't exist in the element tree yet.

fdb scroll-to --key "list_item_42"        # scroll until widget with key is visible
fdb scroll-to --text "Item 42"            # scroll until widget with text is visible
fdb scroll-to --type "MyListItemWidget"   # scroll until widget of type is visible
fdb scroll-to --type "ListTile" --index 5 # scroll to the 6th ListTile (0-based)

Output: SCROLLED_TO=<type> X=<x> Y=<y>

Swipe (PageView, Dismissible)

Requires fdb_helper in the app (see setup section above).

Use swipe when you need to trigger PageView page changes, Dismissible dismissals, or any gesture that requires crossing a snap/dismiss threshold. Unlike scroll, swipe can target a specific widget and automatically uses 60% of the widget's dimension as the default distance — enough to cross most snap thresholds.

fdb swipe left --key "photo_card"         # swipe widget left by key
fdb swipe right --text "Next"             # swipe widget right by text
fdb swipe up --type "Dismissible"         # swipe widget up by type
fdb swipe left                            # swipe from screen center (fallback)
fdb swipe left --at 200,400              # swipe from specific coordinates
fdb swipe left --distance 400            # swipe with custom pixel distance

Output: SWIPED=<DIR> DISTANCE=<n>

Navigate back

Requires fdb_helper in the app (see setup section above).

fdb back

Calls Navigator.maybePop() on the root navigator. Returns POPPED on success, or an error if already at the root route.

Clean app data

Requires fdb_helper in the app (see setup section above).

fdb clean

Deletes all files inside the app's temporary directory (cache) and application support/documents directories. Useful before running a test scenario that requires a clean slate. The app keeps running — no restart needed.

Output: CLEANED, DIRS=<comma-separated paths>, DELETED_ENTRIES=<count>

SharedPreferences

Requires fdb_helper in the app (see setup section above).

fdb shared-prefs get <key>                          # read one key
fdb shared-prefs get-all                            # dump all keys+values as JSON
fdb shared-prefs set <key> <value>                  # write string (default)
fdb shared-prefs set <key> <value> --type bool      # write bool
fdb shared-prefs set <key> <value> --type int       # write int
fdb shared-prefs set <key> <value> --type double    # write double
fdb shared-prefs remove <key>                       # delete one key
fdb shared-prefs clear                              # delete all keys

Output tokens: PREF_VALUE=<v>, PREF_NOT_FOUND, PREF_ALL=<json>, PREF_ENTRY=<key>=<value>, PREF_SET=<key>, PREF_REMOVED=<key>, PREF_CLEARED

Use get-all to inspect current state before a test. Use set to seed feature flags or skip onboarding. Use clear to reset app state to first-run.

VM service extensions

fdb ext list                                           # list all registered ext.* extensions
fdb ext call ext.flutter.imageCache.size               # invoke and print JSON result
fdb ext call ext.flutter.platformOverride --arg value=iOS  # pass parameters
fdb ext call ext.myapp.clearAuthCache                  # invoke app-specific extension

Output of fdb ext list:

EXT_LIST_COUNT=<n>
ext.dart.io.getOpenFiles
ext.flutter.debugPaint
ext.flutter.imageCache.clear
ext.flutter.imageCache.size
ext.myapp.clearAuthCache
...

(or EXT_LIST_EMPTY when no extensions are registered)

Output of fdb ext call: pretty-printed JSON returned by the extension.

Use fdb ext list to discover what debug hooks a Flutter app has registered, then fdb ext call to invoke them. Works on any platform the VM service supports (macOS, iOS, Android). Does not require fdb_helper.

Heap memory inspection

No fdb_helper required — pure VM service, works on any platform fdb supports.

fdb mem                              # per-isolate heap totals (human-readable table)
fdb mem --json                       # same, machine-readable JSON

fdb mem profile --output before.json # capture allocation profile to file
fdb mem profile --output before.json --isolate isolates/123  # specific isolate
fdb mem profile --output before.json --all-isolates          # one file per isolate

fdb mem diff before.json after.json           # top 20 classes by instance count delta
fdb mem diff before.json after.json --all     # all changed classes
fdb mem diff before.json after.json --sort bytes  # sort by byte delta instead
fdb mem diff before.json after.json --json    # machine-readable JSON

fdb mem output:

isolate                          heapUsage    external    capacity
------------------------------------------------------------------
main                               81.0 MB      5.5 KB     89.5 MB
------------------------------------------------------------------
TOTAL                              81.0 MB      5.5 KB     89.5 MB

fdb mem profile output (one line per key):

MEM_PROFILE_SAVED=/tmp/before.json
CLASSES=6405
ISOLATE=main

fdb mem diff output:

Top 3 changed classes (by instance count delta):
   +12  ProductPageBloc                           12 -> 24
   +12  StreamSubscriptionImpl<Product>           47 -> 59
    +8  _ProductImageState                         4 -> 12

Leak-hunting workflow:

fdb mem profile --output /tmp/before.json
# ... navigate, trigger suspected leak ...
fdb mem profile --output /tmp/after.json
fdb mem diff /tmp/before.json /tmp/after.json

Forced garbage collection

No fdb_helper required — pure VM service, works on any platform fdb supports.

fdb gc           # force GC across all isolates; print human-readable summary
fdb gc --json    # same, KEY=value tokens for scripting

fdb gc output:

GC_COMPLETE HEAP_BEFORE=322.4 MB HEAP_AFTER=287.1 MB HEAP_DELTA=-35.3 MB

fdb gc --json output (one line per key):

HEAP_BEFORE=338033664
HEAP_AFTER=301020160
HEAP_DELTA=-37013504

Force GC before/after a suspected-leak navigation to remove GC noise from fdb mem readings:

fdb gc
fdb mem profile --output /tmp/before.json
# ... navigate through the suspected-leak scenario ...
fdb gc
fdb mem profile --output /tmp/after.json
fdb mem diff /tmp/before.json /tmp/after.json

Grant, revoke, or reset runtime permissions

# Grant a permission (iOS simulator or Android)
fdb grant-permission camera
# stdout: PERMISSION_GRANTED=camera

# Revoke a permission
fdb grant-permission camera --revoke
# stdout: PERMISSION_REVOKED=camera

# Reset a single permission (re-prompts on next access)
fdb grant-permission camera --reset
# stdout: PERMISSION_RESET=camera

# Reset ALL permissions for the app
fdb grant-permission --reset-all
# stdout: PERMISSION_RESET_ALL=true

# Override bundle ID / package name
fdb grant-permission --bundle com.example.app camera

Supported tokens: camera, microphone, location, location-always, contacts, contacts-read, photos, photos-add, calendar, reminders, motion, media-library, siri (iOS), notifications (Android), screen-capture (macOS).

Supported on iOS simulator and Android. Physical iOS devices are not supported. macOS supports --reset only; grant/revoke emit WARNING: and exit 1. On iOS simulator, a successful grant emits WARNING: Permission change may have terminated the app. Run \fdb reload` or `fdb launch` to restart.` on stderr.

Status / Kill

fdb status    # RUNNING=true/false, PID, VM_SERVICE_URI
fdb kill      # stop app, clean up temp files

fdb auto-locates the active .fdb/ session by walking up from the current directory, so you can run any command from a subdirectory without switching to the project root. Use --session-dir to override:

fdb --session-dir /path/to/project/.fdb status   # explicit session directory

Deep links

fdb deeplink <url>

Opens a deep link URL on the connected device. Works with Android devices and iOS simulators only.

# Custom scheme
fdb deeplink "myapp://products/123"

# Universal Link / App Link
fdb deeplink "https://example.com/products/123?ref=home"

Output on success: DEEPLINK_OPENED=<url>

Limitations:

• Physical iOS devices are not supported (Apple does not expose a CLI for opening URLs on physical devices)
• Desktop and web targets are not supported
• On iOS simulator, Universal Links (https://) may open Safari instead of the app. Use a custom URL scheme for reliable testing

Adding investigative logging

When debugging, add debugPrint() calls (NOT log() from dart:developer):

• debugPrint goes to stdout (visible in log file)
• dart:developer log() goes to DevTools only (invisible in log file)

Use consistent tags: debugPrint('[Feature-DEBUG] message'), then filter with fdb logs --tag "Feature-DEBUG".

Webview debugging

For webview issues, inject diagnostic JS via controller.evaluateJavascript():

• In onWebviewCreated - runs before page loads
• In onPageFinishedLoading - runs after page is ready

Wire up all webview callbacks for logging: onConsoleMessage, onReceivedError, onReceivedHttpError, onNavigationResponse, onCreateWindow.

Use agent-browser --headed for testing webview behavior in a real browser with JS injection.

Fallback: raw websocat

If fdb's VM service commands fail, use websocat directly:

# Get VM service URI
VM_URI=$(fdb status 2>/dev/null | grep VM_SERVICE_URI | cut -d= -f2)

# Get isolate IDs
echo '{"jsonrpc":"2.0","method":"getVM","params":{},"id":"1"}' \
  | websocat -n1 -B 10485760 "$VM_URI"

# Widget tree (use the second isolate if first returns null)
echo '{"jsonrpc":"2.0","method":"ext.flutter.inspector.getRootWidgetSummaryTree","params":{"isolateId":"isolates/<ID>","objectGroup":"g"},"id":"2"}' \
  | websocat -n1 -B 10485760 "$VM_URI"

# Enable widget selection
echo '{"jsonrpc":"2.0","method":"ext.flutter.inspector.show","params":{"isolateId":"isolates/<ID>","enabled":"true"},"id":"3"}' \
  | websocat -n1 "$VM_URI"

# Get selected widget
echo '{"jsonrpc":"2.0","method":"ext.flutter.inspector.getSelectedSummaryWidget","params":{"isolateId":"isolates/<ID>","objectGroup":"g"},"id":"4"}' \
  | websocat -n1 -B 1048576 "$VM_URI"

Key gotcha: apps have multiple isolates. Try each until one returns a non-null widget tree. Use -B 10485760 for large responses.

Agent patterns

# Standard launch + inspect workflow
DEVICE=$(fdb devices 2>/dev/null | grep '^DEVICE_ID=' | head -1 | sed 's/DEVICE_ID=\([^ ]*\).*/\1/')
fdb launch --device "$DEVICE" --project /path/to/flutter/app
fdb describe                               # compact screen snapshot — preferred over screenshot for navigation
fdb tree --depth 5 --user-only
fdb screenshot

# Describe-driven interaction workflow (requires fdb_helper in the app)
fdb describe                               # see what's on screen + get refs
# Output shows:
#   ListTile "Camera · granted"
#     @2 ElevatedButton "Request" key=perm_request_camera
# The breadcrumb tells you @2 is inside the Camera tile.
fdb tap @2                                 # tap the Request button by ref
fdb tap --key perm_request_camera          # or tap by key (more stable)
fdb describe                               # re-describe after navigation for fresh refs

# Widget interaction workflow (requires fdb_helper in the app)
fdb tap --key "submit_button"              # tap a button
fdb longpress --key "photo_card"           # long-press to open context menu
fdb screenshot                             # verify result visually
fdb input --key "search_field" "flutter"   # type into a text field
fdb tap --text "Search"                    # tap the search button
fdb wait --key "loading_spinner" --absent  # wait in-app instead of shell sleep loops
fdb scroll down                            # scroll to reveal more content
fdb scroll-to --key "list_item_42"         # scroll until a specific item is visible
fdb swipe left --key "photo_card"          # swipe a PageView card left
fdb swipe right                            # swipe from screen center right
fdb back                                   # navigate back to previous screen
fdb logs --tag "fdb_test" --last 20        # check logs after interaction

# Form fill workflow
fdb tap --key "username_field"
fdb input --key "username_field" "testuser"
fdb tap --key "password_field"
fdb input --key "password_field" "secret"
fdb tap --text "Login"
fdb screenshot

iOS simulator commands

fdb simulator controls the booted iOS simulator directly. No running app session required — commands work from any directory.

# Toggle dark/light mode
fdb simulator appearance dark
fdb simulator appearance light
fdb simulator appearance get              # → APPEARANCE=dark

# Dynamic Type size (affects all apps system-wide)
fdb simulator text-size extra-extra-extra-large
fdb simulator text-size large             # reset to default
fdb simulator text-size get              # → TEXT_SIZE=large

# Clean status bar for screenshots
fdb simulator status-bar override --time "9:41" --battery-state charged --battery-level 100 --wifi-bars 3 --cellular-bars 4 --operator "Carrier"
fdb simulator status-bar clear

# Location simulation
fdb simulator location set 48.8584,2.2945          # Eiffel Tower
fdb simulator location route "Freeway Drive"        # animate along a route
fdb simulator location route "City Run"
fdb simulator location clear

# Simulated push notification (requires notification permission in the app)
cat > /tmp/push.apns <<'EOF'
{
  "aps": { "alert": { "title": "Hello", "body": "Test notification" }, "sound": "default" },
  "deeplink": "myapp://some/path"
}
EOF
fdb simulator push /tmp/push.apns                          # auto-detects bundle ID from session
fdb simulator push --bundle-id com.example.app /tmp/push.apns  # explicit bundle ID

# NSUserDefaults — read/write/delete app settings without rebuilding
fdb simulator defaults write --bundle-id com.example.app featureFlag "true"
fdb simulator defaults read --bundle-id com.example.app featureFlag   # → true
fdb simulator defaults read --bundle-id com.example.app               # → all defaults
fdb simulator defaults delete --bundle-id com.example.app featureFlag

Output tokens:

• APPEARANCE=dark|light
• TEXT_SIZE=<size>
• STATUS_BAR_OVERRIDDEN / STATUS_BAR_CLEARED
• LOCATION_SET LAT=<lat> LON=<lon>
• LOCATION_ROUTE=<scenario>
• LOCATION_CLEARED
• PUSH_SENT BUNDLE_ID=<id>
• DEFAULTS_WRITTEN KEY=<key> VALUE=<value>
• DEFAULTS_DELETED KEY=<key>

State files

All state lives in <project>/.fdb/. fdb resolves this directory automatically by walking up from the current working directory to the nearest ancestor that contains a live .fdb/ — so you never need to cd to the project root before running a command. Pass --session-dir <path> to bypass auto-resolution entirely.

• <project>/.fdb/fdb.pid - flutter-tools process ID (the flutter run Dart VM, used for SIGUSR1/SIGUSR2 hot reload/restart and to tear down the session)
• <project>/.fdb/fdb.app_pid - app VM process ID from getVM (the actual Dart VM hosting your app, used for liveness detection on a macOS desktop target)
• <project>/.fdb/logs.txt - full app output
• <project>/.fdb/vm_uri.txt - VM service websocket URI
• <project>/.fdb/device.txt - device ID used at launch
• <project>/.fdb/platform.txt - target platform + emulator flag (written at launch, read by screenshot, syslog, and crash-report)
• <project>/.fdb/app_id.txt - app bundle id / package name (written at launch, read by crash-report)
• <project>/.fdb/screenshot.png - last screenshot