---
title: Run a Build on an Emulator or Simulator
description: Download a Capawesome Cloud build and run it on a local Android emulator or iOS simulator with a single Capawesome CLI command.
---

# Run on an Emulator or Simulator

Run a completed build on a local Android emulator or iOS simulator without downloading and installing it by hand. The [Capawesome CLI](../cli/index.md) downloads the build artifact, starts the target device, installs the app and launches it.

Booting an emulator or simulator requires a local process, so this is a CLI-only workflow. The Console shows you the command to copy.

## Requirements

| Platform | Build type | Requirements |
| --- | --- | --- |
| Android | **Debug** or **Release** | Android SDK with at least one emulator (AVD) |
| iOS | **Simulator** only | macOS with Xcode and at least one simulator |

iOS builds of the type **Development**, **Ad Hoc**, **App Store** or **Enterprise** are signed for physical devices and cannot run in the simulator. See [Install on a Device](install-on-device.md) for those, and [Build Types](build-types.md) for an overview of all types.

The CLI looks for the Android SDK in the `ANDROID_HOME` or `ANDROID_SDK_ROOT` environment variable and falls back to the default installation directory.

## Run a build

=== "CLI"

    ```bash
    npx @capawesome/cli apps:builds:run --app-id <app-id> --build-number 42
    ```

    Without options, the CLI asks which app, build and target device to use.

=== "Console"

    Open the build's detail page and click **Run**. The dialog shows the command for that build — copy it and run it in your terminal.

    ![Run dialog on the build detail page in Capawesome Cloud](../../assets/images/screenshots/cloud-run-app.png)

## Choose a target device

By default the CLI asks which target device to use. Devices that are already running are listed first, so you can reuse a running emulator or simulator instead of waiting for one to boot.

Select a target device without the prompt:

```bash
# By ID (AVD ID on Android, UDID on iOS)
npx @capawesome/cli apps:builds:run --build-number 42 --target Pixel_8_Pro

# By name
npx @capawesome/cli apps:builds:run --build-number 42 --target-name "iPhone 17 Pro"

# By name, when several target devices share it
npx @capawesome/cli apps:builds:run --build-number 42 \
  --target-name "iPhone 17 Pro" --target-name-sdk-version 26.5
```

!!! note "Non-interactive environments"

    In CI or any other non-interactive shell, pass the app, build and target device explicitly. The CLI cannot prompt and exits with an error otherwise.

## Next steps

- [Install on a device](install-on-device.md) — run a build on physical hardware instead.
- [Share a build](share-a-build.md) — give external testers a link to install the build.
- [`apps:builds:run` reference](../cli/commands.md#appsbuildsrun) — every option for running a build from the CLI.
- [Capawesome CLI 4.18.0 Release](../../blog/posts/capawesome-cli-4-18-0-release.md) — the release this command shipped in.