Skip to main content

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.

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

# Force headless simulator mode (do not open Simulator.app)
FLOWDECK_HEADLESS=1 flowdeck run -S "iPhone 16"

# 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

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
--show-warningsShow compiler warnings (console output in text mode, diagnostic events in JSON mode)
--verbose-vShow app console output
--config <path>-cLoad 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. Use FLOWDECK_HEADLESS=1 to run headless.
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"}