Build Commands

flowdeck build

Build an Xcode project or workspace for simulator, macOS, or physical device.

# After 'flowdeck init', build using saved settings
flowdeck build

# Build for iOS simulator
flowdeck build -w MyApp.xcworkspace -s MyApp -S "iPhone 16"

# Build for macOS
flowdeck build -w MyApp.xcworkspace -s MyApp -D "My Mac"

# Build for physical device (by name - partial match)
flowdeck build -w MyApp.xcworkspace -s MyApp -D "iPhone"
flowdeck build -w MyApp.xcworkspace -s MyApp -D "John's iPhone"

# Build for physical device (by UDID)
flowdeck build -w MyApp.xcworkspace -s MyApp -D "00008130-001245110C08001C"

# Release configuration
flowdeck build -C Release

# JSON output for automation
flowdeck build --json

# Verbose output (show xcodebuild output)
flowdeck build -v

# Custom xcodebuild options
flowdeck build --xcodebuild-options='-quiet'
flowdeck build --xcodebuild-options='-enableCodeCoverage YES'

# Custom xcodebuild environment
flowdeck build --xcodebuild-env='CI=true'

# Load settings from config file
flowdeck build --config .flowdeck/ci-config.json

# Show usage examples
flowdeck build --examples

Options

Option	Short	Description
`--examples`		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 (Debug/Release)
`--simulator <name>`	`-S`	Simulator name/UDID (REQUIRED for iOS/tvOS/watchOS)
`--device <name>`	`-D`	Physical device name or UDID
`--derived-data-path <path>`	`-d`	Derived data path
`--json`	`-j`	Output JSON events for programmatic consumption
`--verbose`	`-v`	Show build output in console
`--config <path>`	`-c`	Path to JSON config file with project settings
`--xcodebuild-options <args>`		Extra xcodebuild arguments (e.g., `--xcodebuild-options='-quiet'`)
`--xcodebuild-env <vars>`		Xcodebuild environment variables (e.g., ‘CI=true’)

Either --simulator or --device must be provided:

Use --simulator for iOS/tvOS/watchOS simulators
Use --device "My Mac" for native macOS builds
Use --device "My Mac Catalyst" for Mac Catalyst builds (iOS app running on Mac)
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"

Config File Format

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"
}

For macOS builds, set 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}

Event Types:

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`

Result Event (Success):

{
  "type": "result",
  "success": true,
  "operation": "build",
  "duration": 12.5
}

Result Event (Failure):

{
  "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.

# After 'flowdeck init', run using saved settings
flowdeck run

# Build and run on iOS simulator
flowdeck run -w MyApp.xcworkspace -s MyApp -S "iPhone 16"

# Run on macOS
flowdeck run -w MyApp.xcworkspace -s MyApp -D "My Mac"

# Run on physical device
flowdeck run -w MyApp.xcworkspace -s MyApp -D "John's iPhone"

# Run with log streaming
flowdeck run -S "iPhone 16" --log
flowdeck run -S "iPhone 16" -l  # Short form

# Interactive mode (R=rebuild, C=clean+rebuild, Q=quit)
flowdeck run -S "iPhone 16" --interactive
flowdeck run -S "iPhone 16" -i  # Short form

# Wait for debugger to attach
flowdeck run -S "iPhone 16" --wait-for-debugger

# Verbose output (show app console output)
flowdeck run -S "iPhone 16" --verbose
flowdeck run -S "iPhone 16" -v  # Short form

# Pass launch arguments to the app
flowdeck run -S "iPhone 16" --launch-options='-AppleLanguages (en) -SkipOnboarding'

# Set environment variables for the app
flowdeck run -S "iPhone 16" --launch-env='DEBUG=1 API_ENV=staging'

# Pass custom xcodebuild options
flowdeck run -S "iPhone 16" --xcodebuild-options='-quiet'
flowdeck run -S "iPhone 16" --xcodebuild-env='CI=true'

# JSON output
flowdeck run -S "iPhone 16" --json

# Show usage examples
flowdeck run --examples

Use = when passing values that start with a dash (e.g., --launch-options="-Debug YES") to prevent argument parsing issues.

Options

Option	Short	Description
`--examples`		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 (Debug/Release)
`--simulator <name>`	`-S`	Simulator name/UDID (REQUIRED for iOS/tvOS/watchOS)
`--device <name>`	`-D`	Physical device name or UDID
`--derived-data-path <path>`	`-d`	Derived data path
`--json`	`-j`	Output JSON events for programmatic consumption
`--verbose`	`-v`	Show app console output (default: suppressed)
`--wait-for-debugger`		Wait for debugger to attach before app starts
`--log`	`-l`	Stream logs after launch (print statements + OSLog)
`--session <id>`		Session ID for consistent app tracking across rebuilds
`--interactive`	`-i`	Interactive mode: R to rebuild, C to clean+rebuild, Q to quit
`--config <path>`	`-c`	Path to JSON config file with project settings
`--launch-options <args>`		App launch arguments. Use = when values start with - (e.g., `--launch-options='-AppleLanguages (en)'`)
`--launch-env <vars>`		App launch environment variables (e.g., ‘DEBUG=1 API_ENV=staging’)
`--xcodebuild-options <args>`		Additional xcodebuild arguments. Use = when values start with - (e.g., `--xcodebuild-options='-quiet'`)
`--xcodebuild-env <vars>`		Xcodebuild environment variables (e.g., ‘CI=true DEVELOPER_DIR=/path’)

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"}

App Launched Event:

{
  "type": "app_launched",
  "appId": "abc123",
  "bundleId": "com.example.MyApp",
  "pid": 54321,
  "targetType": "simulator",
  "targetName": "iPhone 16"
}

flowdeck clean

Clean build artifacts and Xcode caches to resolve build issues.

# After 'flowdeck init', clean using saved settings
flowdeck clean

# Clean scheme build artifacts (requires workspace and scheme)
flowdeck clean -w MyApp.xcworkspace -s MyApp

# Nuke all Derived Data (fixes most build issues)
flowdeck clean --derived-data

# Nuke Xcode cache (fixes indexing/autocomplete issues)
flowdeck clean --xcode-cache

# Nuclear option - clean everything
flowdeck clean --all

# Verbose output
flowdeck clean -v

# JSON output
flowdeck clean --json

# Clean using config file
flowdeck clean --config .flowdeck/ci-config.json

# Show usage examples
flowdeck clean --examples

Options

Option	Short	Description
`--examples`		Show usage examples
`--derived-data`		Delete all Xcode Derived Data (~Library/Developer/Xcode/DerivedData)
`--xcode-cache`		Delete Xcode cache (~Library/Caches/com.apple.dt.Xcode)
`--all`		Clean everything: scheme artifacts, derived data, and xcode cache
`--project <path>`	`-p`	Project directory
`--workspace <path>`	`-w`	Path to workspace (.xcworkspace) or project (.xcodeproj)
`--scheme <name>`	`-s`	Scheme name
`--derived-data-path <path>`	`-d`	Custom derived data path for scheme clean
`--config <path>`	`-c`	Path to JSON config file with project settings
`--json`	`-j`	Output JSON events for programmatic consumption
`--verbose`	`-v`	Show clean output in console (default: progress indicator only)

When to Use

--derived-data: Build errors that don’t make sense, disk space issues
--xcode-cache: Autocomplete broken, indexing issues, SourceKit crashes
--all: When nothing else works

JSON Output

{
  "type": "result",
  "success": true,
  "operation": "clean",
  "message": "Clean succeeded"
}

Getting Started

Core Features

AI Agent Integration

Command Reference

Advanced

Support

flowdeck build

Options

Device Matching

Config File Format

JSON Output

flowdeck run

Options

After Launching

JSON Output

flowdeck clean

Options

When to Use

JSON Output

Getting Started

Core Features

AI Agent Integration

Command Reference

Advanced

Support

​flowdeck build

​Options

​Device Matching

​Config File Format

​JSON Output

​flowdeck run

​Options

​After Launching

​JSON Output

​flowdeck clean

​Options

​When to Use

​JSON Output

flowdeck build

Options

Device Matching

Config File Format

JSON Output

flowdeck run

Options

After Launching

JSON Output

flowdeck clean

Options

When to Use

JSON Output