Build

Build an Xcode project or workspace for a simulator, a physical device, or macOS. After running flowdeck config set, you can call flowdeck build with no extra flags.

# After config set, build using saved settings
flowdeck build

# Build for iOS simulator
flowdeck build -w MyApp.xcworkspace -s MyApp -S "iPhone 16"

# Build for macOS
flowdeck build -w MyApp.xcworkspace -s MyApp -D "My Mac"

# Build for a physical device
flowdeck build -w MyApp.xcworkspace -s MyApp -D "John's iPhone"

# Release configuration
flowdeck build -C Release

# JSON output for automation
flowdeck build --json
flowdeck build --json --show-warnings

# Verbose output (show xcodebuild output)
flowdeck build -v

# Extra xcodebuild arguments
flowdeck build --xcodebuild-options='-quiet'
flowdeck build --xcodebuild-env='CI=true'

# Load settings from config file
flowdeck build --config .flowdeck/ci-config.json

# Show usage examples
flowdeck build --examples

Options

Option	Short	Description
`--examples`	`-e`	Show usage examples
`--project <path>`	`-p`	Project directory
`--workspace <path>`	`-w`	Path to workspace (.xcworkspace) or project (.xcodeproj)
`--scheme <name>`	`-s`	Scheme name
`--configuration <name>`	`-C`	Build configuration (Debug/Release)
`--simulator <name>`	`-S`	Simulator name/UDID (use `none` for legacy macOS builds)
`--device <name>`	`-D`	Device name/UDID (use “My Mac” or “My Mac Catalyst” for macOS)
`--derived-data-path <path>`	`-d`	Derived data path (default: `~/Library/Developer/FlowDeck/DerivedData`)
`--json`	`-j`	Output JSON/NDJSON events
`--show-warnings`		Show compiler warnings (console output in text mode, `diagnostic` events in JSON mode)
`--verbose`	`-v`	Show build output in console
`--config <path>`	`-c`	Load settings from an explicit command config file
`--xcodebuild-options <args>`		Extra xcodebuild arguments
`--xcodebuild-env <vars>`		Xcodebuild environment variables

If both --simulator and --device are omitted, FlowDeck uses the saved target from flowdeck config set or interactive mode.

--config here means the explicit command config file format. It is separate from .flowdeck/config.json and .flowdeck/config.local.json.

On failed builds, FlowDeck prints the extracted failure reason plus the absolute persisted build log path. Read that log before rerunning with --verbose.

JSON Output

When --json is set, build emits NDJSON events (one JSON object per line). Example:

Compiler errors are always emitted in JSON failure events. Warning diagnostics are opt-in and emitted when --show-warnings is set. Warning snapshots are always reconciled and stored under DerivedData (<DerivedData>/Warnings) on every build.

{"type":"status","stage":"COMPILING","message":"Compiling sources..."}
{"type":"result","success":true,"operation":"build","duration":12.5}

On failure, a build_errors event lists each error and warning. Items include an optional language token (swift, cpp, objc, objcpp, c, or metal) so you can tell which compiler produced each diagnostic. The field is omitted when the language can’t be determined — issues with no source file (linker, code signing) or ambiguous files (such as .h headers). A grouped multi-target compile error has no single file but is still tagged when all of its diagnostics share one language, so language can appear without a file. Consumers should ignore unknown future values.

{"type":"build_errors","operation":"build","message":"Build failed with 2 errors","data":{"errors":[{"error_type":"compile","message":"cannot find type 'Foo'","file":"/App/View.swift","line":12,"column":5,"language":"swift"},{"error_type":"compile","message":"use of undeclared identifier","file":"/App/Shader.metal","line":3,"column":1,"language":"metal"}],"error_count":2,"warning_count":0,"log_path":"~/.flowdeck/logs/<hash>/build.log"}}

In text mode the same language appears as a bracket tag on each issue line (for example ✗ [Swift] cannot find type 'Foo').

Overview

FlowDeck for AI

Interactive Mode (TUI)

Core Features

Command Reference

Advanced

Support

Options

JSON Output

​Options

​JSON Output

Options

JSON Output