Skip to main content
FlowDeck provides full access to xcodebuild’s capabilities through custom arguments and environment variables. You can configure builds using three methods.

​
Methods Overview

MethodBest ForPriority
CLI OptionsQuick one-off builds, testing flagsHighest
Local Build SettingsProject-wide defaultsMedium
Config FileCI/CD, reproducible buildsLowest
When multiple sources provide arguments, they’re merged with CLI taking highest priority.

​
CLI Options

​
Xcodebuild Arguments

Use --xcodebuild-options to pass arguments to xcodebuild: 
# Single argument
flowdeck build -w App.xcworkspace -s MyApp -S "iPhone 16" \
  --xcodebuild-options='-enableCodeCoverage YES'

# Multiple arguments
flowdeck build -w App.xcworkspace -s MyApp -S "iPhone 16" \
  --xcodebuild-options='-enableCodeCoverage YES ONLY_ACTIVE_ARCH=NO GCC_TREAT_WARNINGS_AS_ERRORS=YES'

# Build settings (KEY=VALUE format)
flowdeck run -w App.xcworkspace -s MyApp -S "iPhone 16" \
  --xcodebuild-options='CODE_SIGN_IDENTITY=- CODE_SIGNING_REQUIRED=NO'
Use = syntax (e.g., --xcodebuild-options='...') when values start with - to avoid argument parsing issues.

​
Xcodebuild Environment

Use --xcodebuild-env to set environment variables for the build: 
flowdeck build -w App.xcworkspace -s MyApp -S "iPhone 16" \
  --xcodebuild-env='CI=true DEVELOPER_DIR=/Applications/Xcode-15.4.app/Contents/Developer'

​
Combining Options

All options can be combined: 
flowdeck build -w App.xcworkspace -s MyApp -S "iPhone 16" \
  --xcodebuild-options='-quiet -enableCodeCoverage YES' \
  --xcodebuild-env='CI=true'

​
Works with All Commands

# Build
flowdeck build -w App.xcworkspace -s MyApp -S "iPhone 16" \
  --xcodebuild-options='-enableCodeCoverage YES'

# Run
flowdeck run -w App.xcworkspace -s MyApp -S "iPhone 16" \
  --xcodebuild-options='ONLY_ACTIVE_ARCH=YES'

# Test
flowdeck test -w App.xcworkspace -s MyApp -S "iPhone 16" \
  --xcodebuild-options='-parallel-testing-enabled YES'

​
Local Build Settings

Create .flowdeck/build-settings.json in your project root for settings that apply to all FlowDeck commands automatically: 
{
  "args": [
    "ONLY_ACTIVE_ARCH=YES",
    "GCC_TREAT_WARNINGS_AS_ERRORS=YES",
    "-enableCodeCoverage", "YES"
  ],
  "env": {
    "CUSTOM_BUILD_VAR": "value"
  }
}
This file is auto-loaded whenever you run FlowDeck commands from that project directory.
Add .flowdeck/build-settings.json to version control to share settings across your team.

​
Structure

FieldTypeDescription
argsarrayArguments appended to xcodebuild command line
envobjectEnvironment variables set for xcodebuild process

​
Config File

Include xcodebuild settings in your --config JSON file: 
{
  "workspace": "MyApp.xcworkspace",
  "scheme": "MyApp",
  "platform": "iOS",
  "xcodebuild": {
    "args": [
      "-enableCodeCoverage", "YES",
      "-resultBundlePath", "./build/results.xcresult"
    ],
    "env": {
      "CI": "true"
    }
  }
}
Use with: 
flowdeck build --config path/to/config.json
See Configuration File for complete config file documentation.

​
Priority and Merging

When arguments come from multiple sources, they’re combined in this order:
  1. Config file (lowest priority) - base configuration
  2. Local build-settings.json - overrides config file
  3. CLI options (highest priority) - appended last, takes effect
Example: 
# Config file has: ONLY_ACTIVE_ARCH=YES
# Local settings has: GCC_TREAT_WARNINGS_AS_ERRORS=YES
# CLI: --xcodebuild-options='ONLY_ACTIVE_ARCH=NO'

# Final xcodebuild args include:
# ONLY_ACTIVE_ARCH=YES (from config, overridden)
# GCC_TREAT_WARNINGS_AS_ERRORS=YES (from local)
# ONLY_ACTIVE_ARCH=NO (from CLI, takes effect because it's last)

​
Common Arguments Reference

​
Build Settings

ArgumentDescription
ONLY_ACTIVE_ARCH=YESBuild only for active architecture (faster debug builds)
ONLY_ACTIVE_ARCH=NOBuild for all architectures (required for distribution)
CODE_SIGN_IDENTITY=-Disable code signing
CODE_SIGNING_REQUIRED=NOSkip code signing requirement
GCC_TREAT_WARNINGS_AS_ERRORS=YESFail build on C/Obj-C warnings
SWIFT_TREAT_WARNINGS_AS_ERRORS=YESFail build on Swift warnings

​
Xcodebuild Flags

FlagDescription
-quietSuppress most xcodebuild output
-enableCodeCoverage YESEnable code coverage collection
-resultBundlePath <path>Save test results to xcresult bundle
-allowProvisioningUpdatesAllow automatic provisioning updates
-allowProvisioningDeviceRegistrationAllow automatic device registration
-parallel-testing-enabled YESEnable parallel test execution
-parallel-testing-worker-count <n>Number of parallel test workers

​
Compiler Flags

ArgumentDescription
OTHER_SWIFT_FLAGS=<flags>Additional Swift compiler flags
OTHER_CFLAGS=<flags>Additional C compiler flags
OTHER_LDFLAGS=<flags>Additional linker flags

​
Environment Variables

Set environment variables for the xcodebuild process:

​
Via CLI

flowdeck build -w App.xcworkspace -s MyApp -S "iPhone 16" \
  --xcodebuild-env='CI=true DEVELOPER_DIR=/Applications/Xcode-15.4.app/Contents/Developer'

​
In Local Settings

{
  "args": [],
  "env": {
    "CI": "true",
    "DEVELOPER_DIR": "/Applications/Xcode-15.4.app/Contents/Developer"
  }
}

​
In Config File

{
  "workspace": "MyApp.xcworkspace",
  "scheme": "MyApp",
  "xcodebuild": {
    "env": {
      "DEVELOPER_DIR": "/Applications/Xcode-15.4.app/Contents/Developer"
    }
  }
}

​
Common Environment Variables

VariableDescription
CIIndicates CI environment (affects some Xcode behaviors)
DEVELOPER_DIROverride Xcode installation path
XCODE_XCCONFIG_FILEPath to custom xcconfig file

​
Use Cases

flowdeck test -w App.xcworkspace -s MyApp -S "iPhone 16" \
  --xcodebuild-options='-enableCodeCoverage YES -resultBundlePath ./coverage/results.xcresult'
Extract coverage after tests:
xcrun xccov view --report ./coverage/results.xcresult

flowdeck test -w App.xcworkspace -s MyApp -S "iPhone 16" \
  --xcodebuild-options='-parallel-testing-enabled YES -parallel-testing-worker-count 4'

flowdeck build -w App.xcworkspace -s MyApp -S "iPhone 16" \
  --xcodebuild-options='CODE_SIGN_IDENTITY=- CODE_SIGNING_REQUIRED=NO'

flowdeck build -w App.xcworkspace -s MyApp -S "iPhone 16" \
  --xcodebuild-env='DEVELOPER_DIR=/Applications/Xcode-15.4.app/Contents/Developer'
Or create .flowdeck/build-settings.json:
{
  "args": [],
  "env": {
    "DEVELOPER_DIR": "/Applications/Xcode-15.4.app/Contents/Developer"
  }
}

flowdeck build -w App.xcworkspace -s MyApp -S "iPhone 16" \
  --xcodebuild-options='GCC_TREAT_WARNINGS_AS_ERRORS=YES SWIFT_TREAT_WARNINGS_AS_ERRORS=YES'

flowdeck build -w App.xcworkspace -s MyApp -S "iPhone 16" \
  --xcodebuild-options='"OTHER_SWIFT_FLAGS=-sanitize=address" "OTHER_CFLAGS=-fsanitize=address" "OTHER_LDFLAGS=-fsanitize=address"'

flowdeck test -w App.xcworkspace -s MyApp -S "iPhone 16" \
  --xcodebuild-options='-quiet -enableCodeCoverage YES' \
  --xcodebuild-env='CI=true'

​
Viewing the Final Command

Use --dry-run to see the complete xcodebuild command with all arguments without executing: 
flowdeck build -w App.xcworkspace -s MyApp -S "iPhone 16" --dry-run \
  --xcodebuild-options='-enableCodeCoverage YES'
Use --verbose to see the command during actual execution: 
flowdeck build -w App.xcworkspace -s MyApp -S "iPhone 16" --verbose \
  --xcodebuild-options='-enableCodeCoverage YES'

​
Troubleshooting

​
Values Starting with Dash

Use = syntax when values start with -: 
# Won't work - ArgumentParser sees -quiet as a new option
flowdeck build ... --xcodebuild-options -quiet

# Works - use = syntax
flowdeck build ... --xcodebuild-options='-quiet -enableCodeCoverage YES'

​
Build Settings Format

Use KEY=VALUE format (no spaces around =): 
# Correct
flowdeck build ... --xcodebuild-options='ONLY_ACTIVE_ARCH=YES'

# Wrong
flowdeck build ... --xcodebuild-options='ONLY_ACTIVE_ARCH = YES'

​
JSON Array Format

In config files, each argument is a separate array element: 
{
  "xcodebuild": {
    "args": ["-enableCodeCoverage", "YES"]
  }
}
Not: 
{
  "xcodebuild": {
    "args": ["-enableCodeCoverage YES"]
  }
}