Skip to main content

Documentation Index

Fetch the complete documentation index at: https://flowdeck.studio/docs/llms.txt

Use this file to discover all available pages before exploring further.

FlowDeck CLI provides powerful build and run capabilities optimized for command-line workflows and CI/CD integration. 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:
  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
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 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 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.