> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowdeck.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Build

> Build the project for simulator, device, or macOS

Build an Xcode project or workspace for a simulator, a physical device, or macOS. After running `flowdeck config set`, you can call `flowdeck build` with no extra flags.

```bash theme={null}
# After config set, build using saved settings
flowdeck build

# Build for iOS simulator
flowdeck build -w MyApp.xcworkspace -s MyApp -S "iPhone 16"

# Build for macOS
flowdeck build -w MyApp.xcworkspace -s MyApp -D "My Mac"

# Build for a physical device
flowdeck build -w MyApp.xcworkspace -s MyApp -D "John's iPhone"

# Release configuration
flowdeck build -C Release

# JSON output for automation
flowdeck build --json
flowdeck build --json --show-warnings

# Verbose output (show xcodebuild output)
flowdeck build -v

# Extra xcodebuild arguments
flowdeck build --xcodebuild-options='-quiet'
flowdeck build --xcodebuild-env='CI=true'

# Load settings from config file
flowdeck build --config .flowdeck/ci-config.json

# Show usage examples
flowdeck build --examples
```

## Options

| Option                        | Short | Description                                                                            |
| ----------------------------- | ----- | -------------------------------------------------------------------------------------- |
| `--examples`                  | `-e`  | Show usage examples                                                                    |
| `--project <path>`            | `-p`  | Project directory                                                                      |
| `--workspace <path>`          | `-w`  | Path to workspace (.xcworkspace) or project (.xcodeproj)                               |
| `--scheme <name>`             | `-s`  | Scheme name                                                                            |
| `--configuration <name>`      | `-C`  | Build configuration (Debug/Release)                                                    |
| `--simulator <name>`          | `-S`  | Simulator name/UDID (use `none` for legacy macOS builds)                               |
| `--device <name>`             | `-D`  | Device name/UDID (use "My Mac" or "My Mac Catalyst" for macOS)                         |
| `--derived-data-path <path>`  | `-d`  | Derived data path (default: `~/Library/Developer/FlowDeck/DerivedData`)                |
| `--json`                      | `-j`  | Output JSON/NDJSON events                                                              |
| `--show-warnings`             |       | Show compiler warnings (console output in text mode, `diagnostic` events in JSON mode) |
| `--verbose`                   | `-v`  | Show build output in console                                                           |
| `--config <path>`             | `-c`  | Load settings from an explicit command config file                                     |
| `--xcodebuild-options <args>` |       | Extra xcodebuild arguments                                                             |
| `--xcodebuild-env <vars>`     |       | Xcodebuild environment variables                                                       |

<Note>
  If both `--simulator` and `--device` are omitted, FlowDeck uses the saved target from `flowdeck config set` or interactive mode.
</Note>

<Note>
  `--config` here means the explicit command config file format. It is separate from `.flowdeck/config.json` and `.flowdeck/config.local.json`.
</Note>

<Note>
  On failed builds, FlowDeck prints the extracted failure reason plus the absolute persisted build log path. Read that log before rerunning with `--verbose`.
</Note>

## JSON Output

When `--json` is set, build emits NDJSON events (one JSON object per line). Example:

<Note>
  Compiler errors are always emitted in JSON failure events. Warning diagnostics are opt-in and emitted when `--show-warnings` is set. Warning snapshots are always reconciled and stored under DerivedData (`<DerivedData>/Warnings`) on every build.
</Note>

```json theme={null}
{"type":"status","stage":"COMPILING","message":"Compiling sources..."}
{"type":"result","success":true,"operation":"build","duration":12.5}
```

On failure, a `build_errors` event lists each error and warning. Items include an optional `language` token (`swift`, `cpp`, `objc`, `objcpp`, `c`, or `metal`) so you can tell which compiler produced each diagnostic. The field is omitted when the language can't be determined — issues with no source file (linker, code signing) or ambiguous files (such as `.h` headers). A grouped multi-target compile error has no single `file` but is still tagged when all of its diagnostics share one language, so `language` can appear without a `file`. Consumers should ignore unknown future values.

```json theme={null}
{"type":"build_errors","operation":"build","message":"Build failed with 2 errors","data":{"errors":[{"error_type":"compile","message":"cannot find type 'Foo'","file":"/App/View.swift","line":12,"column":5,"language":"swift"},{"error_type":"compile","message":"use of undeclared identifier","file":"/App/Shader.metal","line":3,"column":1,"language":"metal"}],"error_count":2,"warning_count":0,"log_path":"~/.flowdeck/logs/<hash>/build.log"}}
```

In text mode the same language appears as a bracket tag on each issue line (for example `✗ [Swift] cannot find type 'Foo'`).