FlowDeck CLI provides powerful build and run capabilities optimized for command-line workflows and CI/CD integration.
Recommended Workflow
The recommended workflow is to use flowdeck config set to save project settings, then run commands without parameters:
# 1. Discover project structure
flowdeck context --json
# 2. Initialize with discovered settings
flowdeck config set -w MyApp.xcworkspace -s MyApp -S "iPhone 16"
# 3. Run commands without parameters
flowdeck build
flowdeck run
flowdeck test
flowdeck clean
After running flowdeck config set, all subsequent commands use the saved settings automatically. You only need to specify parameters when you want to override the defaults.
flowdeck config set saves runtime selection state. Shared project settings live separately in .flowdeck/config.json and .flowdeck/config.local.json, while explicit --config files remain the portable way to script a full command invocation.
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
# JSON output (recommended for AI agents)
flowdeck context --json
Building Your App
Basic Build
# After config set, build using saved settings
flowdeck build
# Or specify parameters directly
flowdeck build -w MyApp.xcworkspace -s MyApp -S "iPhone 16"
Build for macOS
Use --device "My Mac" for macOS targets:
flowdeck build -w MyApp.xcworkspace -s MyApp -D "My Mac"
Build for Physical Device
Use --device with the device name or UDID:
# By device name (partial match, case-insensitive)
flowdeck build -w MyApp.xcworkspace -s MyApp -D "iPhone"
flowdeck build -w MyApp.xcworkspace -s MyApp -D "John's iPhone"
# By device UDID (exact match)
flowdeck build -w MyApp.xcworkspace -s MyApp -D "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 -C Debug
# Release build
flowdeck build -C Release
Custom Xcodebuild Options
Pass arguments directly to xcodebuild:
# Code coverage
flowdeck build --xcodebuild-options='-enableCodeCoverage YES'
# Quiet mode
flowdeck build --xcodebuild-options='-quiet'
# Environment variables
flowdeck build --xcodebuild-env='CI=true'
Running Your App
Build and Run on Simulator
# After config set, run using saved settings
flowdeck run
# Or specify parameters directly
flowdeck run -w MyApp.xcworkspace -s MyApp -S "iPhone 16"
- Builds the app
- Opens Simulator.app (if iOS)
- Boots the simulator (or uses already running)
- Installs the app
- Launches the app
flowdeck run launches app bundle schemes only. Pure Swift Package targets should use flowdeck build or flowdeck test; use -w with an Xcode app workspace or project when the goal is to launch an app.
Build and Run on macOS
flowdeck run -w MyApp.xcworkspace -s MyApp -D "My Mac"
Mac Catalyst
Run an iOS app as Mac Catalyst using --device "My Mac Catalyst":
flowdeck run -w MyApp.xcworkspace -s MyApp -D "My Mac Catalyst"
platform=macOS,variant=Mac Catalyst and runs it natively on your Mac.
Use flowdeck device list to see all available targets including “My Mac” and “My Mac Catalyst”.
Build and Run on Physical Device
flowdeck run -w MyApp.xcworkspace -s MyApp -D "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 -S "iPhone 16" --log
flowdeck run -S "iPhone 16" -l # Short form
Run Without Building
Skip the build step and launch an existing app with --no-build:
# Run the last built app without rebuilding
flowdeck run --no-build
# Or specify a target
flowdeck run -S "iPhone 16" --no-build
flowdeck run -D "My Mac" --no-build
- Quick iteration when you haven’t changed code
- Testing different launch configurations
- Launching after a manual Xcode build
Behavior:
- If a built app exists, it shows “⏭️ Running build from X ago” and launches immediately
- If no built app is found, it automatically falls back to building from source with “⚠️ No built app found. Building from source…”
In interactive mode, use Shift+R to run without building.
App Launch Arguments
Pass arguments and environment variables to your app:
# Launch arguments
flowdeck run -S "iPhone 16" --launch-options='-AppleLanguages (en) -SkipOnboarding'
# Environment variables
flowdeck run -S "iPhone 16" --launch-env='DEBUG=1 API_ENV=staging'
JSON Output for Automation
Use --json for machine-readable output, essential for CI/CD pipelines:
flowdeck build --json
flowdeck build --json --show-warnings
flowdeck run --json
flowdeck run --json --show-warnings
flowdeck test --json
Compiler warnings are hidden by default in regular and JSON output. Add --show-warnings to build or run to surface them (console output in text mode, diagnostic events in JSON mode). Warning snapshots are always reconciled and stored in <DerivedData>/Warnings, even without --show-warnings.
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
FlowDeck uses ~/Library/Developer/FlowDeck/DerivedData by default. Override it when you need isolation across builds:
flowdeck build -d ~/Library/Developer/FlowDeck/DerivedData-CI
Cleaning
Clean build artifacts before rebuilding:
# After config set, clean using saved settings
flowdeck clean
# Clean scheme artifacts
flowdeck clean -w MyApp.xcworkspace -s MyApp
# Clean all FlowDeck derived data
flowdeck clean --derived-data
# Clean all Xcode derived data
flowdeck clean --xcode-derived-data
# Clean Xcode cache
flowdeck clean --xcode-cache
# Clean everything
flowdeck clean --all
Config Files
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.
# Build with a config file
flowdeck build --config .flowdeck/ci-config.json
# Run with a config file
flowdeck run --config .flowdeck/ci-config.json
--config file is the explicit command config format, not the same as .flowdeck/config.json or .flowdeck/config.local.json.
See Configuration File for the complete reference and the distinction between the two formats.
FlowDeck CLI automatically:
- 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 -w /path/to/MyApp.xcworkspace -s MyApp -S "iPhone 16"
# Or navigate to the project directory and configure once
cd ~/Projects/MyApp
flowdeck config set -w MyApp.xcworkspace -s MyApp -S "iPhone 16"
flowdeck build
“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 -P iOS -A
“Build failed”
Try cleaning and rebuilding:
flowdeck clean --all
flowdeck build
