Skip to main content
Every FinalRun project is anchored to a workspace root — the directory that contains the .finalrun/ folder. The workspace holds your configuration file, test specs, optional suite manifests, and per-environment binding files. Understanding the layout and the fields in config.yaml lets the CLI resolve the right app, environment, and AI model without you needing to pass flags on every run.

​
Workspace layout

my-app/                        # workspace root
  .env                         # optional
  .env.dev                     # optional
  .finalrun/
    config.yaml                # workspace configuration
    tests/                     # YAML test specs (required)
      smoke.yaml
      auth/
        login.yaml
    suites/                    # suite manifests (optional)
      auth_smoke.yaml
    env/                       # environment bindings (optional)
      dev.yaml
The tests/ directory is the only required subdirectory. suites/ and env/ are optional and only needed when you run suites or use named environments.

​
.finalrun/config.yaml fields

The workspace config defines defaults that the CLI uses when flags are omitted. Place this file at .finalrun/config.yaml in your workspace root.
​
app.name
string
Human-readable name for the app. Optional — used only for display purposes.
​
app.packageName
string
Android package identifier (e.g. com.example.myapp). Required if you run Android tests and do not pass --app.
​
app.bundleId
string
iOS bundle identifier (e.g. com.example.myapp). Required if you run iOS tests and do not pass --app.
​
env
string
Default environment name. Used when you omit the --env flag. Must match a file under .finalrun/env/<name>.yaml if one exists.
​
model
string
Default AI model in provider/model format (e.g. google/gemini-3-flash-preview). Used when you omit --model.
At least one of app.packageName or app.bundleId is required unless you always pass --app on the command line.

​
Example config

.finalrun/config.yaml
app:
  name: MyApp
  packageName: com.example.myapp
  bundleId: com.example.myapp
env: dev
model: google/gemini-3-flash-preview

​
App identity resolution

FinalRun resolves which app to launch on the device using the following priority order:
1

--app CLI flag (highest priority)

When you pass --app <path>, FinalRun uses that binary directly. It extracts the package name (Android) or bundle ID (iOS) from the binary and ignores any app block in config files.
2

Per-environment app block

If an active environment file at .finalrun/env/<name>.yaml contains an app block, those values override the workspace defaults.
3

config.yaml app block (workspace default)

If neither of the above applies, FinalRun falls back to the app block in .finalrun/config.yaml.

​
Using the --app flag

Pass a local binary to run a specific build without changing any config file: 
finalrun test smoke.yaml --platform android --app path/to/your.apk
finalrun test smoke.yaml --platform ios --app path/to/YourApp.app
The CLI:
  • Extracts the package name (Android) or bundle ID (iOS) from the binary
  • Infers the platform from the file extension (.apk → Android, .app → iOS)
  • Validates that the binary matches the --platform flag if both are provided
CLI flags always override values in config.yaml. You can use flags for one-off runs without modifying your workspace config.

​
Per-environment app overrides

If your app uses different identifiers per environment — for example, a .staging suffix — set the override in the corresponding env file instead of changing config.yaml:
.finalrun/env/staging.yaml
app:
  packageName: com.example.myapp.staging
  bundleId: com.example.myapp.staging
Any environment that does not define its own app block falls back to the workspace default in .finalrun/config.yaml.