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 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
Legacy Local Build SettingsCompatibility with older project setupsMedium
Config FileCI/CD, reproducible buildsLowest
When multiple sources provide arguments, they’re merged with CLI taking highest priority.

​
Preferred Project Settings Format

For shared project settings, prefer storing xcodebuild passthrough values in:
  • .flowdeck/config.json
  • .flowdeck/config.local.json
Example: 
{
  "xcodebuild": {
    "args": ["-enableCodeCoverage", "YES"],
    "env": {
      "CI": "true"
    }
  },
  "schemes": {
    "MyApp": {
      "xcodebuild": {
        "args": ["-quiet"],
        "env": {}
      }
    }
  }
}
Use the top-level xcodebuild block for project-wide defaults, and schemes.<scheme>.xcodebuild for per-scheme overrides.

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

​
Legacy 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 a legacy compatibility format and is still auto-loaded by current CLI runtime paths.
Prefer .flowdeck/config.json or .flowdeck/config.local.json for new setup. Keep .flowdeck/build-settings.json only when you need compatibility with older workflows.

​
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
--config uses the explicit command config format, which is separate from .flowdeck/config.json and .flowdeck/config.local.json. See Configuration File for the difference.

​
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 - compatibility override for current CLI auto-load behavior
  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
The canonical shared project-settings format is xcodebuild inside .flowdeck/config.json or .flowdeck/config.local.json. The separate build-settings.json file remains a legacy compatibility input.

​
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"]
  }
}