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

# 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}
```