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

# Orientation

> Get or set simulator orientation

Read or change the physical orientation of an iOS simulator.

## flowdeck simulator orientation

`flowdeck simulator orientation` defaults to `get`.

```bash theme={null}
# Read the current orientation from the current booted simulator
flowdeck simulator orientation

# Explicit get subcommand
flowdeck simulator orientation get

# Target a specific simulator
flowdeck simulator orientation get --simulator "iPhone 16"

# JSON output
flowdeck simulator orientation get --json

# Usage examples
flowdeck simulator orientation --examples
flowdeck simulator orientation get --examples
```

### Get Options

| Option                       | Short | Description                   |
| ---------------------------- | ----- | ----------------------------- |
| `--simulator <name-or-udid>` | `-S`  | Target simulator name or UDID |
| `--json`                     | `-j`  | Output as JSON                |
| `--examples`                 | `-e`  | Show usage examples           |

### Get 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"
}
```

<Note>
  If you omit `--simulator`, FlowDeck targets the current booted simulator. If no simulator is booted, the command fails.
</Note>

***

## flowdeck simulator orientation set

Set the simulator orientation. By default, FlowDeck waits until the physical and visual state match the confirmed result.

```bash theme={null}
flowdeck simulator orientation set portrait --simulator "iPhone 16"
flowdeck simulator orientation set landscape-left --simulator "iPhone 16"
flowdeck simulator orientation set landscape-right --simulator "iPhone 16"
flowdeck simulator orientation set portrait-upside-down --simulator "FlowDeck-Diag-iPad"

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

# Return immediately after sending the rotation event
flowdeck simulator orientation set landscape-left --simulator "iPhone 16" --no-wait

# Usage examples
flowdeck simulator orientation set portrait --examples
```

### Set Options

| Option                       | Short | Description                                                                     |
| ---------------------------- | ----- | ------------------------------------------------------------------------------- |
| `--simulator <name-or-udid>` | `-S`  | Target simulator name or UDID                                                   |
| `--json`                     | `-j`  | Output as JSON                                                                  |
| `--no-wait`                  |       | Return after sending the rotation event without waiting for visual confirmation |
| `--examples`                 | `-e`  | Show usage examples                                                             |

### Supported Values

* `portrait`
* `landscape-left`
* `landscape-right`
* `portrait-upside-down`

### Set JSON Output

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

`confirmed` reports whether the orientation was actually verified against the simulator's physical and visual state. It is `true` after a successful wait, and always `false` with `--no-wait` since no verification happens on that path. `success` stays `true` on `--no-wait` because the rotation event was dispatched without error — check `confirmed` to know whether that was proven.

<Note>
  FlowDeck returns the confirmed orientation, not just the requested value. If the front-most app does not support the requested orientation, the result reflects what the simulator actually applied.
</Note>

<Note>
  With `--no-wait`, FlowDeck assumes the rotation event was accepted and returns the requested orientation immediately, with `confirmed: false`. Unsupported values, including `portrait-upside-down` on iPhone simulators, are still rejected before the event is sent.
</Note>

<Warning>
  `portrait-upside-down` is not supported on iPhone simulators. Use an iPad simulator if you need to validate upside-down orientation behavior.
</Warning>