device-lab

Stop guessing what's installed on your simulators and emulators.

If you work with iOS simulators or Android emulators, you've been here: you rebuild an app that was already built, reinstall a binary that was already installed, or debug against a stale build because you forgot which device has what. There's no single place to check.

device-lab fixes this. It's a local CLI registry that tracks your build artifacts and device installations in one place — so you always know what's built, what's installed where, and what's out of date.

What it does

• Artifact registry — Register build outputs (.app, .apk, tarballs) with metadata: project, platform, build kind, app ID, commit SHA
• Installation tracking — Record which artifact is installed on which simulator/emulator
• Drift detection — Compare your registry against live simulator/emulator state to find stale installs and untracked apps
• Auto-install — Install the latest matching artifact onto a simulator or emulator with one command

Install

npm install -g device-lab

Requires Node.js 18+. iOS commands need Xcode CLI tools (xcrun). Android commands need the Android SDK (adb).

Quick start

# Initialize the registry
device-lab init

# Register a build artifact
device-lab artifact register \
  --project my-app \
  --platform ios-sim \
  --build-kind debug \
  --app-id com.example.myapp \
  --path ./build/MyApp.app \
  --commit abc1234

# Install latest matching artifact onto a simulator
device-lab ios install-latest \
  --udid <sim-udid> \
  --project my-app \
  --build-kind debug

# See what you've got
device-lab status

# Check for drift between registry and reality
device-lab drift detect

Commands

device-lab init

Create the state directory (~/.device-lab by default, override with DEVICE_LAB_ROOT).

device-lab artifact register

Register a build artifact with project metadata.

device-lab artifact register \
  --project <name> --platform <platform> --build-kind <kind> \
  --app-id <id> --path <file> --commit <sha>

Or register from a stamped manifest:

device-lab artifact register --manifest <path>

device-lab artifact stamp

Write a portable manifest file next to your artifact — useful in CI pipelines or when builds happen on a different machine than installs.

device-lab artifact stamp \
  --project <name> --platform <platform> --build-kind <kind> \
  --app-id <id> --path <file> --commit <sha> --source-type ci-build

device-lab artifact list

List registered artifacts, optionally filtered.

device-lab artifact list --project my-app

device-lab artifact latest

Get the latest artifact matching your filters.

device-lab artifact latest --project my-app --platform ios-sim --build-kind debug

device-lab ios install-latest

Find the latest matching artifact and install it on an iOS simulator (default) or a paired physical iOS device.

# Simulator (xcrun simctl) — default platform
device-lab ios install-latest --udid <sim-udid> --project my-app --build-kind debug

# Physical device (xcrun devicectl) — requires the device to already be paired
# with this Mac (`xcrun devicectl manage pair`) and unlocked
device-lab ios install-latest --platform ios-device --udid <device-udid> \
  --project my-app --build-kind preview

Physical-device installs drive xcrun devicectl device install app followed by xcrun devicectl device process launch. If the device isn't paired or is locked, device-lab reports a targeted hint instead of the raw devicectl error — it does not attempt to pair or unlock the device for you.

device-lab android install-latest

Find the latest matching artifact and install it on an Android emulator.

device-lab android install-latest --serial emulator-5554 --project my-app --build-kind debug

device-lab device record

Manually record an installation (for builds installed outside of device-lab).

device-lab device record \
  --device-id ios:<udid> --device-name "iPhone 16" \
  --platform ios-sim --project my-app --app-id com.example.myapp \
  --artifact-id <id>

device-lab status

Show the current state of your registry and devices.

device-lab status              # human-readable
device-lab status --json       # full registry dump
device-lab status --current    # latest per project/platform/build, with live presence

Filter with --project, --platform, --build-kind, --app-id.

device-lab drift detect

Compare recorded installations against live simulator/emulator state. Reports stale records and untracked app installs.

device-lab drift detect        # human-readable
device-lab drift detect --json # machine-readable

device-lab drift reconcile

Update stored presence from live checks. Use --prune-missing to remove records for apps that are no longer installed.

device-lab drift reconcile
device-lab drift reconcile --prune-missing

Supported platforms

| Platform | Flag | Tools used | |---|---|---| | iOS Simulator | ios-sim | xcrun simctl | | iOS Device | ios-device | xcrun devicectl | | Android Emulator | android-emu | adb | | Android Device | android-device | adb |

How it works

device-lab maintains a JSON state file at ~/.device-lab/state.json (or $DEVICE_LAB_ROOT/state.json). Every register, record, and install-latest updates this file. Drift commands compare it against live simctl / adb output.

No daemons, no databases, no network calls. Just a JSON file and your existing platform tools.

Suggested workflow

1. Build your app (locally or in CI)
2. Stamp a manifest: device-lab artifact stamp ...
3. Register it: device-lab artifact register --manifest <path>
4. Install it: device-lab ios install-latest ... or device-lab android install-latest ...
5. Check before starting work: device-lab status or device-lab drift detect

License

MIT