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

# Building & Running

> Build and run iOS/macOS apps from the command line

FlowDeck CLI provides powerful build and run capabilities optimized for command-line workflows and CI/CD integration.

## Recommended Workflow

The recommended workflow is to use `flowdeck config set` to save project settings, then run commands without parameters:

```bash theme={null}
# 1. Discover project structure
flowdeck context --json

# 2. Initialize with discovered settings
flowdeck config set -w MyApp.xcworkspace -s MyApp -S "iPhone 16"

# 3. Run commands without parameters
flowdeck build
flowdeck run
flowdeck test
flowdeck clean
```

<Tip>
  After running `flowdeck config set`, all subsequent commands use the saved settings automatically. You only need to specify parameters when you want to override the defaults.
</Tip>

<Note>
  `flowdeck config set` saves runtime selection state. Shared project settings live separately in `.flowdeck/config.json` and `.flowdeck/config.local.json`, while explicit `--config` files remain the portable way to script a full command invocation.
</Note>

## Project Context

The `context` command gives you (or your AI agent) everything needed to understand your project at a glance. Available schemes, build configurations, simulators, and connected devices.

```bash theme={null}
# Get app context
flowdeck context

# JSON output (recommended for AI agents)
flowdeck context --json
```

## Building Your App

### Basic Build

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

# Or specify parameters directly
flowdeck build -w MyApp.xcworkspace -s MyApp -S "iPhone 16"
```

### Build for macOS

Use `--device "My Mac"` for macOS targets:

```bash theme={null}
flowdeck build -w MyApp.xcworkspace -s MyApp -D "My Mac"
```

### Build for Physical Device

Use `--device` with the device name or UDID:

```bash theme={null}
# By device name (partial match, case-insensitive)
flowdeck build -w MyApp.xcworkspace -s MyApp -D "iPhone"
flowdeck build -w MyApp.xcworkspace -s MyApp -D "John's iPhone"

# By device UDID (exact match)
flowdeck build -w MyApp.xcworkspace -s MyApp -D "00008130-001245110C08001C"
```

<Tip>
  Use `flowdeck device list` to see available devices and their UDIDs.
</Tip>

### Build Configurations

Specify Debug or Release configuration:

```bash theme={null}
# Debug build (default)
flowdeck build -C Debug

# Release build
flowdeck build -C Release
```

### Custom Xcodebuild Options

Pass arguments directly to xcodebuild:

```bash theme={null}
# Code coverage
flowdeck build --xcodebuild-options='-enableCodeCoverage YES'

# Quiet mode
flowdeck build --xcodebuild-options='-quiet'

# Environment variables
flowdeck build --xcodebuild-env='CI=true'
```

<Info>
  For the complete list of build options, see the [Build Command Reference](/cli/commands/build).
</Info>

## Running Your App

### Build and Run on Simulator

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

# Or specify parameters directly
flowdeck run -w MyApp.xcworkspace -s MyApp -S "iPhone 16"
```

This command:

1. Builds the app
2. Opens Simulator.app (if iOS)
3. Boots the simulator (or uses already running)
4. Installs the app
5. Launches the app

<Note>
  `flowdeck run` launches app bundle schemes only. Pure Swift Package targets should use `flowdeck build` or `flowdeck test`; use `-w` with an Xcode app workspace or project when the goal is to launch an app.
</Note>

### Build and Run on macOS

```bash theme={null}
flowdeck run -w MyApp.xcworkspace -s MyApp -D "My Mac"
```

### Mac Catalyst

Run an iOS app as Mac Catalyst using `--device "My Mac Catalyst"`:

```bash theme={null}
flowdeck run -w MyApp.xcworkspace -s MyApp -D "My Mac Catalyst"
```

This builds the app with `platform=macOS,variant=Mac Catalyst` and runs it natively on your Mac.

<Tip>
  Use `flowdeck device list` to see all available targets including "My Mac" and "My Mac Catalyst".
</Tip>

### Build and Run on Physical Device

```bash theme={null}
flowdeck run -w MyApp.xcworkspace -s MyApp -D "John's iPhone"
```

<Info>
  For the complete list of run options including `--interactive` and `--wait-for-debugger`, see the [Run Command Reference](/cli/commands/build#flowdeck-run).
</Info>

### Run with Log Streaming

Stream OSLog output after launching:

```bash theme={null}
flowdeck run -S "iPhone 16" --log
flowdeck run -S "iPhone 16" -l  # Short form
```

### Run Without Building

Skip the build step and launch an existing app with `--no-build`:

```bash theme={null}
# Run the last built app without rebuilding
flowdeck run --no-build

# Or specify a target
flowdeck run -S "iPhone 16" --no-build
flowdeck run -D "My Mac" --no-build
```

This is useful for:

* Quick iteration when you haven't changed code
* Testing different launch configurations
* Launching after a manual Xcode build

**Behavior:**

* If a built app exists, it shows "⏭️ Running build from X ago" and launches immediately
* If no built app is found, it automatically falls back to building from source with "⚠️ No built app found. Building from source..."

<Tip>
  In interactive mode, use <kbd>Shift+R</kbd> to run without building.
</Tip>

### App Launch Arguments

Pass arguments and environment variables to your app:

```bash theme={null}
# Launch arguments
flowdeck run -S "iPhone 16" --launch-options='-AppleLanguages (en) -SkipOnboarding'

# Environment variables
flowdeck run -S "iPhone 16" --launch-env='DEBUG=1 API_ENV=staging'
```

## JSON Output for Automation

Use `--json` for machine-readable output, essential for CI/CD pipelines:

```bash theme={null}
flowdeck build --json
flowdeck build --json --show-warnings
flowdeck run --json
flowdeck run --json --show-warnings
flowdeck test --json
```

<Note>
  Compiler warnings are hidden by default in regular and JSON output. Add `--show-warnings` to `build` or `run` to surface them (console output in text mode, `diagnostic` events in JSON mode). Warning snapshots are always reconciled and stored in `<DerivedData>/Warnings`, even without `--show-warnings`.
</Note>

<Info>
  For complete CI/CD setup including license configuration and pipeline examples, see [CI/CD Integration](/cli/ci-cd).
</Info>

This outputs NDJSON (newline-delimited JSON) events:

```json theme={null}
{"type":"app_log","message":"Build Started"}
{"type":"app_log","message":"Resolving Packages"}
{"type":"app_log","message":"Building"}
{"type":"app_log","message":"Build Completed"}
```

## Custom Derived Data

FlowDeck uses `~/Library/Developer/FlowDeck/DerivedData` by default. Override it when you need isolation across builds:

```bash theme={null}
flowdeck build -d ~/Library/Developer/FlowDeck/DerivedData-CI
```

## Cleaning

Clean build artifacts before rebuilding:

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

# Clean scheme artifacts
flowdeck clean -w MyApp.xcworkspace -s MyApp

# Clean all FlowDeck derived data
flowdeck clean --derived-data

# Clean all Xcode derived data
flowdeck clean --xcode-derived-data

# Clean Xcode cache
flowdeck clean --xcode-cache

# Clean everything
flowdeck clean --all
```

## Config Files

Use the `--config` option to pass a set of pre-defined parameters from a JSON file. This is especially useful for CI/CD pipelines and complex build configurations.

```bash theme={null}
# Build with a config file
flowdeck build --config .flowdeck/ci-config.json

# Run with a config file
flowdeck run --config .flowdeck/ci-config.json
```

This `--config` file is the explicit command config format, not the same as `.flowdeck/config.json` or `.flowdeck/config.local.json`.

See [Configuration File](/cli/configuration-file) for the complete reference and the distinction between the two formats.

## Performance Optimization

FlowDeck CLI automatically:

* Detects CPU core count for parallel builds
* Uses optimized build settings
* Enables incremental compilation

## Troubleshooting

### "Workspace not found"

Ensure you're specifying the correct path:

```bash theme={null}
# Use full path if needed
flowdeck build -w /path/to/MyApp.xcworkspace -s MyApp -S "iPhone 16"

# Or navigate to the project directory and configure once
cd ~/Projects/MyApp
flowdeck config set -w MyApp.xcworkspace -s MyApp -S "iPhone 16"
flowdeck build
```

### "Scheme not found"

Use `flowdeck context --json` to discover available schemes:

```bash theme={null}
flowdeck context --json | jq '.schemes'
```

### "Simulator not found"

List available simulators first:

```bash theme={null}
flowdeck simulator list -P iOS -A
```

### "Build failed"

Try cleaning and rebuilding:

```bash theme={null}
flowdeck clean --all
flowdeck build
```

Check the error output for specific issues like missing dependencies or code signing problems.