> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowdeck.studio/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. 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                        | ✅    | ✅   |

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

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