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

# Running from the CLI

> Run code-managed flows and suites from the terminal: on your own device, on BugRadar's cloud devices, or from a branch

`BugRadar run` runs the tests in your `.BugRadar/` folder from the terminal, without opening a pull request. It is shorthand for `BugRadar flows run`. There are three ways to run, and the flag you pass decides where the tests come from and where they execute.

## Three ways to run

| | `--local` | `--cloud` | Branch (the default) |
| - | - | - | - |
| **Tests come from** | your working copy, uncommitted | your working copy, uncommitted | the branch's committed files on GitHub |
| **Run on** | your simulator, emulator, phone, or dev server | BugRadar's cloud devices | BugRadar's cloud devices |
| **App build** | whatever is on your device | the branch's newest upload, or one you name | the upload from the same commit, or one you name |
| **Hooks** | not run | run | run |
| **You can select** | one flow or one suite | any flows, suites, labels, folders, or `--all` | flows, suites, folders, or `--all` |

Use `--local` while you iterate on a flow. Use `--cloud` to try an edit on real devices before you commit it. Use a branch run for what CI would do: the committed tests, at a commit, on cloud devices.

## Before you start

[Install the CLI](/docs/install-cli.md) and log in. Run `BugRadar login` from inside the repository and the login is stored for that repository, so different repos can use different organizations.

```bash theme={null}
BugRadar login
BugRadar whoami   # the organization the CLI will run as
```

The organization you are logged in as must own the app you run against. A run that reports `App not found. Upload a build first.` almost always means the login belongs to a different organization than the app. Check `BugRadar whoami` before checking anything else.

`BugRadar run` looks in `.BugRadar/` in the current directory: `--local` and `--cloud` take the tests from there, and every mode reads `config.yaml` from there (a branch run takes its tests from GitHub). Pass `--path` to point at another folder, for example in a monorepo. (`BugRadar flows validate` takes the folder as its argument instead.)

## Choosing the tests

Name flows by key and suites by folder:

```bash theme={null}
BugRadar run login --local                # one flow, by key (--local or --cloud only)
BugRadar run --suite checkout --cloud     # one suite, by folder name
BugRadar run --flow login --flow signup   # several flows (a branch run needs --flow)
BugRadar run --cloud --label smoke        # flows and suites whose labels: list has this name
BugRadar run --all --ref my-branch        # every suite and standalone flow, here from a branch
BugRadar run --folder Auth/Onboarding     # everything in a folder, from the branch
```

A flow's key is its path under `.BugRadar/` without the `.flow.yaml` ending, so `.BugRadar/checkout/cart.flow.yaml` is `checkout/cart`. A suite's key is its folder, so the folder `.BugRadar/checkout/` with a `_suite.yaml` inside is the suite `checkout`.

> [!WARNING]
>
> A bare name is always read as a **flow** key. `BugRadar run checkout` fails with `flow key 'checkout' not found` when `checkout` is a suite folder. Use `--suite checkout`, or name a flow inside it such as `checkout/cart`.

`--folder` takes a folder's path below `.BugRadar/` and runs every suite and flow beneath it. It works with branch runs and `--cloud`, not with `--local`. A branch run also includes tests made in the dashboard and placed in the folder; `--cloud` runs only the files on disk. `--folder` needs CLI 0.17.0 or later.

A label matches the `labels:` list in your flow and suite files. Labels set only in the dashboard are not seen. A flow matched by a label runs inside its suite, with the suite's setup, even when only the flow file carries the label. A flow that belongs to a selected suite runs inside that suite; a flow named by its key runs on its own.

## Choosing the app

A run needs to know which of your apps to run against. For a mobile app that is its bundle id and platform. For a web app, `--app-id` takes its slug: a lowercase id such as `my-web-app`, the `app-id` input of the [CI action](/docs/ci-cd-integration.md), which the [List Apps API](/docs/api-apps.md#list-apps) returns as the app's `bundle_id`. Every run also accepts the app's UUID.

```bash theme={null}
BugRadar run login --cloud --bundle-id com.example.app --platform ios
BugRadar run login --cloud --app-id <APP_ID>
```

When several mobile apps share one bundle ID in an environment, pick one with `--app-id` and `--platform`. `--app-id` takes the app's [App ID](/docs/apps.md) (for example `flow-dev`) or its UUID. Add `--bundle-id` if your organization has more than one bundle ID on that platform. Branch, local, and cloud runs all accept it. A mobile `--app-id` is a flag only: a mobile entry in `config.yaml` takes just a `bundle_id`. `BugRadar apps list` shows every app's bundle ID, App ID, and UUID.

```bash theme={null}
BugRadar apps list --platform android
BugRadar run login --cloud --app-id flow-dev --platform android
```

In a terminal, a branch or cloud run that names no app, or names a bundle ID that several apps share, asks which app to use and prints the flags that skip the question next time. With a shared bundle ID, pressing Enter keeps the app named by the bundle ID alone. With no app named there is no default, and when your organization has only one app (on any platform, or on the `--platform` you passed) the run uses it without asking. Outside a terminal, in CI and scripts, there is no question and no automatic pick: a run that names no app stops with an error, and a shared bundle ID runs the app named by the bundle ID alone.

Rather than type these on every run, commit them once in `.BugRadar/config.yaml`, next to your flows (key reference in [Files & Schema](/docs/code-managed-files.md#config-file)):

```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   # optional
```

With that file, `BugRadar run --cloud --suite checkout` needs no app flags: it uses the iOS app because `default_platform` says so. Add `--platform android` and it uses the Android one. `--platform web`, or `default_platform: web`, uses the `app_id`. A file with a single entry needs no `default_platform` at all. A local run picks the entry for whichever platform your `BugRadar up` session is on.

A value you type beats one from the environment, which beats the file: `--bundle-id` on the command line wins over the `BugRadar_BUNDLE_ID` variable, which wins over `config.yaml`. The keys, their rules, and what the file is not (a test, or anything the sync reads) are in [Files & Schema](/docs/code-managed-files.md#config-file).

Two more things affect the target:

* **Environment.** `--environment <name>` (or `environment:` in the file) selects the [variable set](/docs/variables.md) your flows resolve `${env:…}` references against. It is required when one app spans several [environments](/docs/environments.md).
* **Local runs on mobile** can leave the app out entirely when your organization has a single app for that platform. Cloud and branch runs need it named, by flag, variable, or file. In a terminal they ask instead, or use your only app; in CI and scripts they stop with an error.

## Local runs

Start a session on your device or dev server with `BugRadar up`, then run against it:

```bash theme={null}
# Mobile: boot a local session, then run the working-copy flow
BugRadar up --platform ios --detach
BugRadar run login --local

# Web: connect your dev server, then target its BugRadar app
BugRadar up --platform web --port 3000 --detach
BugRadar run login --local --app-id <APP_ID>

# Suites work locally too
BugRadar run --suite checkout --local
```

A local run executes your **uncommitted** YAML on the target that `BugRadar up` connected. Web is inferred from `--app-id` alone; the mobile platform is taken from your session. Use `--platform` when you have sessions on more than one platform, or `--session-id` when several sessions match. Set-up details for simulators, emulators, physical phones, and dev servers are on the [Local Testing](/docs/local-testing.md) page.

> [!NOTE]
>
> Local runs execute your flow's **instructions** only. [Hooks](/docs/hooks.md) are not run locally because they manipulate the test environment rather than the target. Use a suite's `setup_flow` for setup steps that can run on the target.

## Cloud runs

`--cloud` uploads your uncommitted `.BugRadar/` and runs it on BugRadar's devices, so you can try an edit before committing it. Select any number of flows, suites, or labels:

```bash theme={null}
BugRadar run login --cloud --bundle-id com.example.app --platform ios
BugRadar run --cloud --suite checkout --label smoke
BugRadar run --cloud --all --branch feat/new-cart
BugRadar run login --cloud --app-build-id <BUILD_ID>
```

The first line names the app; the others leave it to `config.yaml` (see [Choosing the app](#choosing-the-app)). The tests always come from your working copy. What `--branch` and `--app-build-id` choose is only the **build**:

| Flags | Which build runs |
| - | - |
| *(none)* | the newest build uploaded from your current git branch |
| `--branch <name>` | the newest build uploaded from that branch |
| `--app-build-id <ID>` | the build you name, whatever branch it came from |

When no build was uploaded from the branch, the run stops and, if the app has an active build, names it so you can pin it with `--app-build-id`.

Unlike `--local`, a cloud run does execute [hooks](/docs/hooks.md). Hook scripts in your working copy are uploaded with the flows and take precedence; a hook a flow names that has no file in `.BugRadar/` is taken from the dashboard.

## Branch runs

With neither `--local` nor `--cloud`, the CLI runs the tests **committed** on a branch. It reads that branch's `.BugRadar/` from GitHub, so nothing uncommitted takes part:

```bash theme={null}
BugRadar run --suite checkout --ref my-branch
BugRadar run --flow login --ref my-branch
BugRadar run --all --ref my-branch
```

`--ref` defaults to your current branch. Name flows with `--flow` here; the bare `BugRadar run login` form is for `--local` and `--cloud` only. The repository comes from your `origin` remote, or pass `--repo owner/name`.

By default the run uses the app build made from the same commit as the tests, so every result names a single commit. Two flags change which build runs:

| Flags | Which build runs |
| - | - |
| *(none)* | the build at the same commit as the tests |
| `--build-match branch-latest` | the newest build on that branch |
| `--app-build-id <ID>` | the build you name, whatever commit it came from |

The last row is the one to reach for when you changed only test files: no build exists at your commit, and rebuilding an app that did not change is wasted work. Reach for `--build-match branch-latest` when you want the branch's newest build but do not have its ID to hand, in CI for example.

If the option you choose matches no build, the run is refused and says so. BugRadar never quietly falls back to the app's active build, because a result that does not name the build it came from is worse than no result.

> [!NOTE]
>
> `--build-match` needs a branch name. Pass a full commit sha as `--ref` and the flag is refused, because a sha names no branch to take a latest build from. Name the build with `--app-build-id` instead, which works with any ref.

The dashboard runs branches too: the run dialogs on the **Flows** page take a branch and a build, and the build you pick there need not come from that branch.

## What a run prints

Each run that starts is printed as a link you can open, followed by the batch that groups them:

```text theme={null}
✓ Started 1 run at branch dev
https://usebugradar.com/runs/groups/<id>
batch <batch-id>
```

The link opens the run in the dashboard. The command returns as soon as the runs start.

## Waiting for the result

Add `--wait` to any run and the command stays open until the run finishes. It prints each flow's result as its suite finishes, then a total:

```bash theme={null}
BugRadar run --suite checkout --cloud --wait
```

```text theme={null}
✓ Started 1 run at branch dev
https://usebugradar.com/runs/groups/<id>
batch <batch-id>
✓ checkout / Add to cart passed  https://usebugradar.com/runs/flow/<id>
✗ checkout / Pay with card failed  https://usebugradar.com/runs/flow/<id>
1/2 flows passed
✗ 1 flow(s) did not pass.
```

The exit code is 0 only when every flow passed, so a script or a coding agent can act on it directly. A run passes or fails by the same rule as the [CI action](/docs/ci-cd-integration.md). Exit code 1 means a flow did not pass, the wait timed out, or the run status could not be read; the last line printed says which. Add `--timeout <seconds>` to give up after that long. Press Ctrl-C to stop waiting. Either way the run carries on, and the batch id is printed so you can check it later with the [Run Status API](/docs/api-runs.md#run-status). `--wait` needs CLI 0.18.0 or later.

## Troubleshooting

### App not found. Upload a build first.

The organization the CLI is logged in as does not own an app with that bundle id and platform. Run `BugRadar whoami`; if it names the wrong organization, run `BugRadar login` from inside the repository. If the organization is right, check the bundle id against the [Apps](/docs/apps.md) page. A web app is looked up by app id, a mobile app by bundle id and platform.

### flow key 'x' not found in the working copy

`x` is not a flow. Either it is a suite folder (use `--suite x`), or the file is not named `<key>.flow.yaml`, or you are in a directory without `.BugRadar/` (pass `--path`).

### no build was uploaded with branch\_name 'x' for this app

A `--cloud` run found no build uploaded from that branch. Upload one from CI, or pin any build with `--app-build-id`. The error names the app's active build when there is one.

### My suite won't run against a branch

A branch run fails with an error naming one or more flow files, instead of starting:

```text theme={null}
suite 'checkout' would not run all of its tests: the flow file
.BugRadar/checkout/cart.flow.yaml sits beside .BugRadar/checkout/_suite.yaml but
could not be used, so the suite would run short
```

BugRadar refuses to run a suite when one of its tests is missing. A suite that runs four tests out of five and still reports a pass would hide the fact that a test never ran. This happens when the suite has no `flows:` list: its tests are then every `.flow.yaml` beside its `_suite.yaml`, and on that branch one of those files could not be read.

**Possible Causes:**

* The file has a YAML error
* The file couldn't be downloaded from GitHub
* Two files claim the same key, so both were dropped

**Solutions:**

* Fix or delete every file the error names. It lists them all at once, so you can repair them in a single commit
* Run `BugRadar flows validate` to reproduce a YAML error or a duplicate key
* If a file failed to download, start the run again. If the same error comes back, check that the file is committed on that branch
* Give the suite an explicit `flows:` list, so its tests are the ones you name rather than whatever the folder contains

Only runs you start against a branch are refused this way. The automatic check on a pull request is unaffected, because suite changes there don't apply until you merge (see [Pull request workflow](/docs/code-managed-sync.md#pull-request-workflow)).

## Next Steps

* [Learn the file schema →](/docs/code-managed-files.md)
* [Validate, sync, and preview on PRs →](/docs/code-managed-sync.md)
* [Set up local devices and dev servers →](/docs/local-testing.md)
* [Poll a run from a script →](/docs/api-runs.md#run-status)


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