> ## 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.

# Configuration File

> Understand FlowDeck's explicit --config files and project settings files

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

1. **Explicit command config** used with `--config`
2. **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.

<Note>
  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.
</Note>

## Explicit Command Config (`--config`)

```bash theme={null}
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

```json theme={null}
{
  "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](/cli/xcodebuild-args))   |
| `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:

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

## Explicit Command Config Examples

<AccordionGroup>
  <Accordion title="Minimal iOS Configuration">
    ```json theme={null}
    {
      "workspace": "MyApp.xcworkspace",
      "scheme": "MyApp"
    }
    ```

    Uses default Debug configuration and latest available iOS simulator.
  </Accordion>

  <Accordion title="macOS Native Build">
    ```json theme={null}
    {
      "workspace": "MyApp.xcworkspace",
      "scheme": "MyApp-macOS",
      "platform": "macOS",
      "configuration": "Release"
    }
    ```

    Builds for macOS without simulator.
  </Accordion>

  <Accordion title="Physical Device Build">
    ```json theme={null}
    {
      "workspace": "MyApp.xcworkspace",
      "scheme": "MyApp",
      "deviceUdid": "00008030-001234567890ABCD"
    }
    ```

    Get device UDID from `flowdeck device list --json`.
  </Accordion>

  <Accordion title="Specific Simulator Version">
    ```json theme={null}
    {
      "workspace": "MyApp.xcworkspace",
      "scheme": "MyApp",
      "platform": "iOS",
      "version": "17.5"
    }
    ```

    Targets iOS 17.5 simulator specifically. If not available, FlowDeck will create one.
  </Accordion>

  <Accordion title="CI Release Build">
    ```json theme={null}
    {
      "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"
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="watchOS Build">
    ```json theme={null}
    {
      "workspace": "MyApp.xcworkspace",
      "scheme": "MyApp-Watch",
      "platform": "watchOS",
      "version": "11.0"
    }
    ```
  </Accordion>

  <Accordion title="visionOS Build">
    ```json theme={null}
    {
      "workspace": "MyApp.xcworkspace",
      "scheme": "MyApp-Vision",
      "platform": "visionOS",
      "version": "2.0"
    }
    ```
  </Accordion>
</AccordionGroup>

## 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, it fully replaces `config.json`. It is not merged with the shared file.

### Project Settings Structure

```json theme={null}
{
  "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)

```json theme={null}
{
  "workspace": "MyApp.xcworkspace",
  "scheme": "MyApp",
  "derivedDataPath": "/tmp/flowdeck-derived-data"
}
```

Or on the command line:

```bash theme={null}
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:

```json theme={null}
{
  "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"
    }
  }
}
```

<Info>
  See [Xcodebuild Arguments](/cli/xcodebuild-args) for complete passthrough documentation and common arguments.
</Info>

## App Launch Settings in `--config`

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

```json theme={null}
{
  "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.

<Info>
  See [App Launch Settings](/cli/app-launch-settings) for complete documentation, common arguments, and local settings file support.
</Info>

## 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:

```bash theme={null}
# 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:

```bash theme={null}
# Config has configuration: "Debug", but this builds Release
flowdeck build --config config.json --configuration Release
```

## Generating Config Files

### From Interactive Mode

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

## Troubleshooting

### Config File Not Found

Ensure the path is correct:

```bash theme={null}
# 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:

```bash theme={null}
# 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:

```json theme={null}
{
  "workspace": "MyApp.xcworkspace"
}
```

If your workspace is in a subdirectory:

```json theme={null}
{
  "workspace": "src/MyApp.xcworkspace"
}
```

### Simulator Not Available

If the specified simulator doesn't exist:

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

To ensure consistency, use simulator UDID:

```bash theme={null}
# Get available simulators
flowdeck simulator list --json

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