Managing Simulators

FlowDeck CLI provides comprehensive simulator management capabilities, allowing you to list, create, rename, boot, and manage iOS simulators without leaving your terminal.

# Show the simulator command overview and common workflows
flowdeck simulator --examples

Managing Simulators

List All Simulators

flowdeck simulator list

Filter by Platform

flowdeck simulator list --platform iOS
flowdeck simulator list --platform tvOS
flowdeck simulator list --platform watchOS
flowdeck simulator list --platform visionOS

Show Only Available Simulators

flowdeck simulator list --available-only

JSON Output

flowdeck simulator list --json

Example output:

[
  {
    "name": "iPhone 16 Pro",
    "udid": "12345678-1234-1234-1234-123456789ABC",
    "platform": "iOS",
    "osVersion": "18.0",
    "state": "Booted",
    "isAvailable": true,
    "lastBootedAt": 800955104,
    "deviceTypeIdentifier": "com.apple.CoreSimulator.SimDeviceType.iPhone-16-Pro",
    "runtimeIdentifier": "com.apple.CoreSimulator.SimRuntime.iOS-18-0"
  },
  {
    "name": "iPhone 16",
    "udid": "23456789-2345-2345-2345-23456789ABCD",
    "platform": "iOS",
    "osVersion": "18.0",
    "state": "Shutdown",
    "isAvailable": true,
    "deviceTypeIdentifier": "com.apple.CoreSimulator.SimDeviceType.iPhone-16",
    "runtimeIdentifier": "com.apple.CoreSimulator.SimRuntime.iOS-18-0"
  }
]

Booting & Shutting Down

Boot a Simulator

flowdeck simulator boot <UDID>

Shutdown a Simulator

flowdeck simulator shutdown <UDID>

Open Simulator.app

flowdeck simulator open

Creating Simulators

Create a New Simulator

flowdeck simulator create \
  --name "My Test iPhone" \
  --device-type "iPhone 15 Pro" \
  --runtime "iOS 17.2"

Find Available Options

# List available device types
flowdeck simulator device-types

# List installed runtimes
flowdeck simulator runtime list

# List downloadable runtimes
flowdeck simulator runtime available

See Runtimes for install/remove workflows and the full runtime command reference.

Cloning Simulators

Duplicate an existing simulator with all its settings and data:

flowdeck simulator clone "iPhone 16 Pro" -n "iPhone 16 Pro Copy"

Clone by UDID

flowdeck simulator clone A7D19B36-1234-5678-ABCD-123456789ABC -n "My Clone"

Use the Clone

# Boot the clone
flowdeck simulator boot "iPhone 16 Pro Copy"

# Run your app on it
flowdeck run -S "iPhone 16 Pro Copy"

Cloning is faster than creating a new simulator when you want an identical copy of a configured environment, including installed apps, saved state, and settings.

Renaming Simulators

Change a simulator’s display name without creating a new device. The UDID stays the same, so saved destinations, scripts, and flowdeck config entries that use the UDID keep working.

# Rename by current name
flowdeck simulator rename "iPhone 16" "My CI Device"

# Rename by UDID
flowdeck simulator rename A7D19B36-1234-5678-ABCD-123456789ABC "My iPhone"

# JSON output
flowdeck simulator rename "iPhone 16" "My CI Device" --json

flowdeck simulator rename --examples

JSON output:

{
  "success": true,
  "type": "simulator_rename",
  "udid": "A7D19B36-1234-5678-ABCD-123456789ABC",
  "name": "My CI Device"
}

A successful rename emits a simulator catalog-change wakeup so the macOS app’s destination pickers refresh.

Prefer renaming by UDID when more than one simulator shares the same name. flowdeck simulator list --json is the source for the UDID.

Deleting Simulators

Delete by UDID

flowdeck simulator delete <UDID>

Delete Unavailable Simulators

Remove all simulators that are no longer available:

flowdeck simulator delete --unavailable

Prune Stale Simulators

Delete simulators that have never been booted, have not been booted in 90+ days, or are unavailable:

flowdeck simulator prune

Screenshots

Capture a screenshot (and accessibility tree when needed) via UI automation:

# Start background session capture (trees + screenshots)
flowdeck ui simulator session start

# One-off screenshot + accessibility tree
flowdeck ui simulator screen

# Tree-only output (no screenshot bytes)
flowdeck ui simulator screen --tree --json

See UI Automation for more screenshot options, including --optimize for AI-friendly output.

FlowDeck’s UI automation is a core CLI feature (not a simulator subcommand) that targets iOS simulators. See the UI Automation overview for examples and the full command reference for all commands and flags.

Device Orientation

Get Current Orientation

# Plain text (default — no subcommand needed)
flowdeck simulator orientation -S "iPhone 16"

# JSON output
flowdeck simulator orientation -S "iPhone 16" --json

# Explicit subcommand
flowdeck simulator orientation get -S "iPhone 16" --json

Reads the physical orientation directly from the simulator — no Accessibility or Screen Recording permissions required. Reflects changes from both programmatic rotation and manual rotation via the Simulator app’s Hardware menu. Possible values: portrait, portrait-upside-down, landscape-left, landscape-right Example JSON output:

{
  "schema": "flowdeck.simulator",
  "schemaVersion": "1.0.0",
  "success": true,
  "type": "orientation_get",
  "orientation": "landscape-left",
  "udid": "12345678-1234-1234-1234-123456789ABC"
}

Set Orientation

flowdeck simulator orientation set portrait -S "iPhone 16"
flowdeck simulator orientation set landscape-left -S "iPhone 16"
flowdeck simulator orientation set landscape-right -S "iPhone 16"
flowdeck simulator orientation set portrait-upside-down -S "FlowDeck-Diag-iPad"

# JSON output
flowdeck simulator orientation set landscape-left -S "iPhone 16" --json

# Send the rotation event and return immediately
flowdeck simulator orientation set landscape-left -S "iPhone 16" --no-wait

Sends a rotation event to the simulator and, by default, polls until the physical and visual orientation match the requested value (up to 30 seconds). Returns the confirmed orientation, not just the requested one, and sets confirmed: true in JSON output once verified. Pass --no-wait when you want the command to return as soon as the rotation event is delivered. This is useful for UI surfaces that rotate their local simulator frame immediately and do not need to block on CoreSimulator’s delayed visual confirmation. success stays true on this path since the event was dispatched without error, but confirmed is always false — nothing was verified.

Rotation only takes effect if the front-most app supports the target orientation. If the app does not support the requested orientation, the command reports the orientation that was actually applied.

portrait-upside-down is not supported on iPhone simulators. Use an iPad simulator for upside-down orientation checks.

Hardware and Debug Controls

# Hardware buttons
flowdeck simulator button home -S "iPhone 16"
flowdeck simulator button swipe-home -S "iPhone 16"
flowdeck simulator button app-switcher -S "iPhone 16"
flowdeck simulator button side-button --hold 1.0 -S "iPhone 16"
flowdeck simulator button siri -S "iPhone 16"

# Runtime diagnostics
flowdeck simulator memory-warning -S "iPhone 16"
flowdeck simulator ca-debug blended on -S "iPhone 16"
flowdeck simulator ca-debug offscreen off -S "iPhone 16"

Supported CoreAnimation debug options: blended, copies, misaligned, offscreen, slow-animations.

Accessibility & Localization

Dynamic Type (Content Size)

# Read the current content size category
flowdeck simulator content-size -S "iPhone 16"
flowdeck simulator content-size get -S "iPhone 16" --json

# Set a category
flowdeck simulator content-size set large -S "iPhone 16"
flowdeck simulator content-size set accessibility-extra-large -S "iPhone 16"

# Step one category larger or smaller
flowdeck simulator content-size set increment -S "iPhone 16"
flowdeck simulator content-size set decrement -S "iPhone 16"

# Reset to the iOS default (large)
flowdeck simulator content-size reset -S "iPhone 16"

Valid categories: extra-small, small, medium, large, extra-large, extra-extra-large, extra-extra-extra-large, accessibility-medium, accessibility-large, accessibility-extra-large, accessibility-extra-extra-large, accessibility-extra-extra-extra-large. Takes effect immediately for apps that honor UIContentSizeCategory.

Increase Contrast

flowdeck simulator increase-contrast -S "iPhone 16"
flowdeck simulator increase-contrast set enabled -S "iPhone 16"
flowdeck simulator increase-contrast set disabled -S "iPhone 16"
flowdeck simulator increase-contrast reset -S "iPhone 16"     # Back to disabled

Language & Locale

# Read the current language and locale
flowdeck simulator language -S "iPhone 16"
flowdeck simulator language get -S "iPhone 16" --json

# Switch the system language (locale follows the language code)
flowdeck simulator language set fr -S "iPhone 16"

# Switch language and locale explicitly
flowdeck simulator language set de --locale de_DE -S "iPhone 16"

# Reset to the device default language/locale
flowdeck simulator language reset -S "iPhone 16"

Changing or resetting the language reboots a booted simulator automatically so the change takes effect across the system. A shut-down simulator applies the change on its next boot. Appearance also supports flowdeck simulator appearance reset (back to light).

Reduce Motion

flowdeck simulator reduce-motion -S "iPhone 16"
flowdeck simulator reduce-motion set enabled -S "iPhone 16"
flowdeck simulator reduce-motion set disabled -S "iPhone 16"
flowdeck simulator reduce-motion reset -S "iPhone 16"     # Back to disabled

Reduce Transparency

flowdeck simulator reduce-transparency -S "iPhone 16"
flowdeck simulator reduce-transparency set enabled -S "iPhone 16"
flowdeck simulator reduce-transparency set disabled -S "iPhone 16"
flowdeck simulator reduce-transparency reset -S "iPhone 16"     # Back to disabled

Show Borders

flowdeck simulator show-borders -S "iPhone 16"
flowdeck simulator show-borders set enabled -S "iPhone 16"
flowdeck simulator show-borders set disabled -S "iPhone 16"
flowdeck simulator show-borders reset -S "iPhone 16"     # Back to disabled

Highlights button shapes on system controls, matching Settings ▸ Accessibility ▸ Display & Text Size ▸ Button Shapes.

VoiceOver

flowdeck simulator voiceover -S "iPhone 16"
flowdeck simulator voiceover set enabled -S "iPhone 16"
flowdeck simulator voiceover set disabled -S "iPhone 16"
flowdeck simulator voiceover reset -S "iPhone 16"     # Back to disabled

Color Filter

flowdeck simulator color-filter -S "iPhone 16"
flowdeck simulator color-filter set grayscale -S "iPhone 16"
flowdeck simulator color-filter set deuteranopia --intensity 0.75 -S "iPhone 16"
flowdeck simulator color-filter set off -S "iPhone 16"
flowdeck simulator color-filter reset -S "iPhone 16"     # Back to off

Valid filters: off, grayscale, protanopia, deuteranopia, tritanopia. --intensity accepts 0.25-1.0 and is not valid for grayscale.

Liquid Glass

flowdeck simulator liquid-glass -S "iPhone 16"
flowdeck simulator liquid-glass set --opacity 0.8 -S "iPhone 16"
flowdeck simulator liquid-glass set --opacity 0.4 --look-and-feel tinted -S "iPhone 16"
flowdeck simulator liquid-glass reset -S "iPhone 16"     # Back to 0.5 opacity, clear look

--opacity accepts 0.0-1.0. --look-and-feel accepts clear or tinted.

Audio

# Read the current audio output, input, and volume
flowdeck simulator audio -S "iPhone 16"
flowdeck simulator audio get -S "iPhone 16" --json

# Set the volume (0-100)
flowdeck simulator audio set --volume 80 -S "iPhone 16"

# Pin output/input to a specific host device
flowdeck simulator audio set --output BuiltInSpeakerDevice -S "iPhone 16"
flowdeck simulator audio set --output systemDefault --input systemDefault -S "iPhone 16"

# Reset to defaults (systemDefault output/input, 60% volume)
flowdeck simulator audio reset -S "iPhone 16"

# List the host audio devices a simulator can pin to
flowdeck simulator audio devices
flowdeck simulator audio devices --json

--output and --input accept systemDefault or a device UID from flowdeck simulator audio devices. --volume accepts an integer 0-100. At least one of --output, --input, or --volume is required for set.

Reduce Motion, Reduce Transparency, Show Borders, VoiceOver, Color Filter, Liquid Glass, and Audio apply immediately to a booted simulator without a reboot. The same nine settings are also reachable from the FlowDeck macOS app’s simulator panel, under the Settings menu.

Status Bar Overrides

Force fixed status bar values — handy for clean App Store screenshots and deterministic UI tests.

# Classic 9:41, full bars, full battery
flowdeck simulator status-bar override --time "9:41" --wifi-bars 3 --cellular-bars 4 --battery-level 100 --battery-state charged -S "iPhone 16"

# Custom carrier and network
flowdeck simulator status-bar override --data-network 5g --operator-name "FlowDeck" -S "iPhone 16"

# Inspect and clear
flowdeck simulator status-bar list -S "iPhone 16"
flowdeck simulator status-bar clear -S "iPhone 16"

Flags: --time, --data-network, --wifi-mode, --wifi-bars, --cellular-mode, --cellular-bars, --operator-name, --battery-state, --battery-level. At least one is required.

Push Notifications

Deliver a simulated remote push from a JSON payload — no APNs required.

flowdeck simulator push payload.json --bundle-id com.example.App -S "iPhone 16"

# Bundle id can come from the payload instead
flowdeck simulator push payload.json -S "iPhone 16"

{
  "Simulator Target Bundle": "com.example.App",
  "aps": { "alert": "Hello from FlowDeck", "badge": 1 }
}

The payload must contain an aps key and be 4096 bytes or less.

Privacy Permissions

Pre-grant, revoke, or reset app permissions so UI tests don’t hit system prompts.

flowdeck simulator privacy grant photos -b com.example.App -S "iPhone 16"
flowdeck simulator privacy revoke location -b com.example.App -S "iPhone 16"
flowdeck simulator privacy reset all -S "iPhone 16"

Services: all, calendar, contacts, contacts-limited, location, location-always, photos, photos-add, media-library, microphone, motion, reminders, siri. grant/revoke require --bundle-id; reset does not.

Pasteboard

flowdeck simulator pasteboard set "Hello world" -S "iPhone 16"
flowdeck simulator pasteboard get -S "iPhone 16"
flowdeck simulator pasteboard clear -S "iPhone 16"

Keychain

flowdeck simulator keychain reset -S "iPhone 16"
flowdeck simulator keychain add-cert ./cert.pem -S "iPhone 16"
flowdeck simulator keychain add-cert ./root.pem --root -S "iPhone 16"

Watch + Phone Pairing

Pair a watch and phone simulator for WatchConnectivity (WCSession) testing.

# Create and activate a pair (watch first, then phone — name or UDID)
flowdeck simulator pair create "Apple Watch Series 10 (46mm)" "iPhone 16" --activate

# Inspect pairs and their active state (list is the default subcommand)
flowdeck simulator pair list
flowdeck simulator pair list --json

# Re-activate or remove a pair (use the pair UDID from `pair list`)
flowdeck simulator pair activate <pair-udid>
flowdeck simulator pair delete <pair-udid>

The watch and phone must have compatible runtimes (e.g. watchOS 11 + iOS 18). --activate makes the new pair the active pair; a freshly created pair is already active, so re-activating is a no-op. WCSession delivery between simulators can be unreliable regardless of pairing — pairing only ensures a connectable pair exists.

Launch an embedded Watch companion

When an iOS app embeds a Watch app at Host.app/Watch/*.app, you can launch that companion on a paired watch simulator without re-running the iPhone app:

flowdeck simulator companion launch \
  --phone "iPhone 16" \
  --app /path/to/Host.app/Watch/MyWatch.app \
  --json

FlowDeck resolves or auto-creates a compatible watch+phone pair, boots the watch if needed, installs the watch app when it is not already present, and launches it. A plain flowdeck run of the iPhone target only detects the embedded Watch product; it does not launch the watch until this command (or the macOS simulator panel header toggle) is used.

App Inspection

# Path to an installed app's container
flowdeck simulator app container com.example.App -S "iPhone 16"
flowdeck simulator app container com.example.App --container data -S "iPhone 16"

# App info (operates on one app)
flowdeck simulator app info com.example.App -S "iPhone 16"

# Enumerate all installed apps (separate, flat command)
flowdeck simulator list-apps -S "iPhone 16"

Cache Management

Clear Simulator Cache

flowdeck simulator clear-cache

Erase Simulator Contents

Reset a simulator to factory state:

flowdeck simulator erase <UDID>

Erasing a simulator deletes all apps, data, and settings. This cannot be undone.

CI/CD Usage

Boot Simulator Before Tests

# Get UDID from list
UDID=$(flowdeck simulator list --platform iOS --json | jq -r '.[0].udid')

# Boot if not already running
flowdeck simulator boot "$UDID"

# Run tests
flowdeck test --workspace MyApp.xcworkspace --simulator "iPhone 16"

Create Fresh Simulator for CI

# Create a clean simulator
flowdeck simulator create \
  --name "CI-iPhone" \
  --device-type "iPhone 16" \
  --runtime "iOS 18.0" \
  --json

# Run tests
flowdeck test --workspace MyApp.xcworkspace --simulator "CI-iPhone"

# Delete when done
flowdeck simulator delete "CI-iPhone"

JSON Output Examples

simulator list —json

[
  {
    "udid": "12345678-1234-1234-1234-123456789ABC",
    "name": "iPhone 16 Pro",
    "platform": "iOS",
    "osVersion": "18.0",
    "state": "Booted",
    "isAvailable": true,
    "lastBootedAt": 800955104,
    "deviceTypeIdentifier": "com.apple.CoreSimulator.SimDeviceType.iPhone-16-Pro",
    "runtimeIdentifier": "com.apple.CoreSimulator.SimRuntime.iOS-18-0"
  }
]

simulator runtime list —json

[
  {
    "identifier": "com.apple.CoreSimulator.SimRuntime.iOS-18-0",
    "name": "iOS 18.0",
    "version": "18.0",
    "build": "22A3354",
    "platform": "iOS",
    "isAvailable": true
  }
]

Troubleshooting

Simulator Won’t Boot

Try erasing and rebooting:

flowdeck simulator erase <UDID>
flowdeck simulator boot <UDID>

Simulator Not Found

Verify the simulator exists and get its UDID:

flowdeck simulator list --json | jq '.[] | {name, udid}'

Old Runtimes

Check for available runtimes and update Xcode if needed:

flowdeck simulator runtime list