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

# Automation & Scripting

> Use FlowDeck programmatically with JSON output, config files, and shell scripting

FlowDeck is designed for automation. Every command supports JSON output for machine parsing and configuration files for reproducible builds, making it ideal for CI/CD pipelines, shell scripts, and AI-powered development tools.

## Quick Start

```bash theme={null}
# Save project settings once
flowdeck config set -w MyApp.xcworkspace -s MyApp -S "iPhone 16"

# Run commands without repeating options
flowdeck build --json
flowdeck test --json
flowdeck run
```

## JSON Output Mode

Add `--json` or `-j` to any command for machine-readable NDJSON (newline-delimited JSON) output:

```bash theme={null}
flowdeck build --json
flowdeck test --json
flowdeck simulator list --json
```

### Event Types

FlowDeck emits structured events that you can parse line-by-line:

| Event Type      | Description            | When Emitted                                                   |
| --------------- | ---------------------- | -------------------------------------------------------------- |
| `status`        | Progress updates       | During operations (building, testing, launching)               |
| `output`        | Raw process output     | Build output, test output, logs                                |
| `diagnostic`    | Compiler diagnostics   | Errors on failures; warnings when `--show-warnings` is enabled |
| `result`        | Operation completion   | At end of build, test, clean operations                        |
| `app_log`       | Informational messages | Status messages, configuration info                            |
| `message`       | Structured messages    | Warnings, errors, info with context                            |
| `test_started`  | Test case started      | When a test begins                                             |
| `test_passed`   | Test case passed       | When a test succeeds                                           |
| `test_failed`   | Test case failed       | When a test fails (includes failure details)                   |
| `test_skipped`  | Test case skipped      | When a test is skipped                                         |
| `configuration` | Build configuration    | At start of build/run/test                                     |

`configuration` events include the resolved Derived Data path so automation can trace build artifacts.

### Event Structure

All events follow a standardized structure:

```json theme={null}
{
  "type": "status",
  "timestamp": "2025-01-13T10:30:45.123Z",
  "operation": "BUILD",
  "message": "Building",
  "stage": "BUILDING",
  "data": {
    "progress": 0.5,
    "phase": "Compiling"
  }
}
```

### Parsing JSON Output

Use `jq` or similar tools to extract specific information:

```bash theme={null}
# Check if build succeeded
flowdeck build --json | jq -s 'last | select(.type == "result") | .data.success'

# Get all errors
flowdeck build --json | jq 'select(.type == "diagnostic") | select(.data.severity == "error")'

# Get warning diagnostics (opt-in)
flowdeck build --json --show-warnings | jq 'select(.type == "diagnostic") | select(.data.severity == "warning")'

# Warning snapshots are always reconciled into DerivedData
# <DerivedData>/Warnings/*.json

# Count test failures
flowdeck test --json | jq -s '[.[] | select(.type == "test_failed")] | length'

# Get test summary
flowdeck test --json | jq 'select(.type == "result") | .data.summary'

```

### Shell Script Example

```bash theme={null}
#!/bin/bash
set -e

# Build and check result
flowdeck build --json | while IFS= read -r line; do
  type=$(echo "$line" | jq -r '.type')

  if [ "$type" = "diagnostic" ]; then
    severity=$(echo "$line" | jq -r '.data.severity')
    message=$(echo "$line" | jq -r '.message')
    if [ "$severity" = "error" ]; then
      echo "ERROR: $message" >&2
    fi
  fi

  if [ "$type" = "result" ]; then
    success=$(echo "$line" | jq -r '.data.success')
    if [ "$success" = "true" ]; then
      echo "Build succeeded"
    else
      echo "Build failed" >&2
      exit 1
    fi
  fi
done
```

## Configuration Files

Store build settings in JSON files for reproducible builds:

```bash theme={null}
flowdeck build --config .flowdeck/ci-config.json
flowdeck test --config .flowdeck/ci-config.json --json
```

<Note>
  These examples use the explicit `--config` file format for scripted runs. That format is separate from the project settings files at `.flowdeck/config.json` and `.flowdeck/config.local.json`.
</Note>

### Config File Structure

```json theme={null}
{
  "workspace": "MyApp.xcworkspace",
  "scheme": "MyApp",
  "configuration": "Debug",
  "platform": "iOS",
  "version": "18.0",
  "simulatorUdid": "A1B2C3D4-E5F6-7890-ABCD-EF1234567890",
  "derivedDataPath": "/tmp/flowdeck-derived-data",
  "xcodebuild": {
    "args": ["-enableCodeCoverage", "YES"],
    "env": {
      "CI": "true"
    }
  },
  "appLaunch": {
    "args": ["-SkipOnboarding"],
    "env": {
      "DEBUG_MODE": "1"
    }
  }
}
```

### Config File Fields

| Field             | Type   | Required | Description                                                                         |
| ----------------- | ------ | -------- | ----------------------------------------------------------------------------------- |
| `workspace`       | string | Yes      | Path to `.xcworkspace` or `.xcodeproj`                                              |
| `scheme`          | string | Yes      | Scheme name to build                                                                |
| `configuration`   | string | No       | Build configuration (`Debug`/`Release`)                                             |
| `platform`        | string | No       | Target platform: `iOS`, `macOS`, `watchOS`, `tvOS`, `visionOS`                      |
| `version`         | string | No       | OS version (e.g., `18.0`)                                                           |
| `simulatorUdid`   | string | No       | Specific simulator UDID                                                             |
| `deviceUdid`      | string | No       | Physical device UDID                                                                |
| `derivedDataPath` | string | No       | Custom derived data directory (default: `~/Library/Developer/FlowDeck/DerivedData`) |
| `xcodebuild`      | object | No       | Passthrough settings for xcodebuild                                                 |
| `appLaunch`       | object | No       | Arguments and env vars passed to app at launch                                      |

<Info>
  See [Configuration File](/cli/configuration-file) for complete reference and examples.
</Info>

## Init Command

Save project settings to avoid repeating options on every command:

```bash theme={null}
# Save settings
flowdeck config set -w MyApp.xcworkspace -s MyApp -S "iPhone 16"

# Now run commands without options
flowdeck build
flowdeck test
flowdeck run
```

Settings are saved to `~/.flowdeck/` and automatically loaded by subsequent commands.

### Init Options

| Option            | Short | Description                  |
| ----------------- | ----- | ---------------------------- |
| `--workspace`     | `-w`  | Path to workspace or project |
| `--scheme`        | `-s`  | Scheme name                  |
| `--simulator`     | `-S`  | Simulator name or UDID       |
| `--device`        | `-D`  | Device name or UDID          |
| `--configuration` | `-C`  | Build configuration          |

## Exit Codes

All commands return appropriate exit codes for scripting:

| Code | Description                                |
| ---- | ------------------------------------------ |
| `0`  | Success                                    |
| `1`  | Failure (build failed, tests failed, etc.) |
| `64` | Usage error (invalid arguments)            |

```bash theme={null}
flowdeck build --json && echo "Build passed" || echo "Build failed"
```

## Environment Variables

| Variable                   | Description                                  |
| -------------------------- | -------------------------------------------- |
| `FLOWDECK_LICENSE_KEY`     | License key for CI/CD (no activation needed) |
| `DEVELOPER_DIR`            | Override Xcode installation path             |
| `FLOWDECK_NO_UPDATE_CHECK` | Set to `1` to disable update notifications   |

## Common Automation Patterns

### Pattern 1: Config-Driven Builds

```bash theme={null}
# Create config files for different scenarios
flowdeck build --config .flowdeck/debug-config.json
flowdeck build --config .flowdeck/release-config.json
flowdeck test --config .flowdeck/ci-config.json --json
```

### Pattern 2: State-Driven Shortcuts

```bash theme={null}
# Setup once
flowdeck config set -w MyApp.xcworkspace -s MyApp -S "iPhone 16"

# Run repeatedly without options
flowdeck build
flowdeck test
flowdeck run
```

### Pattern 3: JSON Streaming

```bash theme={null}
# Parse events as they stream
flowdeck build --json | while read -r event; do
  echo "$event" | jq -r 'select(.type == "status") | .message'
done
```

### Pattern 4: CI/CD Pipeline

```bash theme={null}
# Full CI workflow
flowdeck clean --all
flowdeck build --config .flowdeck/ci-config.json --json
flowdeck test --config .flowdeck/ci-config.json --json

# Check results
if flowdeck test --json | jq -s 'last | .data.success' | grep -q true; then
  echo "All tests passed"
else
  echo "Tests failed"
  exit 1
fi
```

### Pattern 5: Dynamic Simulator Selection

```bash theme={null}
# Find and use a specific simulator
UDID=$(flowdeck simulator list -P iOS --json | \
  jq -r '.[] | select(.name | contains("iPhone 16")) | .udid' | head -1)

flowdeck config set -w MyApp.xcworkspace -s MyApp -S "$UDID"
flowdeck build --json
```

## Commands with JSON Support

Most commands support `--json` output:

| Command           | JSON Support | Notes                     |
| ----------------- | ------------ | ------------------------- |
| `build`           | Yes          | Full event streaming      |
| `run`             | Yes          | Includes app logs         |
| `test`            | Yes          | Test results with details |
| `clean`           | Yes          | Clean status events       |
| `logs`            | Yes          | Structured log events     |
| `simulator list`  | Yes          | Array of simulators       |
| `simulator boot`  | Yes          | Boot status               |
| `device list`     | Yes          | Array of devices          |
| `project schemes` | Yes          | Array of schemes          |
| `project configs` | Yes          | Array of configurations   |
| `apps`            | Yes          | Running app list          |
| `license status`  | Yes          | License details           |

## AI Agent Integration

FlowDeck's JSON output makes it ideal for AI-powered development tools like Claude Code, Cursor, and CodeX. The structured output allows AI agents to:

* Parse build errors and suggest fixes
* Monitor test results and identify failing tests
* Automate build-test-fix cycles
* Track simulator and device state

<Info>
  See [AI Agent Integration](/cli/ai-agents) for setup guides for specific AI tools.
</Info>

## Next Steps

* [CI/CD Integration](/cli/ci-cd) - Complete CI/CD setup guide
* [Configuration File](/cli/configuration-file) - Full config file reference
* [Xcodebuild Arguments](/cli/xcodebuild-args) - Passthrough options for xcodebuild
* [App Launch Settings](/cli/app-launch-settings) - App launch arguments and environment