New Research: Supply Chain Attack on Axios Pulls Malicious Dependency from npm.Details → →
Socket
Book a DemoSign in
Socket
Book a DemoSign in

emul

Package Overview
Dependencies
Maintainers
1
Versions
2
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

emul

[![CI](https://github.com/sakhnyuk/emucli/workflows/CI/badge.svg)](https://github.com/sakhnyuk/emucli/actions) [![npm version](https://img.shields.io/npm/v/emul.svg)](https://www.npmjs.com/package/emul)

latest
npmnpm
Version
1.0.1
Version published
Maintainers
1
Created
Source

emucli (emu)

CI npm version

emu is a Bun + Effect-TS CLI for discovering, booting, and automating iOS simulators and Android emulators/devices.

It is designed for agent/LLM use:

  • deterministic snapshot refs (@e1, @e2, …)
  • per-command --json output
  • stable exit codes + typed errors

Install

bun install
bun run build

Run from source:

bun run dev -- --help

Requirements

  • Bun
  • Android tooling for Android features:
    • adb
    • emulator
  • Xcode Command Line Tools for iOS features:
    • xcrun / simctl
    • xcodebuild (used to launch the vendored XCTest runner)

Quickstart

List devices:

emu devices list
emu devices list --platform ios
emu devices list --platform android --json

Boot:

emu boot <device-id> # UDID (iOS) or AVD name (Android)

Snapshot:

emu snapshot # single booted device will be used
emu snapshot --platform ios
emu snapshot --platform android --interactive  # flat list of clickable elements
emu snapshot --platform ios --max-depth 4 --compact
emu snapshot --platform ios --debug-dir ./debug/snap1 --json

The --interactive flag returns a dramatically reduced flat list (~20-40 elements) of only clickable items (buttons, cells, named images). Refs like @e73 are consistent across modes, so you can use --interactive to find elements then tap --ref @e73 to interact.

Interact:

emu tap --platform ios --ref @e5
emu swipe --platform android --direction down --ref @e2
emu input --platform ios --ref @e3 --text "hello"

App lifecycle:

emu install --platform android --path app.apk
emu install --platform ios --path My.app

emu open --platform android --app com.example.app
emu open --platform ios --app com.example.app

--json contract

  • --json is per-command (not global).
  • In --json mode:
    • stdout is JSON only (no extra logs)
    • errors are returned as a single JSON object (with a stable tag + message + details)

Documentation

  • Comprehensive docs: DOCUMENTATION.md — full feature reference and architecture
  • Agent guidelines: AGENTS.md — conventions for AI agents
  • Agent-facing docs: emu docs — token-efficient markdown
  • Exit codes: docs/EXIT_CODES.md — stable exit codes and JSON envelope

Publishing

This project uses semantic-release for automated versioning and publishing.

Release Process

  • Ensure all changes use conventional commits:

    • feat: add new command → minor version bump (1.0.0 → 1.1.0)
    • fix: resolve crash on startup → patch version bump (1.0.0 → 1.0.1)
    • feat!: change CLI argument format → major version bump (1.0.0 → 2.0.0)
    • Or with body: feat: new feature\n\nBREAKING CHANGE: description

  • Merge changes to main branch

  • Trigger release:

  • semantic-release will:

    • Analyze commits since last release
    • Determine version bump
    • Update CHANGELOG.md
    • Update package.json version
    • Create git tag
    • Publish to npm (includes vendored Android and iOS runners)
    • Create GitHub release

Commit Message Format

<type>(<scope>): <subject>

<body>

<footer>

Types:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation only
  • style: Code style changes (formatting, etc)
  • refactor: Code refactoring
  • perf: Performance improvements
  • test: Adding or updating tests
  • chore: Maintenance tasks

Examples:

git commit -m "feat: add snapshot debug artifacts"
git commit -m "fix: resolve Android input encoding issue"
git commit -m "docs: update installation instructions"
git commit -m "feat!: change device ref format to platform:id"

Development

bun test
bunx tsc --noEmit

Opt-in integration tests

By default, tests run without requiring any emulator/simulator tooling.

To run the opt-in integration suite against a real booted device:

EMUCLI_INTEGRATION=1 bun test test/integration.test.ts

Useful environment variables:

  • EMUCLI_INTEGRATION_PLATFORM=ios|android|all (default: all)
  • EMUCLI_IOS_DEVICE=ios:<udid> (optional; otherwise uses active device resolution)
  • EMUCLI_ANDROID_DEVICE=android:<serial> (optional)
  • EMUCLI_IOS_INPUT_REF=@eN (optional; auto-discovery will try to find a usable Search/TextField)
  • EMUCLI_IOS_SEARCH_QUERY=... (default: Search, used for auto-discovery)
  • EMUCLI_ANDROID_INPUT_REF=@eN (optional)

FAQs

Package last updated on 19 Jan 2026

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

Attackers Are Hunting High-Impact Node.js Maintainers in a Coordinated Social Engineering Campaign

Security News

Attackers Are Hunting High-Impact Node.js Maintainers in a Coordinated Social Engineering Campaign

Multiple high-impact npm maintainers confirm they have been targeted in the same social engineering campaign that compromised Axios.

By Sarah Gooding  -  Apr 03, 2026