> ## Documentation Index
> Fetch the complete documentation index at: https://flowdeck.studio/docs/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, 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
  },
  {
    "name": "iPhone 16",
    "udid": "23456789-2345-2345-2345-23456789ABCD",
    "platform": "iOS",
    "osVersion": "18.0",
    "state": "Shutdown",
    "isAvailable": true
  }
]
```

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

## 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 Unused Simulators

Delete simulators that have never been used:

```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 "iPhone 16"

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

Sends a rotation event to the simulator and polls until the physical orientation matches the requested value (up to 5 seconds). Returns the confirmed orientation, not just the requested one.

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

## 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
  }
]
```

### simulator runtime list --json

```json theme={null}
[
  {
    "identifier": "com.apple.CoreSimulator.SimRuntime.iOS-18-0",
    "name": "iOS 18.0",
    "version": "18.0",
    "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
```