Xcodebuild Arguments

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

Methods Overview

Method	Best For	Priority
CLI Options	Quick one-off builds, testing flags	Highest
Legacy Local Build Settings	Compatibility with older project setups	Medium
Config File	CI/CD, reproducible builds	Lowest

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'

Test Result Bundle Routing

flowdeck test owns one result bundle per xcodebuild phase so each bundle is finalized exactly once:

build-for-testing writes ~/.flowdeck/logs/<project-hash>/build-test.xcresult.
test-without-building writes ~/.flowdeck/logs/<project-hash>/test.xcresult by default.
A caller-supplied -resultBundlePath overrides only the test-phase path.

Both -resultBundlePath <path> and -resultBundlePath=<path> are accepted. When arguments from multiple sources contain the flag, the last valid value wins. FlowDeck removes the duplicates before invoking xcodebuild and normalizes the selected result to an absolute path. The final flowdeck.test JSON snapshot reports that same path as resultBundlePath.

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

Field	Type	Description
`args`	array	Arguments appended to xcodebuild command line
`env`	object	Environment 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 test --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:

Config file (lowest priority) - base configuration
Local build-settings.json - compatibility override for current CLI auto-load behavior
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

Argument	Description
`ONLY_ACTIVE_ARCH=YES`	Build only for active architecture (faster debug builds)
`ONLY_ACTIVE_ARCH=NO`	Build for all architectures (required for distribution)
`CODE_SIGN_IDENTITY=-`	Disable code signing
`CODE_SIGNING_REQUIRED=NO`	Skip code signing requirement
`GCC_TREAT_WARNINGS_AS_ERRORS=YES`	Fail build on C/Obj-C warnings
`SWIFT_TREAT_WARNINGS_AS_ERRORS=YES`	Fail build on Swift warnings

Xcodebuild Flags

Flag	Description
`-quiet`	Suppress most xcodebuild output
`-enableCodeCoverage YES`	Enable code coverage collection
`-resultBundlePath <path>`	Override the finalized test-phase xcresult path during `flowdeck test`; the last valid value wins
`-allowProvisioningUpdates`	Allow automatic provisioning updates
`-allowProvisioningDeviceRegistration`	Allow automatic device registration
`-parallel-testing-enabled YES`	Enable parallel test execution
`-parallel-testing-worker-count <n>`	Number of parallel test workers

Compiler Flags

Argument	Description
`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

Variable	Description
`CI`	Indicates CI environment (affects some Xcode behaviors)
`DEVELOPER_DIR`	Override Xcode installation path
`XCODE_XCCONFIG_FILE`	Path 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

Code Coverage

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

Parallel Testing

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

CI Build (No Code Signing)

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

Use Different Xcode Version

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

Strict Warnings

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

Address Sanitizer

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

Quiet Build with Coverage (CI)

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

Overview

FlowDeck for AI

Interactive Mode (TUI)

Core Features

Command Reference

Advanced

Support

Xcodebuild Arguments

Methods Overview

Preferred Project Settings Format

CLI Options

Xcodebuild Arguments

Xcodebuild Environment

Combining Options

Works with All Commands

Test Result Bundle Routing

Legacy Local Build Settings

Structure

Config File

Priority and Merging

Common Arguments Reference

Build Settings

Xcodebuild Flags

Compiler Flags

Environment Variables

Via CLI

In Local Settings

In Config File

Common Environment Variables

Use Cases

Viewing the Final Command

Troubleshooting

Values Starting with Dash

Build Settings Format

JSON Array Format

​Methods Overview

​Preferred Project Settings Format

​CLI Options

​Xcodebuild Arguments

​Xcodebuild Environment

​Combining Options

​Works with All Commands

​Test Result Bundle Routing

​Legacy Local Build Settings

​Structure

​Config File

​Priority and Merging

​Common Arguments Reference

​Build Settings

​Xcodebuild Flags

​Compiler Flags

​Environment Variables

​Via CLI

​In Local Settings

​In Config File

​Common Environment Variables

​Use Cases

​Viewing the Final Command

​Troubleshooting

​Values Starting with Dash

​Build Settings Format

​JSON Array Format

Methods Overview

Preferred Project Settings Format

CLI Options

Xcodebuild Arguments

Xcodebuild Environment

Combining Options

Works with All Commands

Test Result Bundle Routing

Legacy Local Build Settings

Structure

Config File

Priority and Merging

Common Arguments Reference

Build Settings

Xcodebuild Flags

Compiler Flags

Environment Variables

Via CLI

In Local Settings

In Config File

Common Environment Variables

Use Cases

Viewing the Final Command

Troubleshooting

Values Starting with Dash

Build Settings Format

JSON Array Format