--- description: Download a Capawesome Cloud build and run it on a local Android emulator or iOS simulator with a single Capawesome CLI command. title: Run a Build on an Emulator or Simulator - Capawesome image: https://capawesome.io/docs/assets/images/social/cloud/native-builds/run-on-emulator-or-simulator.png --- [Skip to content ](#run-on-an-emulator-or-simulator) [📲 Introducing **Build Sharing** — get your builds onto testers' devices with a link & QR code. No account required. ](/blog/share-mobile-app-builds-with-testers/) * [ SDKs ](/docs/sdks/) * [ Formbricks ](/docs/sdks/capacitor/formbricks/) * [ Geocoder ](/docs/sdks/capacitor/geocoder/) * [ Google Sign-In ](/docs/sdks/capacitor/google-sign-in/) * [ Grafana Faro ](/docs/sdks/capacitor/grafana-faro/) * [ Gyroscope ](/docs/sdks/capacitor/gyroscope/) * [ Haptics ](/docs/sdks/capacitor/haptics/) * [ Home Indicator ](/docs/sdks/capacitor/home-indicator/) * [ In-App Browser ](/docs/sdks/capacitor/in-app-browser/) * [ Install Referrer ](/docs/sdks/capacitor/install-referrer/) * [ Intercom ](/docs/sdks/capacitor/intercom/) * [ Intune ](/docs/sdks/capacitor/intune/) * [ Keep Awake ](/docs/sdks/capacitor/keep-awake/) * [ libSQL ](/docs/sdks/capacitor/libsql/) * [ Light Sensor ](/docs/sdks/capacitor/light-sensor/) * [ Live Update ](/docs/sdks/capacitor/live-update/) * [ Localization ](/docs/sdks/capacitor/localization/) * [ Mail Composer ](/docs/sdks/capacitor/mail-composer/) * [ Managed Configurations ](/docs/sdks/capacitor/managed-configurations/) * [ Maps Launcher ](/docs/sdks/capacitor/maps-launcher/) * [ Media Session ](/docs/sdks/capacitor/media-session/) * [ ML Kit ](/docs/sdks/capacitor/mlkit/) * [ Navigation Bar ](/docs/sdks/capacitor/navigation-bar/) * [ Network ](/docs/sdks/capacitor/network/) * [ NFC ](/docs/sdks/capacitor/nfc/) * [ Node.js ](/docs/sdks/capacitor/nodejs/) * [ OAuth ](/docs/sdks/capacitor/oauth/) * [ Passkeys ](/docs/sdks/capacitor/passkeys/) * [ Password Autofill ](/docs/sdks/capacitor/password-autofill/) * [ PDF Generator ](/docs/sdks/capacitor/pdf-generator/) * [ PDF Viewer ](/docs/sdks/capacitor/pdf-viewer/) * [ Pedometer ](/docs/sdks/capacitor/pedometer/) * [ Permissions ](/docs/sdks/capacitor/permissions/) * [ Phone Dialer ](/docs/sdks/capacitor/phone-dialer/) * [ Photo Editor ](/docs/sdks/capacitor/photo-editor/) * [ Photo Manipulator ](/docs/sdks/capacitor/photo-manipulator/) * [ PixLive ](/docs/sdks/capacitor/pixlive/) * [ PostHog ](/docs/sdks/capacitor/posthog/) * [ Printer ](/docs/sdks/capacitor/printer/) * [ Privacy Screen ](/docs/sdks/capacitor/privacy-screen/) * [ Proximity Sensor ](/docs/sdks/capacitor/proximity-sensor/) * [ Purchases ](/docs/sdks/capacitor/purchases/) * [ RealtimeKit ](/docs/sdks/capacitor/realtimekit/) * [ Root Detection ](/docs/sdks/capacitor/root-detection/) * [ Screen Brightness ](/docs/sdks/capacitor/screen-brightness/) * [ Screen Orientation ](/docs/sdks/capacitor/screen-orientation/) * [ Screen Reader ](/docs/sdks/capacitor/screen-reader/) * [ Screenshot ](/docs/sdks/capacitor/screenshot/) * [ Secure Preferences ](/docs/sdks/capacitor/secure-preferences/) * [ Settings Launcher ](/docs/sdks/capacitor/settings-launcher/) * [ Shake ](/docs/sdks/capacitor/shake/) * [ Silent Mode ](/docs/sdks/capacitor/silent-mode/) * [ SIM ](/docs/sdks/capacitor/sim/) * [ SMS Composer ](/docs/sdks/capacitor/sms-composer/) * [ Speech Recognition ](/docs/sdks/capacitor/speech-recognition/) * [ Speech Synthesis ](/docs/sdks/capacitor/speech-synthesis/) * [ Share Target ](/docs/sdks/capacitor/share-target/) * [ Square Mobile Payments ](/docs/sdks/capacitor/square-mobile-payments/) * [ SQLite ](/docs/sdks/capacitor/sqlite/) * [ Superwall ](/docs/sdks/capacitor/superwall/) * [ System WebView ](/docs/sdks/capacitor/system-webview/) * [ Tauri ](/docs/sdks/capacitor/tauri/) * [ Text Interaction ](/docs/sdks/capacitor/text-interaction/) * [ Text Zoom ](/docs/sdks/capacitor/text-zoom/) * [ Thermal State ](/docs/sdks/capacitor/thermal-state/) * [ Toast ](/docs/sdks/capacitor/toast/) * [ Torch ](/docs/sdks/capacitor/torch/) * [ Vault ](/docs/sdks/capacitor/vault/) * [ Volume ](/docs/sdks/capacitor/volume/) * [ Wallet ](/docs/sdks/capacitor/wallet/) * [ Wifi ](/docs/sdks/capacitor/wifi/) * [ YouTube Player ](/docs/sdks/capacitor/youtube-player/) * [ Zip ](/docs/sdks/capacitor/zip/) * [ Cordova ](/docs/sdks/cordova/) * [ Cloud ](/docs/cloud/) * [ Integrations ](/docs/cloud/live-updates/integrations/) * Concepts * Reference * [ Troubleshooting ](/docs/cloud/live-updates/troubleshooting/) * [ FAQ ](/docs/cloud/live-updates/faq/) * [ Native Builds ](/docs/cloud/native-builds/) * [ Share a Build ](/docs/cloud/native-builds/share-a-build/) * [ Set Up Signing Certificates ](/docs/cloud/native-builds/certificates/) * [ Set Up Environments ](/docs/cloud/native-builds/environments/) * [ Set Up Native Configurations ](/docs/cloud/native-builds/native-configurations/) * [ Auto-Increment Build Numbers ](/docs/cloud/native-builds/auto-incrementing-build-numbers/) * [ Configure the Web Build Script ](/docs/cloud/native-builds/web-build-script/) * [ Build from a Monorepo ](/docs/cloud/native-builds/monorepo/) * [ Use pnpm, Yarn, or bun ](/docs/cloud/native-builds/package-managers/) * [ Install Private npm Packages ](/docs/cloud/native-builds/npm-private-registry/) * [ Override the Java Version ](/docs/cloud/native-builds/override-java-version/) * [ Custom iOS Provisioning Profiles ](/docs/cloud/native-builds/custom-ios-provisioning-profiles/) * [ Build without Git ](/docs/cloud/native-builds/build-without-git/) * [ Access Git Behind a Firewall ](/docs/cloud/native-builds/firewall-access/) * [ Integrations ](/docs/cloud/native-builds/integrations/) * Reference * [ Troubleshooting ](/docs/cloud/native-builds/troubleshooting/) * [ FAQ ](/docs/cloud/native-builds/faq/) * [ App Store Publishing ](/docs/cloud/app-store-publishing/) * [ Submit a Build ](/docs/cloud/app-store-publishing/submit-a-build/) * [ Submit Automatically After a Build ](/docs/cloud/app-store-publishing/submit-automatically/) * [ Troubleshooting ](/docs/cloud/app-store-publishing/troubleshooting/) * [ FAQ ](/docs/cloud/app-store-publishing/faq/) * [ Automations ](/docs/cloud/automations/) * [ Reference ](/docs/cloud/automations/reference/) * [ Troubleshooting ](/docs/cloud/automations/troubleshooting/) * [ FAQ ](/docs/cloud/automations/faq/) * [ Assist ](/docs/cloud/assist/) * [ CLI ](/docs/cloud/cli/) * APIs and SDKs * [ Webhooks ](/docs/cloud/webhooks/) * [ Integrations ](/docs/cloud/integrations/) * Notifications * Account * [ Organization ](/docs/cloud/organizations/) * [ Two-Factor Enforcement ](/docs/cloud/organizations/two-factor-authentication/) * [ Audit Logs ](/docs/cloud/organizations/audit-logs/) * [ Billing ](/docs/cloud/organizations/billing/) * [ License Keys ](/docs/cloud/license-keys/) * [ AI ](/docs/ai/) * [ Insiders ](/docs/insiders/) * [ Billing & Plans ](/docs/insiders/billing-and-plans/) * [ FAQ ](/docs/insiders/faq/) * [ License ](https://capawesome.io/legal/eula/) * [ Support ](/docs/support/) * [ Contributing ](/docs/contributing/) * Contributing code * [ Code of Conduct ](/docs/contributing/code-of-conduct/) * [ Questions ](https://docs.github.com/en/discussions/collaborating-with-your-community-using-discussions/participating-in-a-discussion#creating-a-discussion) * [ Blog ](/blog/) * Categories # Run on an Emulator or Simulator[¶](#run-on-an-emulator-or-simulator "Permanent link") Run a completed build on a local Android emulator or iOS simulator without downloading and installing it by hand. The [Capawesome CLI](/docs/cloud/cli/) 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[¶](#requirements "Permanent link") | 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](/docs/cloud/native-builds/install-on-device/) for those, and [Build Types](/docs/cloud/native-builds/build-types/) 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[¶](#run-a-build "Permanent link") CLIConsole `[](#%5F%5Fcodelineno-0-1)npx @capawesome/cli apps:builds:run --app-id --build-number 42 ` Without options, the CLI asks which app, build and target device to use. 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](/docs/assets/images/screenshots/cloud-run-app.png) ## Choose a target device[¶](#choose-a-target-device "Permanent link") 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: `[](#%5F%5Fcodelineno-1-1)# By ID (AVD ID on Android, UDID on iOS) [](#%5F%5Fcodelineno-1-2)npx @capawesome/cli apps:builds:run --build-number 42 --target Pixel_8_Pro [](#%5F%5Fcodelineno-1-3) [](#%5F%5Fcodelineno-1-4)# By name [](#%5F%5Fcodelineno-1-5)npx @capawesome/cli apps:builds:run --build-number 42 --target-name "iPhone 17 Pro" [](#%5F%5Fcodelineno-1-6) [](#%5F%5Fcodelineno-1-7)# By name, when several target devices share it [](#%5F%5Fcodelineno-1-8)npx @capawesome/cli apps:builds:run --build-number 42 \ [](#%5F%5Fcodelineno-1-9) --target-name "iPhone 17 Pro" --target-name-sdk-version 26.5 ` 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[¶](#next-steps "Permanent link") * [Install on a device](/docs/cloud/native-builds/install-on-device/) — run a build on physical hardware instead. * [Share a build](/docs/cloud/native-builds/share-a-build/) — give external testers a link to install the build. * [apps:builds:run reference](/docs/cloud/cli/commands/#appsbuildsrun) — every option for running a build from the CLI. August 2, 2026 Back to top ```json {"@context": "https://schema.org", "@graph": [{"@type": "TechArticle", "@id": "https://capawesome.io/docs/cloud/native-builds/run-on-emulator-or-simulator/#article", "headline": "Run a Build on an Emulator or Simulator", "name": "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.", "inLanguage": "en", "url": "https://capawesome.io/docs/cloud/native-builds/run-on-emulator-or-simulator/", "mainEntityOfPage": "https://capawesome.io/docs/cloud/native-builds/run-on-emulator-or-simulator/", "author": {"@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": {"@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg"}}, "publisher": {"@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": {"@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg"}}}]} ```