Building & Running

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'

For the complete list of build options, see the Build Command Reference.

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"

This command:

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"

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 app logs after launching:

flowdeck run -S "iPhone 16" --log
flowdeck run -S "iPhone 16" -l  # Short form
flowdeck run -D "John's iPhone" --log

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

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

This --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.

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

Check the error output for specific issues like missing dependencies or code signing problems.

Overview

FlowDeck for AI

Interactive Mode (TUI)

Core Features

Command Reference

Advanced

Support

Building & Running

Recommended Workflow

Project Context

Building Your App

Basic Build

Build for macOS

Build for Physical Device

Build Configurations

Custom Xcodebuild Options

Running Your App

Build and Run on Simulator

Build and Run on macOS

Mac Catalyst

Build and Run on Physical Device

Run with Log Streaming

Run Without Building

App Launch Arguments

JSON Output for Automation

Custom Derived Data

Cleaning

Config Files

Performance Optimization

Troubleshooting

”Workspace not found”

“Scheme not found”

“Simulator not found”

“Build failed”

​Recommended Workflow

​Project Context

​Building Your App

​Basic Build

​Build for macOS

​Build for Physical Device

​Build Configurations

​Custom Xcodebuild Options

​Running Your App

​Build and Run on Simulator

​Build and Run on macOS

​Mac Catalyst

​Build and Run on Physical Device

​Run with Log Streaming

​Run Without Building

​App Launch Arguments

​JSON Output for Automation

​Custom Derived Data

​Cleaning

​Config Files

​Performance Optimization

​Troubleshooting

​”Workspace not found”

​“Scheme not found”

​“Simulator not found”

​“Build failed”

Recommended Workflow

Project Context

Building Your App

Basic Build

Build for macOS

Build for Physical Device

Build Configurations

Custom Xcodebuild Options

Running Your App

Build and Run on Simulator

Build and Run on macOS

Mac Catalyst

Build and Run on Physical Device

Run with Log Streaming

Run Without Building

App Launch Arguments

JSON Output for Automation

Custom Derived Data

Cleaning

Config Files

Performance Optimization

Troubleshooting

”Workspace not found”

“Scheme not found”

“Simulator not found”

“Build failed”