Skip to content

cli-commands.md

Latest commit

 

History

History
864 lines (679 loc) · 21.7 KB

cli-commands.md

File metadata and controls

864 lines (679 loc) · 21.7 KB

CLI Commands Reference

Comprehensive reference for all CLI commands across Android, iOS, and React Native plugins.

Command Syntax

All commands follow the pattern:

devbox run [--pure] <command> [arguments]

The --pure flag runs commands in an isolated environment without environment variable inheritance.

Android Plugin Commands

Main CLI: android.sh

The main Android CLI provides device and emulator management.

Emulator Management

Start emulator:

devbox run --pure android.sh emulator start [--pure] [device]
  • --pure: Start fresh emulator with wiped data (clean Android OS state)
  • device: Device name (optional, defaults to ANDROID_DEFAULT_DEVICE)
  • Without --pure: Reuses existing emulator if running (faster, preserves data)
  • With --pure: Always starts new instance with -wipe-data flag
  • REUSE_EMU=1: Override pure mode to reuse existing emulator

Examples:

# Start default device, reuse if running
devbox run --pure android.sh emulator start

# Start specific device with fresh state
devbox run --pure android.sh emulator start --pure pixel_api30

# Start max device
devbox run --pure android.sh emulator start max

Stop emulator:

devbox run --pure android.sh emulator stop
  • Stops all running emulators

Check emulator readiness:

devbox run --pure android.sh emulator ready
  • Silent readiness probe: exit 0 if emulator is booted, exit 1 if not
  • Reads emulator serial from suite-namespaced state file
  • Checks sys.boot_completed property via adb

Reset emulator:

devbox run --pure android.sh emulator reset [device]
  • Wipes emulator data for specified device
  • If no device specified, uses ANDROID_DEFAULT_DEVICE

Convenience aliases:

# Start emulator (without --pure flag)
devbox run --pure start:emu [device]

# Stop emulator
devbox run --pure stop:emu

Device Management

List devices:

devbox run --pure android.sh devices list
  • Shows all device definitions in devbox.d/android/devices/
  • Displays: name, API level, device profile, tag, ABI

Show specific device:

devbox run --pure android.sh devices show <name>
  • Displays JSON configuration for specified device
  • Example: android.sh devices show pixel_api30

Create device:

devbox run --pure android.sh devices create <name> --api <n> --device <id> [--tag <tag>] [--abi <abi>]
  • name: Device name (used as filename)
  • --api: Android API level (required, e.g., 30, 33, 36)
  • --device: AVD device profile (required, e.g., pixel, pixel_7, tablet)
  • --tag: System image tag (optional, e.g., google_apis, google_apis_playstore, aosp_atd)
  • --abi: Preferred ABI (optional, e.g., x86_64, arm64-v8a, x86)

Examples:

# Create Pixel device with API 30
devbox run --pure android.sh devices create pixel_api30 \
  --api 30 \
  --device pixel \
  --tag google_apis \
  --abi x86_64

# Create tablet device
devbox run --pure android.sh devices create tablet_api33 \
  --api 33 \
  --device tablet \
  --tag google_apis_playstore

Update device:

devbox run --pure android.sh devices update <name> [--name <new>] [--api <n>] [--device <id>] [--tag <tag>] [--abi <abi>]
  • All flags are optional
  • --name: Rename device
  • Other flags update respective properties

Examples:

# Update API level
devbox run --pure android.sh devices update pixel_api30 --api 31

# Rename and update
devbox run --pure android.sh devices update pixel_api30 \
  --name pixel_api31 \
  --api 31

Delete device:

devbox run --pure android.sh devices delete <name>
  • Removes device definition file
  • Example: android.sh devices delete pixel_api30

Select devices for evaluation:

devbox run --pure android.sh devices select <name...>
  • Sets which devices to evaluate in Nix flake
  • Multiple device names space-separated
  • Example: android.sh devices select min max

Reset device selection:

devbox run --pure android.sh devices reset
  • Resets to evaluate all devices

Generate lock file:

devbox run --pure android.sh devices eval
  • Generates devices.lock from device definitions
  • Respects ANDROID_DEVICES filter (empty = all devices)
  • Run after creating/updating/deleting devices
  • Optimizes CI by limiting SDK versions evaluated

Related: devbox run android:devices:eval (convenience script)

Sync AVDs:

devbox run --pure android.sh devices sync
  • Creates/updates AVDs to match device definitions
  • Reads from devices.lock
  • Reports: matched, recreated, created, skipped

Configuration Management

Show configuration:

devbox run --pure android.sh config show
  • Displays current environment variable configuration

Set configuration:

devbox run --pure android.sh config set KEY=VALUE [KEY=VALUE...]
  • Updates configuration values
  • Multiple key-value pairs supported
  • Example: android.sh config set ANDROID_DEFAULT_DEVICE=pixel_api30

Reset configuration:

devbox run --pure android.sh config reset
  • Resets configuration to defaults

Application Deployment

Deploy app (install + launch on running emulator):

android.sh deploy [apk_path]
  • Installs and launches app on an already-running emulator (no build, no emulator start)
  • If apk_path is provided, installs the specified APK
  • If no arguments, auto-detects APK using the same resolution as run
  • Saves app ID and activity to suite-namespaced state files

Check app status:

android.sh app status
  • Exit 0 if the deployed app is running, exit 1 if not
  • Reads app ID and emulator serial from state files

Stop app:

android.sh app stop
  • Stops the deployed app via adb shell am force-stop

Run app (full orchestration):

devbox run --pure android.sh run [apk_path] [device]
  • Builds, installs, and launches app on emulator (starts emulator if needed)
  • apk_path: Path to APK (optional, uses ANDROID_APP_APK glob if not provided)
  • device: Device name (optional, defaults to ANDROID_DEFAULT_DEVICE)

Examples:

# Full orchestration: build, start emulator, install, launch
devbox run --pure android.sh run

# Install specific APK on default device
devbox run --pure android.sh run app/build/outputs/apk/debug/app-debug.apk

# Deploy to already-running emulator
android.sh deploy

# Check if app is running
android.sh app status

# Stop app
android.sh app stop

Note: start:app is not a plugin command. If your project defines a start:app script in devbox.json, it is a user-defined convenience script that may wrap android.sh run with additional build steps.

Diagnostics

Environment check:

devbox run doctor
  • Checks Android SDK configuration
  • Verifies tools in PATH (adb, emulator, avdmanager)
  • Shows device definitions and lock file status
  • Displays environment variables

Verify setup:

devbox run verify:setup
  • Quick check that Android environment is functional
  • Exits 1 on failure, 0 on success
  • Checks: ANDROID_SDK_ROOT, directory exists, adb available

iOS Plugin Commands

Main CLI: ios.sh

The main iOS CLI provides device and simulator management.

Simulator Management

Start simulator:

ios.sh simulator start [--pure] [device]
  • device: Device name (optional, defaults to IOS_DEFAULT_DEVICE)
  • Boots simulator if not already running
  • --pure: Creates a fresh, isolated test simulator with clean state
  • Auto-detects pure mode when DEVBOX_PURE_SHELL=1 (set by devbox run --pure)
  • REUSE_SIM=1: Override pure mode to reuse existing simulator
  • Saves UDID to $IOS_RUNTIME_DIR/${SUITE_NAME:-default}/simulator-udid.txt

Examples:

# Start default device, reuse if running
ios.sh simulator start

# Start specific device with fresh state
ios.sh simulator start --pure iphone15

# Start max device
ios.sh simulator start max

Stop simulator:

ios.sh simulator stop
  • In pure mode: shuts down and deletes the test simulator, cleans up state files
  • In normal mode: shuts down the simulator

Check simulator readiness:

ios.sh simulator ready
  • Silent readiness probe: exit 0 if booted, exit 1 if not
  • Designed for use as a process-compose readiness probe

Reset simulators:

ios.sh simulator reset
  • Stops all running simulators and deletes those matching device definitions

Convenience aliases:

devbox run --pure start:sim [device]   # ios.sh simulator start (without --pure)
devbox run --pure stop:sim             # ios.sh simulator stop

Device Management

List devices:

devbox run --pure ios.sh devices list
  • Shows all device definitions in devbox.d/ios/devices/
  • Displays: name, iOS runtime version

Show specific device:

devbox run --pure ios.sh devices show <name>
  • Displays JSON configuration for specified device
  • Example: ios.sh devices show iphone15

Create device:

devbox run --pure ios.sh devices create <name> --runtime <version>
  • name: Device name (used as filename and display name)
  • --runtime: iOS version (required, e.g., "17.5", "18.0", "15.4")

Examples:

# Create iPhone 15 simulator with iOS 17.5
devbox run --pure ios.sh devices create iphone15 --runtime 17.5

# Create iPad simulator
devbox run --pure ios.sh devices create ipad_pro --runtime 18.0

Update device:

devbox run --pure ios.sh devices update <name> [--name <new>] [--runtime <version>]
  • --name: Rename device (optional)
  • --runtime: Change iOS version (optional)

Examples:

# Update runtime version
devbox run --pure ios.sh devices update iphone15 --runtime 18.0

# Rename device
devbox run --pure ios.sh devices update iphone15 --name iphone15_pro

Delete device:

devbox run --pure ios.sh devices delete <name>
  • Removes device definition file
  • Example: ios.sh devices delete iphone15

Generate lock file:

devbox run --pure ios.sh devices eval
  • Generates devices.lock from device definitions
  • Respects IOS_DEVICES filter (empty = all devices)
  • Run after creating/updating/deleting devices
  • Includes checksum for validation

Related: devbox run ios:devices:eval (convenience script)

Sync simulators:

devbox run --pure ios.sh devices sync
  • Creates/updates simulators to match device definitions
  • Reads from devices.lock
  • Reports: matched, recreated, created, skipped

Application Deployment

Deploy app (install + launch on running simulator):

ios.sh deploy [app_path]
  • Installs and launches app on an already-running simulator (no build, no simulator start)
  • If app_path is provided, installs the specified .app bundle
  • If no arguments, auto-detects .app bundle
  • Saves bundle ID to suite-namespaced state file

Check app status:

ios.sh app status
  • Exit 0 if the deployed app is running, exit 1 if not

Stop app:

ios.sh app stop
  • Terminates the deployed app via xcrun simctl terminate

Run app (full orchestration):

ios.sh run [app_path] [device]
  • Starts simulator, builds, installs, and launches the app
  • Auto-detects .app bundle via IOS_APP_ARTIFACT env var, xcodebuild settings, or recursive search
  • Extracts bundle ID from Info.plist

Examples:

# Full orchestration
ios.sh run

# Deploy to already-running simulator
ios.sh deploy

# Check if app is running
ios.sh app status

# Stop app
ios.sh app stop

Example devbox.json scripts:

{
  "shell": {
    "scripts": {
      "build:ios": ["xcodebuild -scheme MyApp -configuration Debug -destination 'generic/platform=iOS Simulator' build"],
      "build:release": ["xcodebuild -scheme MyApp -configuration Release build"],
      "start:app": ["ios.sh run ${1:-}"]
    }
  }
}

Configuration Management

Show configuration:

devbox run --pure ios.sh config show
  • Displays current environment variable configuration

Show SDK info:

devbox run --pure ios.sh info
  • Shows Xcode developer directory
  • Displays iOS SDK version
  • Lists available runtimes
  • Shows device configuration

Diagnostics

Environment check:

devbox run doctor
  • Checks Xcode installation and command-line tools
  • Verifies xcrun and simctl availability
  • Shows device definitions and lock file status
  • Displays environment variables

Verify setup:

devbox run verify:setup
  • Quick check that iOS environment is functional
  • Exits 1 on failure, 0 on success
  • Checks: Xcode tools, simctl availability

React Native Plugin Commands

The React Native plugin composes Android and iOS plugins and adds Metro bundler management.

Platform Commands

Plugin-provided:

  • devbox run --pure start:emu [device] - Start Android emulator
  • devbox run --pure stop:emu - Stop Android emulator
  • devbox run --pure start:sim [device] - Start iOS simulator
  • devbox run --pure stop:sim - Stop iOS simulator

User-defined (define in your devbox.json):

  • devbox run --pure start-android [device] - Build and run Android app
  • devbox run --pure start-ios [device] - Build and run iOS app
  • devbox run --pure start-web - Start web development server

Metro Bundler Management

Get Metro port:

devbox run rn:metro:port [suite]
  • Returns the port assigned to Metro bundler for specified suite
  • suite: Test suite name (optional, defaults to "default")
  • Used for test isolation with multiple Metro instances

Clean Metro cache:

devbox run rn:metro:clean [suite]
  • Removes Metro cache and port tracking for specified suite
  • suite: Test suite name (optional, defaults to "default")
  • Cleans: port files, environment files, cache directory

Testing

Test Metro functionality:

devbox run test:metro
  • Runs Metro port management unit tests

Test Metro shutdown:

devbox run test:metro:shutdown
  • Runs Metro shutdown process-compose tests

Diagnostics

Environment check:

devbox run doctor
  • Checks Node.js, npm, and Watchman availability
  • Verifies Android environment (SDK, tools, devices)
  • Verifies iOS environment (Xcode, simctl, devices)
  • Shows device counts for both platforms

Verify setup:

devbox run verify:setup
  • Quick check that React Native environment is functional
  • Exits 1 on failure, 0 on success
  • Checks: Node.js/npm, Android SDK, iOS tools

Device Management Commands

Available for both Android and iOS plugins.

Common Operations

Workflow after device changes:

# 1. Create/update/delete devices
devbox run --pure {platform}.sh devices create <name> <options>

# 2. Regenerate lock file
devbox run --pure {platform}.sh devices eval

# 3. Sync simulators/AVDs (optional, creates actual devices)
devbox run --pure {platform}.sh devices sync

Platform-specific examples:

# Android workflow
devbox run --pure android.sh devices create pixel_api35 --api 35 --device pixel
devbox run --pure android.sh devices eval
devbox run --pure android.sh devices sync

# iOS workflow
devbox run --pure ios.sh devices create iphone16 --runtime 18.0
devbox run --pure ios.sh devices eval
devbox run --pure ios.sh devices sync

Diagnostic Commands

All plugins provide diagnostic commands for troubleshooting.

doctor

Purpose: Comprehensive environment check

Android output includes:

  • ANDROID_SDK_ROOT configuration
  • Tool availability (adb, emulator, avdmanager)
  • Device definitions count and filter settings
  • Lock file status

iOS output includes:

  • Xcode developer directory
  • Command-line tools availability
  • xcrun and simctl status
  • Device definitions count and filter settings
  • Lock file status

React Native output includes:

  • Node.js, npm, Watchman availability
  • Android environment summary
  • iOS environment summary
  • Device counts for both platforms

verify:setup

Purpose: Quick pass/fail environment check

Behavior:

  • Exits 0 if environment is functional
  • Exits 1 if environment check fails
  • Useful for CI/CD pipelines

Platform checks:

  • Android: SDK root, directory exists, adb available
  • iOS: Xcode tools, simctl working
  • React Native: Node.js/npm, Android SDK, iOS tools

Configuration Commands

config show

Available for: Android, iOS

Purpose: Display current environment variable configuration

Output includes:

  • All plugin-specific environment variables
  • Directory paths
  • Device selection settings
  • Build configuration

config set

Available for: Android

Purpose: Update configuration values

Syntax:

devbox run --pure android.sh config set KEY=VALUE [KEY=VALUE...]

Examples:

# Set default device
devbox run --pure android.sh config set ANDROID_DEFAULT_DEVICE=pixel_api35

# Set multiple values
devbox run --pure android.sh config set \
  ANDROID_DEFAULT_DEVICE=pixel_api35 \
  ANDROID_COMPILE_SDK=35

config reset

Available for: Android

Purpose: Reset configuration to defaults

Script Naming Conventions

Main CLI Scripts

  • android.sh - Android main CLI (device and emulator management)
  • ios.sh - iOS main CLI (device and simulator management)
  • rn.sh - React Native utilities (Metro management)
  • metro.sh - Metro bundler operations

Convenience Scripts (Plugin-Provided)

  • start:emu - Start Android emulator (alias for android.sh emulator start)
  • stop:emu - Stop Android emulator
  • start:sim - Start iOS simulator
  • stop:sim - Stop iOS simulator
  • doctor - Comprehensive environment check
  • verify:setup - Quick pass/fail check

User-Defined Scripts (Define in Your devbox.json)

The following are NOT provided by the plugins. Define them in your project's devbox.json as needed:

  • start-ios / start:ios - Build and run iOS app
  • start-android / start:android - Build and run Android app

Device Management Scripts

  • {platform}:devices:eval - Generate lock file (convenience alias)

Command Categories

Emulator/Simulator Lifecycle (Plugin-Provided)

Android:

  • android.sh emulator start [--pure] [device]
  • android.sh emulator stop
  • android.sh emulator ready
  • android.sh emulator reset [device]
  • start:emu [device] - Convenience alias for android.sh emulator start
  • stop:emu - Convenience alias for android.sh emulator stop

iOS:

  • ios.sh simulator start [--pure] [device]
  • ios.sh simulator stop
  • ios.sh simulator ready
  • ios.sh simulator reset
  • start:sim [device] - Convenience alias for ios.sh simulator start
  • stop:sim - Convenience alias for ios.sh simulator stop

Device Definition Management (Plugin-Provided)

Create:

  • android.sh devices create <name> --api <n> --device <id> [options]
  • ios.sh devices create <name> --runtime <version>

Read:

  • {platform}.sh devices list
  • {platform}.sh devices show <name>

Update:

  • android.sh devices update <name> [options]
  • ios.sh devices update <name> [options]

Delete:

  • {platform}.sh devices delete <name>

Sync:

  • {platform}.sh devices eval - Generate lock file
  • {platform}.sh devices sync - Create/update simulators/AVDs

Application Deployment

Plugin-provided:

  • android.sh deploy [apk_path] - Install and launch on running emulator
  • android.sh app status - Check if deployed app is running
  • android.sh app stop - Stop the deployed app
  • android.sh run [apk_path] [device] - Build, start emulator, install and launch
  • ios.sh deploy [app_path] - Install and launch on running simulator
  • ios.sh app status - Check if deployed app is running
  • ios.sh app stop - Stop the deployed app
  • ios.sh run [app_path] [device] - Start simulator, build, install and launch

User-defined (define in your devbox.json):

  • start-android / start:android - Build and run Android app
  • start-ios / start:ios - Build and run iOS app
  • start-web - Start web development server

Configuration (Plugin-Provided)

  • {platform}.sh config show - Display configuration
  • android.sh config set KEY=VALUE - Update configuration
  • android.sh config reset - Reset to defaults
  • ios.sh info - Show SDK info

Diagnostics (Plugin-Provided)

  • doctor - Comprehensive check
  • verify:setup - Quick pass/fail check

Usage Tips

Using --pure flag

The --pure flag runs commands in isolated environments:

# Recommended for reproducibility
devbox run --pure android.sh devices list

# Useful for testing
devbox run --pure start:emu

Device name resolution

When no device specified, uses default:

# Uses ANDROID_DEFAULT_DEVICE
devbox run start:emu

# Uses IOS_DEFAULT_DEVICE
devbox run start:sim

Set defaults in devbox.json:

{
  "env": {
    "ANDROID_DEFAULT_DEVICE": "pixel_api35",
    "IOS_DEFAULT_DEVICE": "iphone15"
  }
}

Device filtering

Control which devices are evaluated:

{
  "env": {
    "ANDROID_DEVICES": "min,max",
    "IOS_DEVICES": "min,max"
  }
}

After changing filters, regenerate lock files:

devbox run --pure android.sh devices eval
devbox run --pure ios.sh devices eval

Chaining commands

Use shell operators for workflows:

# Start emulator and run app
devbox run --pure start:emu && devbox run --pure android.sh run

# Create device and sync
devbox run --pure android.sh devices create pixel_api35 --api 35 --device pixel && \
devbox run --pure android.sh devices eval && \
devbox run --pure android.sh devices sync

Script location

All scripts are in PATH when in devbox shell:

# Inside devbox shell
devbox shell

# Can run directly
android.sh devices list
ios.sh config show

Outside shell, use devbox run:

# Outside shell
devbox run android.sh devices list

Related Documentation