Run

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

# 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

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

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

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.

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.

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

JSON Output

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

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.

{"type":"status","stage":"LAUNCHING","message":"Launching on iPhone 16"}
{"type":"result","success":true,"operation":"run"}

Overview

FlowDeck for AI

Interactive Mode (TUI)

Core Features

Command Reference

Advanced

Support

Options

JSON Output

​Options

​JSON Output

Options

JSON Output