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

# App Launch Settings

> Pass custom arguments and environment variables to your app at launch

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

| Method                                          | Best For                                | Priority |
| ----------------------------------------------- | --------------------------------------- | -------- |
| [CLI Options](#cli-options)                     | Quick testing from command line         | Highest  |
| [Legacy Local Settings](#legacy-local-settings) | Compatibility with older project setups | Medium   |
| [Config File](#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:

```json theme={null}
{
  "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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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'
```

<Tip>
  Use `=` syntax when values start with `-` to avoid argument parsing issues.
</Tip>

## Legacy Local Settings

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

```json theme={null}
{
  "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.

<Info>
  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.
</Info>

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

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

Use with:

```bash theme={null}
flowdeck run --config path/to/config.json -S "iPhone 16"
```

<Info>
  `--config` uses the explicit command config format, which is separate from `.flowdeck/config.json` and `.flowdeck/config.local.json`. See [Configuration File](/cli/configuration-file) for the difference.
</Info>

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

<Note>
  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.
</Note>

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

```bash theme={null}
--launch-options='-MyCustomFlag true -FeatureFlag_NewUI enabled'
```

Your app reads these with:

```swift theme={null}
UserDefaults.standard.bool(forKey: "MyCustomFlag")
UserDefaults.standard.string(forKey: "FeatureFlag_NewUI")
```

## Environment Variables

Set environment variables for the app process:

```bash theme={null}
--launch-env='API_BASE_URL=https://staging.api.example.com DEBUG_MODE=1 LOG_LEVEL=verbose'
```

Your app reads these with:

```swift theme={null}
ProcessInfo.processInfo.environment["API_BASE_URL"]
ProcessInfo.processInfo.environment["DEBUG_MODE"]
```

## Use Cases

<AccordionGroup>
  <Accordion title="Skip Onboarding During Development">
    ```bash theme={null}
    flowdeck run -w App.xcworkspace -s MyApp -S "iPhone 16" \
      --launch-options='-SkipOnboarding -SkipTutorial'
    ```
  </Accordion>

  <Accordion title="Test Different Locales">
    ```bash theme={null}
    flowdeck run -w App.xcworkspace -s MyApp -S "iPhone 16" \
      --launch-options='-AppleLanguages (ja) -AppleLocale ja_JP'
    ```
  </Accordion>

  <Accordion title="Staging API Environment">
    ```bash theme={null}
    flowdeck run -w App.xcworkspace -s MyApp -S "iPhone 16" \
      --launch-env='API_ENVIRONMENT=staging API_BASE_URL=https://staging.api.example.com'
    ```
  </Accordion>

  <Accordion title="Debug Firebase">
    ```bash theme={null}
    flowdeck run -w App.xcworkspace -s MyApp -S "iPhone 16" \
      --launch-options='-FIRDebugEnabled -FIRAnalyticsDebugEnabled'
    ```
  </Accordion>

  <Accordion title="Find Localization Issues">
    ```bash theme={null}
    flowdeck run -w App.xcworkspace -s MyApp -S "iPhone 16" \
      --launch-options='-NSDoubleLocalizedStrings YES -NSShowNonLocalizedStrings YES'
    ```
  </Accordion>

  <Accordion title="Full Development Setup">
    ```bash theme={null}
    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'
    ```
  </Accordion>

  <Accordion title="CI Build with Coverage">
    ```bash theme={null}
    flowdeck run -w App.xcworkspace -s MyApp -S "iPhone 16" \
      --xcodebuild-options='-quiet -enableCodeCoverage YES' \
      --xcodebuild-env='CI=true'
    ```
  </Accordion>
</AccordionGroup>

## Troubleshooting

### Arguments Not Taking Effect

1. **Check the source** - Make sure your JSON is valid:
   ```bash theme={null}
   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:
   ```swift theme={null}
   // For args
   UserDefaults.standard.bool(forKey: "SkipOnboarding")

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

### Values Starting with Dash

Use `=` syntax when values start with `-`:

```bash theme={null}
# 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:

```json theme={null}
{
  "args": ["-AppleLanguages", "(en)"]
}
```

Not:

```json theme={null}
{
  "args": ["-AppleLanguages (en)"]
}
```