Skip to main content
run builds (unless skipped) and launches your app on the selected target. After flowdeck init, you can run without extra flags. 
# After init, 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

# 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

# Show usage examples
flowdeck run --examples

​
Options

OptionShortDescription
--examples-eShow usage examples
--project <path>-pProject directory
--workspace <path>-wPath to workspace (.xcworkspace) or project (.xcodeproj)
--scheme <name>-sScheme name
--configuration <name>-CBuild configuration
--simulator <name>-SSimulator name/UDID (use none for legacy macOS builds)
--device <name>-DDevice name/UDID (use “My Mac” or “My Mac Catalyst” for macOS)
--derived-data-path <path>-dDerived data path (default: ~/Library/Developer/FlowDeck/DerivedData)
--log-lStream logs after launch
--wait-for-debuggerWait for debugger to attach before app starts
--no-buildSkip build step and launch existing app
--json-jOutput JSON/NDJSON events
--verbose-vShow app console output
--config <path>-cLoad settings from JSON 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 init or interactive mode.

​
JSON Output

When --json is set, run emits NDJSON events (one JSON object per line). Example: 
{"type":"status","stage":"LAUNCHING","message":"Launching on iPhone 16"}
{"type":"result","success":true,"operation":"run"}