Automation & 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

# 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

Previewing mutations

Supported mutating commands accept --dry-run. Combine it with --json to receive a normalized object containing type: "dry_run", a display-safe command, and an argument-safe argv array without performing the mutation.

flowdeck simulator erase SIMULATOR-UDID --dry-run --json

See Dry-Run Previews for the single-command and multi-command schemas.

JSON Output Mode

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

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. flowdeck test --json finishes with a top-level flowdeck.test snapshot in addition to the streamed events. That final object is the authoritative verdict and aggregate count source; for a real test phase, it also reports the selected absolute resultBundlePath.

Event Structure

All events follow a standardized structure:

{
  "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:

# 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 the authoritative test summary
flowdeck test --json | \
  jq 'select(.schema == "flowdeck.test") | {success, totalTests, passedTests, failedTests, skippedTests, resultBundlePath}'

Shell Script Example

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

flowdeck build --config .flowdeck/ci-config.json
flowdeck test --config .flowdeck/ci-config.json --json

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.

Config File Structure

{
  "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

See Configuration File for complete reference and examples.

Init Command

Save project settings to avoid repeating options on every command:

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

flowdeck build --json && echo "Build passed" || echo "Build failed"

For test runs, any nonzero underlying xcodebuild status—including status 65—is a failure. Use the command exit status for pipeline control and the final flowdeck.test object for the authoritative verdict, counts, and result-bundle location.

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

# 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

# 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

# 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

# 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 -e 'select(.schema == "flowdeck.test") | .success' >/dev/null; then
  echo "All tests passed"
else
  echo "Tests failed"
  exit 1
fi

Pattern 5: Dynamic Simulator Selection

# 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

See AI Agent Integration for setup guides for specific AI tools.

Next Steps

CI/CD Integration - Complete CI/CD setup guide
Configuration File - Full config file reference
Xcodebuild Arguments - Passthrough options for xcodebuild
App Launch Settings - App launch arguments and environment

Overview

FlowDeck for AI

Interactive Mode (TUI)

Core Features

Command Reference

Advanced

Support

Automation & Scripting

Quick Start

Previewing mutations

JSON Output Mode

Event Types

Event Structure

Parsing JSON Output

Shell Script Example

Configuration Files

Config File Structure

Config File Fields

Init Command

Init Options

Exit Codes

Environment Variables

Common Automation Patterns

Pattern 1: Config-Driven Builds

Pattern 2: State-Driven Shortcuts

Pattern 3: JSON Streaming

Pattern 4: CI/CD Pipeline

Pattern 5: Dynamic Simulator Selection

Commands with JSON Support

AI Agent Integration

Next Steps

​Quick Start

​Previewing mutations

​JSON Output Mode

​Event Types

​Event Structure

​Parsing JSON Output

​Shell Script Example

​Configuration Files

​Config File Structure

​Config File Fields

​Init Command

​Init Options

​Exit Codes

​Environment Variables

​Common Automation Patterns

​Pattern 1: Config-Driven Builds

​Pattern 2: State-Driven Shortcuts

​Pattern 3: JSON Streaming

​Pattern 4: CI/CD Pipeline

​Pattern 5: Dynamic Simulator Selection

​Commands with JSON Support

​AI Agent Integration

​Next Steps

Quick Start

Previewing mutations

JSON Output Mode

Event Types

Event Structure

Parsing JSON Output

Shell Script Example

Configuration Files

Config File Structure

Config File Fields

Init Command

Init Options

Exit Codes

Environment Variables

Common Automation Patterns

Pattern 1: Config-Driven Builds

Pattern 2: State-Driven Shortcuts

Pattern 3: JSON Streaming

Pattern 4: CI/CD Pipeline

Pattern 5: Dynamic Simulator Selection

Commands with JSON Support

AI Agent Integration

Next Steps