FlowDeck CLI provides powerful build and run capabilities optimized for command-line workflows and CI/CD integration.
Project context
The context command gives you (or your AI agent) everything needed to understand your project at a glance. Available schemes, build configurations, simulators, and connected devices.
# Get app context
flowdeck context
# Also avavilable in JSON output
flowdeck context --json
Building Your App
Basic Build
# Stateless build (requires workspace/project, scheme, and target)
flowdeck build --workspace MyApp.xcworkspace --scheme MyApp --simulator "iPhone 16"
Build for macOS
Use --device "My Mac" for macOS targets:
flowdeck build --workspace MyApp.xcworkspace --scheme MyApp --device "My Mac"
Build for Physical Device
Use --device with the device name or UDID:
# By device name (partial match, case-insensitive)
flowdeck build --workspace MyApp.xcworkspace --scheme MyApp --device "iPhone"
flowdeck build --workspace MyApp.xcworkspace --scheme MyApp --device "John's iPhone"
# By device UDID (exact match)
flowdeck build --workspace MyApp.xcworkspace --scheme MyApp --device "00008130-001245110C08001C"
Use flowdeck device list to see available devices and their UDIDs.
Build Configurations
Specify Debug or Release configuration:
# Debug build (default)
flowdeck build --workspace MyApp.xcworkspace --scheme MyApp --simulator "iPhone 16" --configuration Debug
# Release build
flowdeck build --workspace MyApp.xcworkspace --scheme MyApp --simulator "iPhone 16" --configuration Release
Scheme Selection
The --scheme parameter specifies which scheme to build:
flowdeck build --workspace MyApp.xcworkspace --scheme MyApp --simulator "iPhone 16"
Running Your App
Build and Run on Simulator
flowdeck run --workspace MyApp.xcworkspace --scheme MyApp --simulator "iPhone 16"
- Builds the app
- Opens Simulator.app (if iOS)
- Boots the simulator (or uses already running)
- Installs the app
- Launches the app
Build and Run on macOS
flowdeck run --workspace MyApp.xcworkspace --scheme MyApp --device "My Mac"
Build and Run on Physical Device
flowdeck run --workspace MyApp.xcworkspace --scheme MyApp --device "John's iPhone"
For the complete list of run options including --interactive and --wait-for-debugger, see the Run Command Reference. Run with Log Streaming
Stream OSLog output after launching:
flowdeck run --workspace MyApp.xcworkspace --scheme MyApp --simulator "iPhone 16" --log
JSON Output for Automation
Use --json for machine-readable output, essential for CI/CD pipelines:
flowdeck build --workspace MyApp.xcworkspace --scheme MyApp --simulator "iPhone 16" --json
For complete CI/CD setup including license configuration and pipeline examples, see CI/CD Integration. {"type":"app_log","message":"Build Started"}
{"type":"app_log","message":"Resolving Packages"}
{"type":"app_log","message":"Building"}
{"type":"app_log","message":"Build Completed"}
Custom Derived Data
Specify a custom derived data path to avoid conflicts with Xcode:
flowdeck build --workspace MyApp.xcworkspace --scheme MyApp --simulator "iPhone 16" \
--derived-data-path ~/FlowDeck/DerivedData
Cleaning
Clean build artifacts before rebuilding:
flowdeck clean --workspace MyApp.xcworkspace --scheme MyApp
flowdeck build --workspace MyApp.xcworkspace --scheme MyApp --simulator "iPhone 16"
Pre-defined configuration
Use the --config option to pass a set of pre-defined parameters from a JSON file. This is especially useful for CI/CD pipelines and complex build configurations.
To generate a config file, use the W (Write Config) option in FlowDeck interactive mode.
# Build your app with a JSON config
flowdeck build --config ios.json
- Detects CPU core count for parallel builds
- Uses optimized build settings
- Enables incremental compilation
Troubleshooting
”Workspace not found”
Ensure you’re specifying the correct path:
# Use full path if needed
flowdeck build --workspace /path/to/MyApp.xcworkspace --scheme MyApp --simulator "iPhone 16"
# Or navigate to the project directory first
cd ~/Projects/MyApp
flowdeck build --workspace MyApp.xcworkspace --scheme MyApp --simulator "iPhone 16"
“Scheme not found”
Use flowdeck context --json to discover available schemes:
flowdeck context --json | jq '.schemes'
“Simulator not found”
List available simulators first:
flowdeck simulator list --platform iOS --available-only
“Build failed”
Try cleaning and rebuilding:
flowdeck clean --workspace MyApp.xcworkspace --scheme MyApp
flowdeck build --workspace MyApp.xcworkspace --scheme MyApp --simulator "iPhone 16"
