npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

emul

v1.0.1

Published

[![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)

Vulnerabilities

Powered byPowered by Snyk
  • 0High
  • 0Medium
  • 0Low

Links

Maintainers

sakhnyuksakhnyuk

Keywords

Readme

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

  1. 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

  2. Merge changes to main branch

  3. Trigger release:

  4. 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)