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

# Run

> Build and launch an app on a simulator, device, or macOS

`run` builds (unless skipped) and launches your app on the selected target. After `flowdeck config set`, you can run without extra flags.

```bash theme={null}
# After config set, run with saved settings
flowdeck run

# Run on a simulator
flowdeck run -w MyApp.xcworkspace -s MyApp -S "iPhone 16"

# Run on macOS
flowdeck run -D "My Mac"

# Skip build and launch existing app
flowdeck run --no-build

# Stream logs after launch
flowdeck run --log

# Run on the simulator without opening Simulator.app (headless)
flowdeck run -S "iPhone 16" --headless

# Wait for debugger
flowdeck run --wait-for-debugger

# Pass launch arguments and env vars
flowdeck run --launch-options='-AppleLanguages (en) -SkipOnboarding'
flowdeck run --launch-env='DEBUG=1 API_ENV=staging'

# Extra xcodebuild options
flowdeck run --xcodebuild-options='-quiet'
flowdeck run --xcodebuild-env='CI=true'

# JSON output
flowdeck run --json
flowdeck run --json --show-warnings

# Show usage examples
flowdeck run --examples
```

## Options

| Option                        | Short | Description                                                                            |
| ----------------------------- | ----- | -------------------------------------------------------------------------------------- |
| `--examples`                  | `-e`  | Show usage examples                                                                    |
| `--project <path>`            | `-p`  | Project directory                                                                      |
| `--workspace <path>`          | `-w`  | Path to workspace (.xcworkspace) or project (.xcodeproj)                               |
| `--scheme <name>`             | `-s`  | Scheme name                                                                            |
| `--configuration <name>`      | `-C`  | Build configuration                                                                    |
| `--simulator <name>`          | `-S`  | Simulator name/UDID (use `none` for legacy macOS builds)                               |
| `--device <name>`             | `-D`  | Device name/UDID (use "My Mac" or "My Mac Catalyst" for macOS)                         |
| `--derived-data-path <path>`  | `-d`  | Derived data path (default: `~/Library/Developer/FlowDeck/DerivedData`)                |
| `--log`                       | `-l`  | Stream logs after launch                                                               |
| `--wait-for-debugger`         |       | Wait for debugger to attach before app starts                                          |
| `--no-build`                  |       | Skip build step and launch existing app                                                |
| `--headless`                  |       | Run on the simulator without opening Simulator.app (simulator targets only)            |
| `--json`                      | `-j`  | Output JSON/NDJSON events                                                              |
| `--show-warnings`             |       | Show compiler warnings (console output in text mode, `diagnostic` events in JSON mode) |
| `--verbose`                   | `-v`  | Show app console output                                                                |
| `--config <path>`             | `-c`  | Load settings from an explicit command config file                                     |
| `--launch-options <args>`     |       | App launch arguments                                                                   |
| `--launch-env <vars>`         |       | App launch environment variables                                                       |
| `--xcodebuild-options <args>` |       | Extra xcodebuild arguments                                                             |
| `--xcodebuild-env <vars>`     |       | Xcodebuild environment variables                                                       |

<Note>
  If both `--simulator` and `--device` are omitted, FlowDeck uses the saved target from `flowdeck config set` or interactive mode.
</Note>

<Note>
  `--config` here means the explicit command config file format. It is separate from `.flowdeck/config.json` and `.flowdeck/config.local.json`.
</Note>

<Note>
  Simulator launches open Simulator.app by default using the Simulator bundle from the selected Xcode developer directory. If that selected Xcode does not contain Simulator.app, FlowDeck opens an installed Xcode bundle that does. Pass `--headless` to boot and run the simulator without opening Simulator.app (for example, when another surface renders it). `--headless` is ignored for macOS, Mac Catalyst, and physical-device targets.
</Note>

<Note>
  Pure Swift Package directories are routed through Xcode's generated `.swiftpm/xcode/package.xcworkspace`, matching Xcode's build path. Package library schemes may still fail at launch time if xcodebuild does not produce an app bundle.
</Note>

<Note>
  For physical device runs, `flowdeck apps`, `flowdeck logs`, and `flowdeck stop` continue to work as long as the app is running on the device.
</Note>

## JSON Output

When `--json` is set, run emits NDJSON events (one JSON object per line). Example:

<Note>
  Compiler errors are always emitted in JSON failure events. Warning diagnostics are opt-in and emitted when `--show-warnings` is set. Warning snapshots are still reconciled and stored under DerivedData (`<DerivedData>/Warnings`) when a build step runs.
</Note>

```json theme={null}
{"type":"status","stage":"LAUNCHING","message":"Launching on iPhone 16"}
{"type":"result","success":true,"operation":"run"}
```