Skip to main content
FlowDeck CLI provides powerful build and run capabilities optimized for command-line workflows and CI/CD integration. The recommended workflow is to use init to save project settings, then run commands without parameters: 
# 1. Discover project structure
flowdeck context --json

# 2. Initialize with discovered settings
flowdeck init -w MyApp.xcworkspace -s MyApp -S "iPhone 16"

# 3. Run commands without parameters
flowdeck build
flowdeck run
flowdeck test
flowdeck clean
After running flowdeck init, all subsequent commands use the saved settings automatically. You only need to specify parameters when you want to override the defaults.

​
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 init, 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'
For the complete list of build options, see the Build Command Reference.

​
Running Your App

​
Build and Run on Simulator

# After init, run using saved settings
flowdeck run

# Or specify parameters directly
flowdeck run -w MyApp.xcworkspace -s MyApp -S "iPhone 16"
This command:
  1. Builds the app
  2. Opens Simulator.app (if iOS)
  3. Boots the simulator (or uses already running)
  4. Installs the app
  5. Launches the 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"
This builds the app with 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
This is useful for:
  • 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 run --json
flowdeck test --json
For complete CI/CD setup including license configuration and pipeline examples, see CI/CD Integration.
This outputs NDJSON (newline-delimited JSON) events: 
{"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 init, 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. To generate a config file, use Project Tools (P), then select Export Project Config in FlowDeck interactive mode. 
# Build with a config file
flowdeck build --config .flowdeck/ci-config.json

# Run with a config file
flowdeck run --config .flowdeck/ci-config.json
See Configuration File for the complete reference.

​
Performance Optimization

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 use init
cd ~/Projects/MyApp
flowdeck init -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
Check the error output for specific issues like missing dependencies or code signing problems.