Skip to main content

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.

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
Legacy Local SettingsCompatibility with older project setupsMedium
Config FileCI/CD, reproducible buildsLowest
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

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"
--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:
  1. Config file (lowest priority) - base configuration
  2. Local app-launch-settings.json - compatibility override for current CLI auto-load behavior
  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.
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

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)"]
}