run

The run command builds your app and launches it on a device or simulator.

Usage

teardown run <platform> [options]

Arguments

Argument	Description
`platform`	`ios` or `android` (required)

Options

Option	Description	Default
`-d, --device <device>`	Specific device name or ID	-
`--no-picker`	Skip device picker, use first available	`false`
`--release`	Run in release mode	`false`
`--port <port>`	Metro bundler port	`8081`
`--no-bundler`	Skip starting Metro bundler	`false`
`--configuration <config>`	iOS build configuration	`Debug`
`--scheme <scheme>`	iOS Xcode scheme to build	-
`--variant <variant>`	Android build variant	`debug`
`--clean`	Clean build before running	`false`

Examples

Run on iOS Simulator

teardown run ios

Shows a device picker if multiple simulators are available.

Run on Android Emulator

teardown run android

Run on Specific Device

# By name
teardown run ios --device "iPhone 15 Pro"

# By UDID
teardown run ios --device "ABCD1234-5678-90EF-GHIJ-KLMNOPQRSTUV"

Skip Device Picker

# Use first available device
teardown run ios --no-picker

Release Build

teardown run ios --release

Custom Metro Port

teardown run ios --port 8082

Without Metro Bundler

# Useful when Metro is already running
teardown run ios --no-bundler

Clean Build

teardown run ios --clean

What Happens

The run command:

Checks for native project - Auto-runs prebuild if needed
Installs CocoaPods (iOS) - If pods aren't installed
Starts Metro bundler - In background (unless --no-bundler or --release)
Detects devices - Lists available devices/simulators
Shows device picker - Unless --device or --no-picker
Boots simulator (if needed) - For iOS simulators
Builds the app - Using Xcode or Gradle
Installs the app - On selected device
Launches the app - Via deep link with bundler URL
Attaches Metro - Brings bundler to foreground

Device Picker

When multiple devices are available, an interactive picker appears:

? Select a device
❯ iPhone 15 Pro (Booted)
  iPhone 15 (Shutdown)
  iPhone SE (3rd generation) (Shutdown)
  iPad Pro (Shutdown)

Use arrow keys to navigate, Enter to select.

iOS-Specific Options

Scheme

Use a specific Xcode scheme:

teardown run ios --scheme MyApp-Development

Configuration

Specify build configuration:

teardown run ios --configuration Release

Android-Specific Options

Variant

Specify build variant:

teardown run android --variant release
teardown run android --variant stagingDebug

Auto-Prebuild

If native projects don't exist, run automatically triggers prebuild:

# This works even without ios/ folder
teardown run ios
# → Runs prebuild first, then builds and runs

CocoaPods Installation

For iOS, if Pods aren't installed, the CLI handles it:

Installing CocoaPods dependencies... (45s) - installing React-Core

Progress is shown with current activity and elapsed time.

Troubleshooting

No Devices Found

No iOS simulators found

Open Xcode and install simulators: Xcode → Settings → Platforms
For physical devices, connect via USB and trust the computer

Build Failed

Check the error output. Common fixes:

# Clean and rebuild
teardown run ios --clean

# Or rebuild from scratch
teardown prebuild --clean
teardown run ios

Metro Already Running

Port 8081 is already in use

Either:

Stop the existing Metro process
Use a different port: teardown run ios --port 8082
Skip bundler: teardown run ios --no-bundler

CocoaPods Failed

If pod install fails:

cd ios
pod install --repo-update

Or delete and reinstall:

rm -rf ios/Pods ios/Podfile.lock
cd ios && pod install

App Won't Launch

If the app builds but doesn't launch:

# Try with verbose logging
teardown run ios --verbose

Check that your app scheme matches your URL scheme in teardown.config.ts.

dev - Start Metro bundler only
prebuild - Generate native projects

On this page