App Launch Settings

FlowDeck lets you pass arguments and environment variables to your app when it launches. This is useful for:

Skipping onboarding flows during development
Setting debug flags
Configuring API environments
Testing different locales

Platform Support

Both args and env are honored on every launch target:

Target	Args	Env
iOS/tvOS/watchOS/visionOS Simulator	✅	✅
Physical device	✅	✅
macOS (native)	✅	✅
Mac Catalyst	✅	✅

Launch env is delivered by prefixing the child process’s environment — SIMCTL_CHILD_<KEY> for simulator launches, DEVICECTL_CHILD_<KEY> for physical devices — never as part of the printed xcrun simctl launch ... or devicectl ... command line. Reading the verbose command line alone can never tell you whether an env var was applied, even when it worked correctly.Run with --verbose to see the actually-resolved config root, launch args, and launch env (including the literal SIMCTL_CHILD_*/DEVICECTL_CHILD_* keys sent to the process), printed directly instead of inferred from the command line.

Methods Overview

Method	Best For	Priority
CLI Options	Quick testing from command line	Highest
Legacy Local Settings	Compatibility with older project setups	Medium
Config File	CI/CD, reproducible builds	Lowest

When multiple sources provide settings, they’re merged with CLI taking highest priority.

Preferred Project Settings Format

For shared project settings, prefer storing app launch settings in:

.flowdeck/config.json
.flowdeck/config.local.json

Example:

{
  "appLaunch": {
    "args": ["-SkipOnboarding"],
    "env": {
      "API_ENVIRONMENT": "staging"
    }
  },
  "schemes": {
    "MyApp": {
      "appLaunch": {
        "args": ["-AppleLanguages", "(en)"],
        "env": {
          "DEBUG_MODE": "1"
        }
      }
    }
  }
}

Use the top-level appLaunch block for project-wide defaults, and schemes.<scheme>.appLaunch for per-scheme overrides.

CLI Options

App Launch Arguments

Use --launch-options to pass arguments to your app:

flowdeck run -w App.xcworkspace -s MyApp -S "iPhone 16" \
  --launch-options='-AppleLanguages (en) -SkipOnboarding'

App Launch Environment

Use --launch-env to set environment variables for your app:

flowdeck run -w App.xcworkspace -s MyApp -S "iPhone 16" \
  --launch-env='DEBUG=1 API_ENV=staging'

Xcodebuild Arguments

Use --xcodebuild-options to pass arguments to xcodebuild:

flowdeck run -w App.xcworkspace -s MyApp -S "iPhone 16" \
  --xcodebuild-options='-quiet -enableCodeCoverage YES'

Xcodebuild Environment

Use --xcodebuild-env to set environment variables for the build:

flowdeck run -w App.xcworkspace -s MyApp -S "iPhone 16" \
  --xcodebuild-env='CI=true DEVELOPER_DIR=/Applications/Xcode-15.4.app/Contents/Developer'

Combining Options

All options can be combined in any order:

flowdeck run -w App.xcworkspace -s MyApp -S "iPhone 16" \
  --launch-options='-AppleLanguages (en) -SkipOnboarding' \
  --launch-env='DEBUG=1' \
  --xcodebuild-options='-quiet' \
  --xcodebuild-env='CI=true'

Use = syntax when values start with - to avoid argument parsing issues.

Legacy Local Settings

Create .flowdeck/app-launch-settings.json in your project root for settings that apply automatically:

{
  "args": [
    "-AppleLanguages", "(en)",
    "-SkipOnboarding",
    "-UITestingDisabled", "NO"
  ],
  "env": {
    "DEBUG_MODE": "1",
    "API_ENVIRONMENT": "staging"
  }
}

This file is a legacy compatibility format and is still auto-loaded by current CLI runtime paths.

Prefer .flowdeck/config.json or .flowdeck/config.local.json for new setup. Keep .flowdeck/app-launch-settings.json only when you need compatibility with older workflows.

Structure

Field	Type	Description
`args`	array	Arguments passed to the app at launch
`env`	object	Environment variables set for the app process

Config File

Include app launch settings in your --config JSON file:

{
  "workspace": "MyApp.xcworkspace",
  "scheme": "MyApp",
  "appLaunch": {
    "args": [
      "-AppleLanguages", "(en)",
      "-SkipOnboarding"
    ],
    "env": {
      "API_ENVIRONMENT": "staging"
    }
  }
}

Use with:

flowdeck run --config path/to/config.json -S "iPhone 16"

--config uses the explicit command config format, which is separate from .flowdeck/config.json and .flowdeck/config.local.json. See Configuration File for the difference.

Priority and Merging

When settings come from multiple sources, they’re combined in this order:

Config file (lowest priority) - base configuration
Local app-launch-settings.json - compatibility override for current CLI auto-load behavior
CLI options (highest priority) - overrides everything

Args are appended in order (config + local + CLI). Environment variables are merged, with higher priority sources overwriting lower priority values for the same key.

The canonical shared project-settings format is appLaunch inside .flowdeck/config.json or .flowdeck/config.local.json. The separate app-launch-settings.json file remains a legacy compatibility input.

Common Arguments Reference

Apple System Arguments

Argument	Description
`-AppleLanguages (en)`	Force app language to English
`-AppleLanguages (es)`	Force app language to Spanish
`-AppleLocale en_US`	Force locale to US English
`-AppleTextDirection`	Override text direction (LTR/RTL)
`-NSDoubleLocalizedStrings YES`	Double all localized strings (find truncation issues)
`-NSShowNonLocalizedStrings YES`	Highlight non-localized strings

Common App Flags

Argument	Description
`-SkipOnboarding`	Skip onboarding flow (if your app supports it)
`-UITestingDisabled NO`	Enable/disable UI testing mode
`-FIRAnalyticsDebugEnabled`	Enable Firebase Analytics debug mode
`-FIRDebugEnabled`	Enable Firebase debug mode

UserDefaults Style

You can pass any UserDefaults value:

--launch-options='-MyCustomFlag true -FeatureFlag_NewUI enabled'

Your app reads these with:

UserDefaults.standard.bool(forKey: "MyCustomFlag")
UserDefaults.standard.string(forKey: "FeatureFlag_NewUI")

Environment Variables

Set environment variables for the app process:

--launch-env='API_BASE_URL=https://staging.api.example.com DEBUG_MODE=1 LOG_LEVEL=verbose'

Your app reads these with:

ProcessInfo.processInfo.environment["API_BASE_URL"]
ProcessInfo.processInfo.environment["DEBUG_MODE"]

Use Cases

Skip Onboarding During Development

flowdeck run -w App.xcworkspace -s MyApp -S "iPhone 16" \
  --launch-options='-SkipOnboarding -SkipTutorial'

Test Different Locales

flowdeck run -w App.xcworkspace -s MyApp -S "iPhone 16" \
  --launch-options='-AppleLanguages (ja) -AppleLocale ja_JP'

Staging API Environment

flowdeck run -w App.xcworkspace -s MyApp -S "iPhone 16" \
  --launch-env='API_ENVIRONMENT=staging API_BASE_URL=https://staging.api.example.com'

Debug Firebase

flowdeck run -w App.xcworkspace -s MyApp -S "iPhone 16" \
  --launch-options='-FIRDebugEnabled -FIRAnalyticsDebugEnabled'

Find Localization Issues

flowdeck run -w App.xcworkspace -s MyApp -S "iPhone 16" \
  --launch-options='-NSDoubleLocalizedStrings YES -NSShowNonLocalizedStrings YES'

Full Development Setup

flowdeck run -w App.xcworkspace -s MyApp -S "iPhone 16" \
  --launch-options='-AppleLanguages (en) -SkipOnboarding -EnableDevMenu' \
  --launch-env='DEBUG_MODE=1 API_ENVIRONMENT=development LOG_LEVEL=verbose'

CI Build with Coverage

flowdeck run -w App.xcworkspace -s MyApp -S "iPhone 16" \
  --xcodebuild-options='-quiet -enableCodeCoverage YES' \
  --xcodebuild-env='CI=true'

Troubleshooting

Arguments Not Taking Effect

Check the source - Make sure your JSON is valid:

cat .flowdeck/app-launch-settings.json | jq .

Verify priority - CLI options override local settings which override config file

Check your app - Your app must read these values:

// For args
UserDefaults.standard.bool(forKey: "SkipOnboarding")

// For env
ProcessInfo.processInfo.environment["DEBUG_MODE"]

Values Starting with Dash

Use = syntax when values start with -:

# Won't work - ArgumentParser sees -AppleLanguages as new option
flowdeck run ... --launch-options -AppleLanguages "(en)"

# Works - use = syntax
flowdeck run ... --launch-options='-AppleLanguages (en)'

JSON Array Format

Arguments are individual array elements:

{
  "args": ["-AppleLanguages", "(en)"]
}

Not:

{
  "args": ["-AppleLanguages (en)"]
}

Overview

FlowDeck for AI

Interactive Mode (TUI)

Core Features

Command Reference

Advanced

Support

App Launch Settings

Platform Support

Methods Overview

Preferred Project Settings Format

CLI Options

App Launch Arguments

App Launch Environment

Xcodebuild Arguments

Xcodebuild Environment

Combining Options

Legacy Local Settings

Structure

Config File

Priority and Merging

Common Arguments Reference

Apple System Arguments

Common App Flags

UserDefaults Style

Environment Variables

Use Cases

Troubleshooting

Arguments Not Taking Effect

Values Starting with Dash

JSON Array Format

​Platform Support

​Methods Overview

​Preferred Project Settings Format

​CLI Options

​App Launch Arguments

​App Launch Environment

​Xcodebuild Arguments

​Xcodebuild Environment

​Combining Options

​Legacy Local Settings

​Structure

​Config File

​Priority and Merging

​Common Arguments Reference

​Apple System Arguments

​Common App Flags

​UserDefaults Style

​Environment Variables

​Use Cases

​Troubleshooting

​Arguments Not Taking Effect

​Values Starting with Dash

​JSON Array Format

Platform Support

Methods Overview

Preferred Project Settings Format

CLI Options

App Launch Arguments

App Launch Environment

Xcodebuild Arguments

Xcodebuild Environment

Combining Options

Legacy Local Settings

Structure

Config File

Priority and Merging

Common Arguments Reference

Apple System Arguments

Common App Flags

UserDefaults Style

Environment Variables

Use Cases

Troubleshooting

Arguments Not Taking Effect

Values Starting with Dash

JSON Array Format