Configuration File

FlowDeck has two JSON config formats, and they are easy to confuse:

Explicit command config used with --config
Project settings config stored in .flowdeck/config.json or .flowdeck/config.local.json

Use --config for reproducible command invocations in CI, scripts, and one-off runs. Use the project settings files for shared project defaults and per-scheme overrides inside a repository.

Today, explicit --config remains the clearest way to drive a full build, run, or test invocation from the CLI. The project settings files are the canonical shared on-disk format, while legacy sidecar files remain supported for compatibility in current runtime paths.

Explicit Command Config (`--config`)

flowdeck build --config path/to/config.json
flowdeck run --config path/to/config.json
flowdeck test --config path/to/config.json

Explicit Command Config Structure

{
  "workspace": "MyApp.xcworkspace",
  "scheme": "MyApp",
  "configuration": "Debug",
  "platform": "iOS",
  "version": "18.0",
  "deviceUdid": "00008030-001234567890ABCD",
  "simulatorUdid": "A1B2C3D4-E5F6-7890-ABCD-EF1234567890",
  "derivedDataPath": "~/Library/Developer/FlowDeck/DerivedData",
  "xcodebuild": {
    "args": ["-enableCodeCoverage", "YES"],
    "env": {
      "CI": "true"
    }
  },
  "appLaunch": {
    "args": ["-SkipOnboarding"],
    "env": {
      "DEBUG_MODE": "1"
    }
  }
}

Explicit Command Config Field Reference

Field	Type	Required	Description
`workspace`	string	Yes	Path to `.xcworkspace` or `.xcodeproj` (relative to project root)
`scheme`	string	Yes	Scheme name to build
`configuration`	string	No	Build configuration. Default: `Debug`. Options: `Debug`, `Release`, or custom
`platform`	string	No	Target platform. Options: `iOS`, `macOS`, `watchOS`, `tvOS`, `visionOS`
`version`	string	No	OS version (e.g., `18.0`, `17.5`). Uses latest available if not specified
`deviceUdid`	string	No	Physical device UDID for device builds
`simulatorUdid`	string	No	Simulator UDID for simulator builds
`derivedDataPath`	string	No	Custom derived data directory path (default: `~/Library/Developer/FlowDeck/DerivedData`)
`xcodebuild`	object	No	Passthrough settings for xcodebuild (see Xcodebuild Arguments)
`appLaunch`	object	No	Arguments and environment variables passed to the app at launch (run command only)

Explicit Command Config Target Resolution Priority

When determining the build target, FlowDeck uses this priority order:

deviceUdid - Physical device (if specified and connected)
simulatorUdid - Exact simulator by UDID
platform + version - Auto-resolve best matching simulator
platform: "macOS" - Native Mac build (no simulator needed)

Explicit Command Config Examples

Minimal iOS Configuration

{
  "workspace": "MyApp.xcworkspace",
  "scheme": "MyApp"
}

Uses default Debug configuration and latest available iOS simulator.

macOS Native Build

{
  "workspace": "MyApp.xcworkspace",
  "scheme": "MyApp-macOS",
  "platform": "macOS",
  "configuration": "Release"
}

Builds for macOS without simulator.

Physical Device Build

{
  "workspace": "MyApp.xcworkspace",
  "scheme": "MyApp",
  "deviceUdid": "00008030-001234567890ABCD"
}

Get device UDID from flowdeck device list --json.

Specific Simulator Version

{
  "workspace": "MyApp.xcworkspace",
  "scheme": "MyApp",
  "platform": "iOS",
  "version": "17.5"
}

Targets iOS 17.5 simulator specifically. If not available, FlowDeck will create one.

CI Release Build

{
  "workspace": "MyApp.xcworkspace",
  "scheme": "MyApp",
  "configuration": "Release",
  "platform": "iOS",
  "derivedDataPath": "/tmp/derived-data",
  "xcodebuild": {
    "args": [
      "-enableCodeCoverage", "YES",
      "CODE_SIGN_IDENTITY=-",
      "CODE_SIGNING_REQUIRED=NO"
    ],
    "env": {
      "CI": "true"
    }
  }
}

watchOS Build

{
  "workspace": "MyApp.xcworkspace",
  "scheme": "MyApp-Watch",
  "platform": "watchOS",
  "version": "11.0"
}

visionOS Build

{
  "workspace": "MyApp.xcworkspace",
  "scheme": "MyApp-Vision",
  "platform": "visionOS",
  "version": "2.0"
}

Project Settings Files

Project settings files are the shared on-disk format for project-level defaults:

.flowdeck/config.json — shared team config, usually committed
.flowdeck/config.local.json — per-user local override, usually gitignored

When config.local.json exists and is valid JSON, it fully replaces config.json — it is not merged with the shared file. This is enforced by both the CLI (build/run/test) and the macOS app’s Settings UI. If config.local.json exists but fails to parse, the CLI ignores it and falls back to config.json, printing a warning that names the file and the decode error rather than silently treating the project as unconfigured. The same applies to a malformed config.json with no local override present. (The macOS app’s Settings UI falls back the same way but does not yet surface an equivalent warning.)

Config Discovery

build, run, and test no longer require you to invoke them from the exact directory that owns .flowdeck/. FlowDeck walks upward from the working directory (or --project, if passed) looking for the nearest ancestor directory that contains .flowdeck/config.json, .flowdeck/config.local.json, or one of the legacy compatibility files, and loads project settings from there. The walk stops before your home directory and before /, so it never mistakes your ~/.flowdeck/ global state (CLI state, license cache, etc.) for a project config.

This discovered directory — the “config root” — is used only for loading .flowdeck/config.json and its sidecars. Derived data, saved state, and other paths keyed by project location still use the exact directory you invoked FlowDeck from or passed via --project.

Run with --verbose to see which directory FlowDeck resolved as the config root, along with the final merged launch args and env — see App Launch Settings for details.

Project Settings Structure

{
  "version": 1,
  "workspace": "MyApp.xcworkspace",
  "configuration": "Debug",
  "appLaunch": {
    "args": ["-SkipOnboarding"],
    "env": {
      "API_ENVIRONMENT": "staging"
    }
  },
  "xcodebuild": {
    "args": ["-enableCodeCoverage", "YES"],
    "env": {
      "CI": "true"
    }
  },
  "schemes": {
    "MyApp": {
      "configuration": "Release"
    },
    "MyAppUITests": {
      "appLaunch": {
        "args": ["-UITests"],
        "env": {
          "RESET_STATE": "1"
        }
      },
      "xcodebuild": {
        "args": ["-quiet"],
        "env": {}
      }
    }
  }
}

Project Settings Field Reference

Field	Type	Description
`version`	integer	Schema version. Defaults to `1`
`workspace`	string	Workspace or project path relative to the project root
`configuration`	string	Top-level fallback build configuration
`appLaunch`	object	Top-level fallback app launch settings
`xcodebuild`	object	Top-level fallback xcodebuild passthrough settings
`schemes`	object	Per-scheme overrides keyed by scheme name

Each entry under schemes may contain:

configuration
appLaunch
xcodebuild

Legacy Compatibility Files

Older FlowDeck setups may still contain:

.flowdeck/schemes.json
.flowdeck/app-launch-settings.json
.flowdeck/build-settings.json

Prefer the project settings files for new setup and new documentation. Compatibility rule:

Missing fields in the new project settings config may be filled from legacy files.
Present-but-empty fields are treated as intentional and should not fall back to legacy files.

Custom Derived Data

Specify a custom derived data path to:

Avoid conflicts with Xcode
Enable parallel builds with separate derived data
Use faster storage (e.g., RAM disk)

{
  "workspace": "MyApp.xcworkspace",
  "scheme": "MyApp",
  "derivedDataPath": "/tmp/flowdeck-derived-data"
}

Or on the command line:

flowdeck build --workspace MyApp.xcworkspace --scheme MyApp \
  --simulator "iPhone 16" \
  --derived-data-path ~/FlowDeck/DerivedData

xcodebuild Passthrough in `--config`

The xcodebuild section passes arguments and environment variables directly to xcodebuild:

{
  "workspace": "MyApp.xcworkspace",
  "scheme": "MyApp",
  "xcodebuild": {
    "args": [
      "-enableCodeCoverage", "YES",
      "-resultBundlePath", "./build/results.xcresult",
      "ONLY_ACTIVE_ARCH=NO"
    ],
    "env": {
      "CI": "true",
      "DEVELOPER_DIR": "/Applications/Xcode-15.4.app/Contents/Developer"
    }
  }
}

See Xcodebuild Arguments for complete passthrough documentation and common arguments.

App Launch Settings in `--config`

The appLaunch section passes arguments and environment variables to your app when it launches (for run command only):

{
  "workspace": "MyApp.xcworkspace",
  "scheme": "MyApp",
  "appLaunch": {
    "args": [
      "-AppleLanguages", "(en)",
      "-SkipOnboarding"
    ],
    "env": {
      "DEBUG_MODE": "1",
      "API_ENVIRONMENT": "staging"
    }
  }
}

These are passed to simctl launch or the device launch process, not to xcodebuild.

See App Launch Settings for complete documentation, common arguments, and local settings file support.

File Locations

Project Config

Store shared project settings in your repository:

your-project/
  .flowdeck/
    config.json
    config.local.json
  MyApp.xcworkspace

Keep config.local.json gitignored so local overrides do not replace the shared team config for everyone else.

Multiple Configurations

Create separate explicit --config files for different scenarios:

# Development
flowdeck run --config .flowdeck/dev-config.json

# CI builds
flowdeck build --config .flowdeck/ci-config.json

# Release builds
flowdeck build --config .flowdeck/release-config.json

CLI Override

Command-line parameters override config file values:

# Config has configuration: "Debug", but this builds Release
flowdeck build --config config.json --configuration Release

Generating Config Files

From Interactive Mode

Run flowdeck -i in your project directory
Configure your build settings
Press P, then select Export Project Config
Save the exported explicit command config where you want to reuse it for --config

Troubleshooting

Config File Not Found

Ensure the path is correct:

# Absolute path
flowdeck build --config /path/to/config.json

# Relative to current directory
flowdeck build --config ./configs/build.json

Invalid JSON

Validate your JSON syntax:

# Check if valid JSON
cat config.json | jq .

Workspace Not Found

Workspace paths are relative to the project root (where you run FlowDeck), not the config file location:

{
  "workspace": "MyApp.xcworkspace"
}

If your workspace is in a subdirectory:

{
  "workspace": "src/MyApp.xcworkspace"
}

Simulator Not Available

If the specified simulator doesn’t exist:

FlowDeck will try to resolve from platform + version
If a matching runtime exists, it creates a new simulator
Otherwise, it uses the first available simulator for that platform

To ensure consistency, use simulator UDID:

# Get available simulators
flowdeck simulator list --json

# Use UDID in config
{
  "simulatorUdid": "A1B2C3D4-E5F6-7890-ABCD-EF1234567890"
}

Overview

FlowDeck for AI

Interactive Mode (TUI)

Core Features

Command Reference

Advanced

Support

Configuration File

Explicit Command Config (`--config`)

Explicit Command Config Structure

Explicit Command Config Field Reference

Explicit Command Config Target Resolution Priority

Explicit Command Config Examples

Project Settings Files

Config Discovery

Project Settings Structure

Project Settings Field Reference

Legacy Compatibility Files

Custom Derived Data

xcodebuild Passthrough in `--config`

App Launch Settings in `--config`

File Locations

Project Config

Multiple Configurations

CLI Override

Generating Config Files

From Interactive Mode

Troubleshooting

Config File Not Found

Invalid JSON

Workspace Not Found

Simulator Not Available

​Explicit Command Config (--config)

​Explicit Command Config Structure

​Explicit Command Config Field Reference

​Explicit Command Config Target Resolution Priority

​Explicit Command Config Examples

​Project Settings Files

​Config Discovery

​Project Settings Structure

​Project Settings Field Reference

​Legacy Compatibility Files

​Custom Derived Data

​xcodebuild Passthrough in --config

​App Launch Settings in --config

​File Locations

​Project Config

​Multiple Configurations

​CLI Override

​Generating Config Files

​From Interactive Mode

​Troubleshooting

​Config File Not Found

​Invalid JSON

​Workspace Not Found

​Simulator Not Available

Explicit Command Config (`--config`)

Explicit Command Config Structure

Explicit Command Config Field Reference

Explicit Command Config Target Resolution Priority

Explicit Command Config Examples

Project Settings Files

Config Discovery

Project Settings Structure

Project Settings Field Reference

Legacy Compatibility Files

Custom Derived Data

xcodebuild Passthrough in `--config`

App Launch Settings in `--config`

File Locations

Project Config

Multiple Configurations

CLI Override

Generating Config Files

From Interactive Mode

Troubleshooting

Config File Not Found

Invalid JSON

Workspace Not Found

Simulator Not Available