> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowdeck.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Managing Simulators

> Manage iOS simulators from the command line

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

```bash theme={null}
# Show the simulator command overview and common workflows
flowdeck simulator --examples
```

## Managing Simulators

### List All Simulators

```bash theme={null}
flowdeck simulator list
```

### Filter by Platform

```bash theme={null}
flowdeck simulator list --platform iOS
flowdeck simulator list --platform tvOS
flowdeck simulator list --platform watchOS
flowdeck simulator list --platform visionOS
```

### Show Only Available Simulators

```bash theme={null}
flowdeck simulator list --available-only
```

### JSON Output

```bash theme={null}
flowdeck simulator list --json
```

**Example output:**

```json theme={null}
[
  {
    "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

```bash theme={null}
flowdeck simulator boot <UDID>
```

### Shutdown a Simulator

```bash theme={null}
flowdeck simulator shutdown <UDID>
```

### Open Simulator.app

```bash theme={null}
flowdeck simulator open
```

## Creating Simulators

### Create a New Simulator

```bash theme={null}
flowdeck simulator create \
  --name "My Test iPhone" \
  --device-type "iPhone 15 Pro" \
  --runtime "iOS 17.2"
```

### Find Available Options

```bash theme={null}
# List available device types
flowdeck simulator device-types

# List installed runtimes
flowdeck simulator runtime list

# List downloadable runtimes
flowdeck simulator runtime available
```

<Tip>
  See [Runtimes](/cli/simulators/runtimes) for install/remove workflows and the [full runtime command reference](/cli/commands/simulator/runtimes).
</Tip>

## Cloning Simulators

Duplicate an existing simulator with all its settings and data:

```bash theme={null}
flowdeck simulator clone "iPhone 16 Pro" -n "iPhone 16 Pro Copy"
```

### Clone by UDID

```bash theme={null}
flowdeck simulator clone A7D19B36-1234-5678-ABCD-123456789ABC -n "My Clone"
```

### Use the Clone

```bash theme={null}
# Boot the clone
flowdeck simulator boot "iPhone 16 Pro Copy"

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

<Tip>
  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.
</Tip>

## 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.

```bash theme={null}
# 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
```

```bash theme={null}
flowdeck simulator rename --examples
```

**JSON output:**

```json theme={null}
{
  "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.

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

## Deleting Simulators

### Delete by UDID

```bash theme={null}
flowdeck simulator delete <UDID>
```

### Delete Unavailable Simulators

Remove all simulators that are no longer available:

```bash theme={null}
flowdeck simulator delete --unavailable
```

### Prune Stale Simulators

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

```bash theme={null}
flowdeck simulator prune
```

## Screenshots

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

```bash theme={null}
# 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
```

<Tip>
  See [UI Automation](/cli/commands/ui/automation) for more screenshot options, including `--optimize` for AI-friendly output.
</Tip>

## Related: UI Automation (Core Feature)

FlowDeck's UI automation is a core CLI feature (not a simulator subcommand) that targets iOS simulators.

See the [UI Automation overview](/cli/ui-automation) for examples and the [full command reference](/cli/commands/ui/automation) for all commands and flags.

## Device Orientation

### Get Current Orientation

```bash theme={null}
# 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:**

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

### Set Orientation

```bash theme={null}
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.

<Note>
  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.
</Note>

<Warning>
  `portrait-upside-down` is not supported on iPhone simulators. Use an iPad simulator for upside-down orientation checks.
</Warning>

## Hardware and Debug Controls

```bash theme={null}
# 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)

```bash theme={null}
# 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

```bash theme={null}
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

```bash theme={null}
# 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"
```

<Note>
  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).
</Note>

### Reduce Motion

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
# 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`.

<Note>
  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.
</Note>

## Status Bar Overrides

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

```bash theme={null}
# 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.

```bash theme={null}
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"
```

```json theme={null}
{
  "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.

```bash theme={null}
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

```bash theme={null}
flowdeck simulator pasteboard set "Hello world" -S "iPhone 16"
flowdeck simulator pasteboard get -S "iPhone 16"
flowdeck simulator pasteboard clear -S "iPhone 16"
```

## Keychain

```bash theme={null}
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.

```bash theme={null}
# 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>
```

<Note>
  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.
</Note>

### 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:

```bash theme={null}
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

```bash theme={null}
# 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

```bash theme={null}
flowdeck simulator clear-cache
```

### Erase Simulator Contents

Reset a simulator to factory state:

```bash theme={null}
flowdeck simulator erase <UDID>
```

<Warning>
  Erasing a simulator deletes all apps, data, and settings. This cannot be undone.
</Warning>

## CI/CD Usage

### Boot Simulator Before Tests

```bash theme={null}
# 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

```bash theme={null}
# 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

```json theme={null}
[
  {
    "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

```json theme={null}
[
  {
    "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:

```bash theme={null}
flowdeck simulator erase <UDID>
flowdeck simulator boot <UDID>
```

### Simulator Not Found

Verify the simulator exists and get its UDID:

```bash theme={null}
flowdeck simulator list --json | jq '.[] | {name, udid}'
```

### Old Runtimes

Check for available runtimes and update Xcode if needed:

```bash theme={null}
flowdeck simulator runtime list
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.