flowdeck build
Build an Xcode project or workspace for simulator, macOS, or physical device.
# Build for iOS simulator
flowdeck build --workspace MyApp.xcworkspace --scheme MyApp --simulator "iPhone 16"
# Build for macOS
flowdeck build --workspace MyApp.xcworkspace --scheme MyApp --device "My Mac"
# Build for physical device (by name - partial match)
flowdeck build --workspace MyApp.xcworkspace --scheme MyApp --device "iPhone"
flowdeck build --workspace MyApp.xcworkspace --scheme MyApp --device "John's iPhone"
# Build for physical device (by UDID)
flowdeck build --workspace MyApp.xcworkspace --scheme MyApp --device "00008130-001245110C08001C"
# Release configuration
flowdeck build --workspace MyApp.xcworkspace --scheme MyApp --simulator "iPhone 16" --configuration Release
# JSON output for automation
flowdeck build --workspace MyApp.xcworkspace --scheme MyApp --simulator "iPhone 16" --json
# Load settings from config file
flowdeck build --config .flowdeck/state.json
Options
| Option | Short | Description |
|---|
--workspace <path> | -w | Path to .xcworkspace or .xcodeproj (required) |
--simulator <name> | -S | Target simulator name or UDID |
--device <name> | -D | Physical device name/UDID, or “My Mac” for macOS |
--scheme <name> | -s | Build scheme name (auto-detected if only one) |
--configuration <name> | -C | Build configuration (Debug/Release) |
--project <path> | -p | Project directory (defaults to current directory) |
--derived-data-path <path> | -d | Custom derived data location |
--config <path> | -c | Path to JSON config file with project settings |
--json | -j | Output JSON events for programmatic consumption |
--verbose | -v | Show full xcodebuild output (default: progress only) |
Either --simulator or --device must be provided:
- Use
--simulator for iOS/tvOS/watchOS simulators
- Use
--device "My Mac" (or "mac", "macOS") for macOS builds
- Use
--device "<name>" or --device "<UDID>" for physical devices
Device Matching
When using --device, FlowDeck supports:
- UDID: Exact match (case-sensitive)
- Name: Partial match (case-insensitive), e.g.,
"iPhone" matches "John's iPhone"
The --config parameter accepts a JSON file with portable project settings:
{
"workspace": "MyApp.xcworkspace",
"scheme": "MyApp",
"configuration": "Debug",
"platform": "iOS",
"version": "18.0",
"derivedDataPath": "/custom/path"
}
platform to "macOS" (no simulator needed).
JSON Output
When using --json, the command outputs newline-delimited JSON events:
{"type":"status","stage":"COMPILING","message":"Compiling sources..."}
{"type":"status","stage":"LINKING","message":"Linking..."}
{"type":"result","success":true,"operation":"build","duration":12.5}
| Type | Description |
|---|
status | Progress updates with stage and message |
log | Build log messages with level and message |
warning | Compiler warnings with file, line, message |
error | Compiler errors with file, line, message |
result | Final result with success, operation, duration |
{
"type": "result",
"success": true,
"operation": "build",
"duration": 12.5
}
{
"type": "result",
"success": false,
"operation": "build",
"error": {
"code": "BUILD_FAILED",
"message": "Build failed with 3 errors",
"suggestions": ["Check compiler errors above"],
"recoverable": true
}
}
flowdeck run
Build and launch the app on a simulator, macOS, or physical device.
# Build and run on iOS simulator
flowdeck run --workspace MyApp.xcworkspace --scheme MyApp --simulator "iPhone 16"
# Run on macOS
flowdeck run --workspace MyApp.xcworkspace --scheme MyApp --device "My Mac"
# Run on physical device
flowdeck run --workspace MyApp.xcworkspace --scheme MyApp --device "John's iPhone"
# Run with log streaming
flowdeck run --workspace MyApp.xcworkspace --scheme MyApp --simulator "iPhone 16" --log
# Interactive mode (R=rebuild, C=clean+rebuild, Q=quit)
flowdeck run --workspace MyApp.xcworkspace --scheme MyApp --simulator "iPhone 16" --interactive
# Wait for debugger to attach
flowdeck run --workspace MyApp.xcworkspace --scheme MyApp --simulator "iPhone 16" --wait-for-debugger
Options
| Option | Short | Description |
|---|
--workspace <path> | -w | Path to .xcworkspace or .xcodeproj (required) |
--simulator <name> | -S | Target simulator name or UDID |
--device <name> | -D | Physical device name/UDID, or “My Mac” for macOS |
--scheme <name> | -s | Build scheme name |
--configuration <name> | -C | Build configuration |
--project <path> | -p | Project directory |
--derived-data-path <path> | -d | Custom derived data location |
--config <path> | -c | Path to JSON config file |
--log | -l | Stream logs after launch (print statements + OSLog) |
--wait-for-debugger | | Wait for debugger to attach before app starts |
--interactive | -i | Interactive mode: R to rebuild, C to clean+rebuild, Q to quit |
--json | -j | Output JSON events |
--verbose | -v | Show app console output (default: suppressed) |
Either --simulator or --device must be provided (same as build command).
After Launching
When the app launches, you’ll get an App ID. Use it to:
flowdeck apps # List running apps
flowdeck logs <app-id> # Stream logs from the app
flowdeck stop <app-id> # Stop the app
JSON Output
{"type":"status","stage":"COMPILING","message":"Building..."}
{"type":"status","stage":"INSTALLING","message":"Installing on iPhone 16..."}
{"type":"status","stage":"LAUNCHING","message":"Launching app..."}
{"type":"app_launched","appId":"abc123","bundleId":"com.example.MyApp","pid":54321}
{"type":"result","success":true,"operation":"launch","appId":"abc123"}
{
"type": "app_launched",
"appId": "abc123",
"bundleId": "com.example.MyApp",
"pid": 54321,
"targetType": "simulator",
"targetName": "iPhone 16"
}
flowdeck clean
Clean build artifacts for a project.
# Clean with workspace and scheme
flowdeck clean --workspace MyApp.xcworkspace --scheme MyApp
# Clean with custom derived data path
flowdeck clean --workspace MyApp.xcworkspace --scheme MyApp --derived-data-path /tmp/DerivedData
# Clean using config file
flowdeck clean --config .flowdeck/state.json
# Delete ALL DerivedData (nuclear option)
flowdeck clean --derived-data
Options
| Option | Short | Description |
|---|
--workspace <path> | -w | Path to .xcworkspace or .xcodeproj |
--scheme <name> | -s | Scheme name |
--project <path> | -p | Project directory |
--derived-data-path <path> | -d | Custom derived data path |
--config <path> | -c | Path to JSON config file |
--derived-data | | Delete entire ~/Library/Developer/Xcode/DerivedData folder |
--json | -j | Output JSON events |
--verbose | -v | Show clean output in console |
When to Use
- Build errors that don’t make sense
- After changing build settings
- After switching branches with different dependencies
- When disk space is running low
JSON Output
{
"type": "result",
"success": true,
"operation": "clean",
"message": "Clean succeeded"
}
