> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Files & Schema

> The repository layout and the full flow, suite, and hook file reference for code-managed flows

This is the complete file reference for [code-managed flows](/docs/code-managed-flows.md): where files live under `.BugRadar/`, and every recognized key in flow files, suite manifests, and hook scripts.

## Repository layout

Everything BugRadar manages lives under a single `.BugRadar/` folder — at your repository root by default, or under a subdirectory you point BugRadar at (see [Monorepos](#monorepos)). Flows are `*.flow.yaml` files, a suite is a directory containing a `_suite.yaml` manifest, and hooks are script files under a `hooks/` directory.

```text theme={null}
.BugRadar/
├── BugRadar.md              # shared repository context for test runs
├── config.yaml              # run defaults for the CLI (not a test, never synced)
├── login.flow.yaml          # a root flow (folder "")
├── hooks/
│   └── seed-db.py           # a hook — slug "seed-db"
└── smoke/                   # a suite directory
    ├── _suite.yaml          # the suite manifest (suite key "smoke")
    ├── checkout.flow.yaml   # a flow in the smoke suite
    └── hooks/
        └── reset-test-env.sh  # another hook — slug "reset-test-env"
```

| File type | Location | Purpose |
| - | - | - |
| **Flow** | `<name>.flow.yaml` (anywhere under `.BugRadar/`) | One test flow |
| **Suite** | `<directory>/_suite.yaml` (one per directory) | Groups the flows in that directory |
| **Hook** | `<any>/hooks/<name>.<ext>` (direct parent must be `hooks/`) | A setup/teardown script |
| **Context** | `BugRadar.md` (root of `.BugRadar/` only) | Shared guidance for runs associated with this repository; see [Repository context](/docs/code-managed-flows.md#repository-context) |
| **Config** | `config.yaml` (root of `.BugRadar/` only) | Default app target for `BugRadar run`; see [Config file](#config-file) |

> [!NOTE]
>
> The sync reads `BugRadar.md` at the root of `.BugRadar/`, files that end in `.flow.yaml`, are named exactly `_suite.yaml`, or scripts directly inside a `hooks/` folder with a supported extension. Every other file under `.BugRadar/` is ignored, including `config.yaml`, which only the CLI reads.

## Flow files

A flow file ends in `.flow.yaml`. The only required keys are `name` and `instructions`, where `instructions` is either a single multiline prompt or a YAML list of steps.

As a multiline prompt:

```yaml theme={null}
key: login
name: Login
instructions: |
  Log in as qa+smoke@example.com using the password in ${env:LOGIN_PASSWORD}.
  Open the account menu and verify the signed-in email is shown.
  Sign out and confirm you land back on the login screen.
```

Or as a list of steps:

```yaml theme={null}
key: checkout
name: Checkout happy path
description: Buys one item as a logged-in user
caching_mode: 'off'
device_count: 2
instructions:
  - From the home screen, tap the cart icon
  - Tap "Checkout"
  - Verify the order confirmation screen appears
```

The recognized top-level keys are:

| Key | Required | Notes |
| - | - | - |
| **name** | Yes | Non-empty string. |
| **instructions** | Yes | A YAML list of non-empty step strings, or a single non-empty prompt string. A list is numbered into a single prompt. |
| **key** | No | Unique flow key. Defaults to the path minus `.BugRadar/` and `.flow.yaml` (e.g. `smoke/checkout`). |
| **description** | No | Free-text description. |
| **app** | Sometimes | Name of a linked app. Optional when the repo is linked to 0 or 1 apps; **required on every flow once the repo is linked to more than one app**. An unknown name fails the sync. |
| **caching\_mode** | No | `off`, `standard`, or `aggressive`. Omit or use `null` to inherit the workspace mode. A flow can reduce the workspace mode, never exceed it. Quote `'off'` so YAML treats it as a string. |
| **caching** | No | Legacy boolean: `false` means Off; `true` means inherit. Do not combine with `caching_mode`. |
| **device\_count** | No | Number of devices the agent controls. Use `1` (default) or `2`. Every member and setup flow in a suite must use the same value. |
| **setup\_hooks** | No | Ordered list of hook slugs to run before the flow. |
| **teardown\_hooks** | No | Ordered list of hook slugs to run after the flow. |
| **labels** | No | List of label names — see [Labels](#labels). |
| **variables** | No | Map of variable names to literal string values. See [Referencing variables](#referencing-variables). |

> [!WARNING]
>
> Any top-level key that isn't in the table above is a hard error. A typo like `instructoins:` fails validation with a "Did you mean 'instructions'?" suggestion on the [BugRadar - Code-Managed Flows check](/docs/code-managed-sync.md#sync-status-&-validation), so mechanical mistakes are caught before they merge.

> [!TIP]
>
> **Let the path derive your key.** If you omit `key`, the key comes from the file path (`.BugRadar/smoke/checkout.flow.yaml` becomes `smoke/checkout`). Set an explicit `key` when you want the key to stay stable even if you move or rename the file — see [Deleting and renaming](/docs/code-managed-sync.md#deleting-and-renaming).

### Exporting caching settings

CLI 0.9.15 and later preserve each caching mode when exporting flows. Older CLI
versions export an explicit Standard limit as caching Off, because their boolean
format cannot preserve that limit. Upgrade the CLI before exporting to retain
the exact setting.

### Referencing variables

Define flow overrides in `*.flow.yaml` and suite defaults in `_suite.yaml` with `variables`:

```yaml theme={null}
name: Login
variables:
  ACCOUNT_ROLE: guest
instructions: Sign in as ${env:ACCOUNT_ROLE}.
```

Flow variables override suite defaults. Hooks read them as environment variables (see [Variables](/docs/variables.md)).
Values must be literal strings; quote numbers and booleans (`CODE: "00123"`, `ENABLED: "false"`).
Names use letters, digits, and underscores, and cannot start with a digit.

A supplied map replaces that flow's or suite's overrides on sync. Omit `variables` to keep existing values, or use `variables: {}` to clear them.
Keep secrets in [Environments](/docs/environments.md), since YAML values are committed to your repository.

### Referencing hooks

Attach hooks to a flow with `setup_hooks` and `teardown_hooks`, each an ordered list of hook **slugs**:

```yaml theme={null}
name: Checkout happy path
setup_hooks:
  - seed-db
teardown_hooks:
  - reset-test-env
instructions:
  - Add an item to the cart and check out
  - Verify the order confirmation appears
```

A slug resolves against **every active hook in your organization** — not just repo files — so you can also reference hooks authored in the dashboard, including cURL hooks (which can only be created in the dashboard). Find a dashboard hook's slug on the hook in the [Hooks](/docs/hooks.md) page. See [Hooks as files](#hooks-as-files) for how a repo file's slug is derived.

[Built-in hooks](/docs/guides-otp-testing.md) don't need to be added from the Hook Library first. Reference **Lease email address** as `lease-email-address` and **Lease phone number** as `lease-phone-number`, and the sync adds the hook to your organization if it isn't there yet. If one of your own hooks already uses that slug, your hook is used instead.

Duplicate slugs within one list are rejected. The same slug may appear in both `setup_hooks` and `teardown_hooks` — that's legal. To reference a hook by name inside your instructions at run time, use `${hooks:Hook Name}` (by display name); see [Hooks](/docs/hooks.md). On a run pinned to a commit (an API run with `ref`, `BugRadar run --ref`, BugRadar's pull-request test runs, or a CI run with a [branch build's `app_build_id`](/docs/api-runs#branch-builds-run-at-their-commit)), the branch's hook file of that name runs, including one the branch adds. Working-copy runs (`--local` or `--cloud`) use your local file.

When the list mixes scripts with a launch-args (`.json`) hook, the app starts where that hook sits — see [when launch configuration runs](/docs/hooks.md#when-it-runs).

### Labels

Attach [labels](/docs/api-labels.md) to a flow or suite with `labels`, a list of label names:

```yaml theme={null}
name: Checkout happy path
labels: [smoke, critical]
instructions:
  - Add an item to the cart and check out
```

Names match case-insensitively against your org's labels; unknown names are auto-created. Omitting `labels` leaves the flow/suite's existing labels untouched — an explicit `labels: []` clears them. Labeled flows and suites dispatch via run-by-label as usual.

The built-in `snoozed` label is the exception. List it to [snooze](/docs/flows.md#snoozing-a-test) a flow:

```yaml theme={null}
name: Checkout happy path
labels: [smoke, snoozed]
```

* Remove `snoozed` from the file to unsnooze the flow on the next sync. Omitting `labels`, or `labels: []`, also removes it.
* A snooze added in the dashboard stays even when the file leaves `snoozed` out, including `labels: []`. Only the dashboard removes it.
* When both the file and the dashboard snoozed a flow, it stays snoozed until both remove it. **Unsnooze** in the dashboard removes only the dashboard's snooze. When only the file snoozes a flow, **Unsnooze** is unavailable, and the API refuses with `409`.
* A branch or commit run reads `snoozed` from the file at that commit. A flow snoozed in the dashboard is also skipped there.

## Suites

A suite is a directory containing a `_suite.yaml` manifest. The suite's key is its directory path (a `smoke/` directory gives the suite key `smoke`). The only required key is `name`:

```yaml theme={null}
name: Smoke Tests
description: Critical-path checks
setup_flow: login
parallelize_flows: false
instructions: |
  Test account is qa+smoke@example.com.
flows: [login, checkout]
```

The recognized keys are:

| Key | Required | Notes |
| - | - | - |
| **name** | Yes | Non-empty string. |
| **flows** | No | Ordered list of flow-key references. Omit it to include every flow **directly in the suite's own directory**, in filename-alphabetical order. |
| **setup\_flow** | No | A single flow-key reference to run first. |
| **parallelize\_flows** | No | Boolean. Runs each member flow in an independent session when `true`; defaults to `false`. An explicit API request override takes precedence for that launch; an omitted or `null` override uses this saved value. |
| **description** | No | Free-text description. |
| **instructions** | No | Suite-level context shared across the suite's flows (e.g. shared test-account info). |
| **setup\_hooks** / **teardown\_hooks** | No | Ordered lists of hook slugs. |
| **labels** | No | List of label names — see [Labels](#labels). |
| **variables** | No | Map of variable names to literal string values. See [Referencing variables](#referencing-variables). |

The **Lease email address** and **Lease phone number** built-in hooks may be listed in a suite's `setup_hooks`. Unlike ordinary suite setup scripts, a lease hook is inherited by every member flow and creates a separate inbox or number for each flow run. The suite's `setup_flow`, when configured, receives its own lease too. This also applies when `parallelize_flows: true`. These built-ins are setup-only and are rejected in `teardown_hooks`. Reference them as `lease-email-address` and `lease-phone-number`; you don't need to add them from the Hook Library first.

References in `flows` and `setup_flow` resolve **sibling-first**: a flow directly in the suite's own directory wins, otherwise the reference is matched against every flow in the repo. A suite directory cannot hold directories of tests; the sync fails and names the directory to move out. Flow keys and suite keys must each be unique across the whole repo. An unknown reference, or the same flow listed twice, is a validation error.

> [!NOTE]
>
> The `_suite.yaml` file must live inside a directory — it cannot sit at the `.BugRadar/` root, because a suite *is* a directory. Membership is defined by the suite (its `flows` list or its directory), never declared inside the flow files themselves.

> [!WARNING]
>
> YAML parses bare `no`, `yes`, `on`, and `off` as booleans (the "Norway problem"). Because `setup_flow` and `name` must be strings, `setup_flow: no` fails validation — quote the value if you really mean the string `"no"`.

For how variables and setup flows propagate across a suite's flows, see [Suites](/docs/suites.md).

## Folders

Each directory under `.BugRadar/` that holds tests, at any depth, shows as a folder on the [Flows](/docs/flows.md#organizing-tests-with-folders) page. The top folder from a repo shows the repo's name, linked to that directory in your repo. Directories can nest as deep as you like.

```text theme={null}
.BugRadar/
└── Auth/                    # folder "Auth"
    └── Onboarding/          # folder "Onboarding", inside "Auth"
        └── signup/          # a suite directory, not a folder
            ├── _suite.yaml  # flows: [email, verify]
            ├── email.flow.yaml
            ├── verify.flow.yaml
            └── sso.flow.yaml  # left out of the suite: shows in "Onboarding"
```

* A suite directory (one with `_suite.yaml`) is a suite, not a folder. It cannot hold directories of tests.
* A flow file the suite lists shows under the suite only. A flow file the suite leaves out shows in the folder that holds the suite.
* `hooks/` directories, and everything below them, are not folders.
* Spaces at the start or end of a directory name are dropped from the folder name.
* Folders from a pull request appear when it merges to your default branch.

Directories set where a test starts. On the Flows page you can drag a flow or suite from your repo to a new spot, another folder, or a section, and it stays there: a push moves it only when its file moves to another directory. To see every test where its file is, select **Show repo file structure**, the folder tree button at the start of the toolbar above the list.

If you remove or rename a directory that still holds flows, suites, or folders made in the dashboard, the folder stays with those items and becomes an ordinary dashboard folder. If you disconnect or remove the repository, its folders all stay as dashboard folders, and its flows become dashboard flows in the same folders. Only empty folders are removed.

## Moving files

Moving a flow file to another directory keeps its run history when the file name stays the same. If several moved files share a name, a file keeps its history only when exactly one new file matches it on the folder around it as well as the name, and that new file matches no other old file as closely. For example, renaming `Checkout/` to `Payments/` keeps the history of both `Checkout/web/happy-path.flow.yaml` and `Checkout/ios/happy-path.flow.yaml`. If that's not clear-cut, those files start as new tests. Moving a suite directory works the same way, matched on the directory name.

Otherwise the old test is archived and a new one starts. That includes moving and renaming a file in one commit, or moving it across two commits.

What a move does not carry over:

* Results of runs on a branch, which are saved by key, stay under the old key.
* A branch cut before the move still has the old path. Its runs create a separate test under the old key.

Moving or renaming a directory changes the key of every flow inside it, because keys come from the path. A suite's `flows` or `setup_flow` entry that names an old key then stops the whole sync. When only one flow could be the moved one, the error names its new key. CI scripts that name keys need updating too. To keep keys fixed when you move files, set `key:` in each file.

## Hooks as files

Hooks live as script files inside a `hooks/` folder — either `.BugRadar/hooks/` or `<suite>/hooks/`. The file extension determines the hook type, and the filename becomes the hook's slug.

| Extension | Hook type |
| - | - |
| `.py` | Python script |
| `.js` | JavaScript script |
| `.ts` | TypeScript script |
| `.sh` | Bash script |
| `.json` | Launch args (must be valid JSON) |

The **slug** is derived from the filename with its final extension removed: lowercased, with runs of non-alphanumeric characters collapsed to `-`. So `Seed DB.sh` becomes slug `seed-db`, and `reset.env.json` becomes `reset-env`. This slug is what you reference in `setup_hooks` / `teardown_hooks`. The **display name** is the humanized filename (`reset-test-env.sh` shows as "Reset Test Env").

> [!WARNING]
>
> **Hook slugs are unique across your whole organization** — the folder a hook lives in has no scoping effect. Two files that slugify the same (`seed-db.py` and `seed_db.sh`), or a slug that collides with a **different repository's** hook, fail the sync with a rename error. A slug that matches an existing **dashboard-authored** hook is *not* an error — that hook is adopted (its run history preserved), the same way flows adopt by name; see [Migrating existing flows](/docs/code-managed-migrate.md). Rename the file if that isn't what you intend.

> [!NOTE]
>
> The file content **is** the hook script, stored verbatim. Empty or whitespace-only files are rejected. A `.json` launch-args hook must parse as valid JSON, and a filename with no letters or digits (so it produces an empty slug) is rejected.

Script hooks (`.py`, `.js`, `.ts`, `.sh`) read environment variables **natively** — `os.environ.get(...)` in Python, `process.env` in JavaScript/TypeScript, `$VAR` in Bash. Launch-args (`.json`) hooks — and dashboard-authored cURL hooks — use the `${env:KEY}` token instead, since they aren't executed scripts. cURL hooks have no file form; reference an existing dashboard cURL hook by slug, or use a `.sh` hook that runs `curl`. See [Hooks](/docs/hooks.md) for the full hook model.

## Config file

`config.yaml` at the root of `.BugRadar/` sets defaults for `BugRadar run`. It is not a test: the sync never reads it and the CLI never uploads it. How the defaults apply is on [Running from the CLI](/docs/code-managed-cli.md#choosing-the-app).

```yaml theme={null}
apps:
  ios:
    bundle_id: com.example.app.dev
  android:
    bundle_id: com.example.app
  web:
    app_id: my-web-app
default_platform: ios
environment: staging
```

| Key | Required | Notes |
| - | - | - |
| **apps** | No | Map keyed by `ios`, `android`, or `web`. A mobile entry takes `bundle_id`; the `web` entry takes `app_id`. |
| **default\_platform** | Sometimes | One of `ios`, `android`, `web`. Not needed when `apps` has a single entry, which is the default. With several entries and no `default_platform`, a run must pass `--platform`. |
| **environment** | No | Name of the [environment](/docs/environments.md) runs resolve variables against. |

Any other key, an unknown platform, or a mobile entry without `bundle_id` (or a web entry without `app_id`) is an error. `BugRadar flows validate` reports it, and `BugRadar run` refuses to start until it is fixed.

## Monorepos

By default BugRadar looks for `.BugRadar/` at your repository root. If your definitions live in a subdirectory — common in a monorepo — point BugRadar at that folder with the repo's **Root directory** setting.

1. Go to **[Settings > Integrations > GitHub](https://usebugradar.com/settings?tab=integrations\&integration=github)**
2. On the connected repo, set **Root directory** to the folder that contains `.BugRadar/` (for example, `services/mobile` for `services/mobile/.BugRadar/`)
3. Leave it blank to use the repository root

Flow and suite **keys stay relative to `.BugRadar/`**, so moving your definitions into a subdirectory doesn't change any keys — a flow at `services/mobile/.BugRadar/login.flow.yaml` still has the key `login`. The GitHub links on each row point at the full path in your repo.

> [!NOTE]
>
> Saving a new Root directory doesn't re-sync on its own. Click **Resync** on the repository card, or push to the default branch to sync from the new location. Once `.BugRadar/` has been detected, the nightly resync also checks it for drift.

## Next Steps

* [Validate, sync, and preview on PRs →](/docs/code-managed-sync.md)
* [Run your tests from the terminal →](/docs/code-managed-cli.md)
* [Write effective flows →](/docs/flows.md)
* [Organize flows with Suites →](/docs/suites.md)
* [Learn about hooks →](/docs/hooks.md)
* [Manage variables →](/docs/variables.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.