Skip to main content
FlowDeck lets you pass arguments and environment variables to your app when it launches on simulator or device. This is useful for:
  • Skipping onboarding flows during development
  • Setting debug flags
  • Configuring API environments
  • Testing different locales

​
Methods Overview

MethodBest ForPriority
CLI OptionsQuick testing from command lineHighest
Local SettingsProject-wide defaultsMedium
Config FileCI/CD, reproducible buildsLowest
When multiple sources provide settings, they’re merged with CLI taking highest priority.

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

​
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 auto-loaded whenever you run flowdeck run from that project directory.
Add .flowdeck/app-launch-settings.json to .gitignore if it contains developer-specific settings, or commit it for team-wide defaults.

​
Structure

FieldTypeDescription
argsarrayArguments passed to the app at launch
envobjectEnvironment 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"
See Configuration File for complete config file documentation.

​
Priority and Merging

When settings come from multiple sources, they’re combined in this order:
  1. Config file (lowest priority) - base configuration
  2. Local app-launch-settings.json - overrides config file
  3. 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.

​
Common Arguments Reference

​
Apple System Arguments

ArgumentDescription
-AppleLanguages (en)Force app language to English
-AppleLanguages (es)Force app language to Spanish
-AppleLocale en_USForce locale to US English
-AppleTextDirectionOverride text direction (LTR/RTL)
-NSDoubleLocalizedStrings YESDouble all localized strings (find truncation issues)
-NSShowNonLocalizedStrings YESHighlight non-localized strings

​
Common App Flags

ArgumentDescription
-SkipOnboardingSkip onboarding flow (if your app supports it)
-UITestingDisabled NOEnable/disable UI testing mode
-FIRAnalyticsDebugEnabledEnable Firebase Analytics debug mode
-FIRDebugEnabledEnable 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

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

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

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

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

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

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'

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

​
Troubleshooting

​
Arguments Not Taking Effect

  1. Check the source - Make sure your JSON is valid: 
    cat .flowdeck/app-launch-settings.json | jq .
  2. Verify priority - CLI options override local settings which override config file
  3. 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)"]
}