sims-cli

Imported from siner308/sims (skills/sims-cli/SKILL.md). Install upstream with npx skills add siner308/sims --skill sims-cli. Copyright stays with the author.

sims

sims is one command over the Android and iOS device tools. Every subcommand addresses a device by name or id, takes --json, exits 0 or 1, and never asks a question, so it fits a script or an agent better than the tools underneath. This file covers the whole command surface.

Check it is there with command -v sims. If not, install with curl -fsSL https://raw.githubusercontent.com/siner308/sims/main/install.sh | sh (macOS and Linux; Windows takes the zip from the releases page). sims doctor reports which of adb, emulator, avdmanager, sdkmanager, aapt2, xcrun simctl, devicectl and idevicesyslog it found.

A bare sims opens an interactive terminal UI, so always give a subcommand.

How to work

1. List first, then act by id. Run sims device list --json (-p android or -p ios narrows it) and pick the id. Lookup by name is an exact, case-insensitive match: pixel does not find Pixel_7. When a name matches two devices the command fails and prints both ids.
2. Read state before acting. A virtual device is usable at Booted; app *, logs and key fail with device is not running on a Shutdown one, so boot it first with --wait. A paired iPhone works at Offline too: that state means CoreDevice let the idle wifi tunnel go, and the next command reopens it, so sims device connect is for opening the tunnel on purpose, not a prerequisite.
3. Pass --json and parse it rather than reading the table. The record shapes are below.
4. Ask before erase, delete and uninstall. sims does not confirm; these act at once. Say what will be lost and wait for the user unless they asked for exactly that.
5. Bound anything that streams or waits. device logs and app logs run until killed, so run them under timeout 30 ... (GNU coreutils; on macOS brew install coreutils) or in the background with output redirected to a file and kill them after. timeout exits 124 when it cuts the stream, which is the normal end of a capture, so a script under set -e treats 124 as success. boot --wait, wait and create --boot block up to --timeout (default 3m). image install takes minutes. device pair <iphone> waits up to 2 minutes for the user to tap Trust on the phone, so tell them before running it.
6. On any failure read stderr. The reason follows sims:; the table at the end maps the common ones to the next step.

Commands

Aliases: device = devices = dev, app = apps, image = images = img, device-type = device-types = types, every list = ls. Global flags: --json and --platform android|ios (-p). <device> is an id (AVD name or simulator UDID), an adb serial, or an exact name.

sims device list [--all] [--json]           # --all includes never-booted simulators (hidden by default)
sims device get <device>
sims device boot <device> [--wait] [--timeout 3m]
sims device wait <device> [--timeout 3m]    # until Booted or Connected
sims device shutdown <device>
sims device erase <device>                  # factory reset; needs Shutdown first; no confirmation
sims device delete <device>                 # remove an AVD/simulator; on a phone: ios unpairs, android drops wifi
sims device create <name> --image <image> [--type <type>] [--ram MB --cores N --disk GB] [--boot] [--timeout 3m]
sims device hardware <device> [--ram MB --cores N --disk GB]   # AVD only; no flags prints current values
sims device key <device> home|back|overview # android only
sims device screenshot <device> [path]      # PNG; no path names it after the device and the time, - writes to stdout
sims device reboot <device> [--wait] [--timeout 3m]   # simulator: shutdown and boot again
sims device logs <device> [--app <bundle-or-name>]
sims device connect <device>                # iPhone: open wifi tunnel; USB Android phone: switch to adb over wifi
sims device connect <host:port>             # adb connect (20s limit)
sims device pair <device>                   # iPhone over USB; user must accept the prompt on the phone
sims device pair <host:port> <code>         # Android 11+ wireless debugging
sims device disconnect <device>             # adb disconnect

sims app list <device> [--all]              # --all includes system/preinstalled apps; running apps sort first
sims app install <device> <path>            # .apk (android); .app or .ipa on a simulator; .app on an iPhone
sims app uninstall <device> <bundle-id>     # no confirmation
sims app launch <device> <bundle-id>
sims app logs <device> <bundle-id-or-name>  # android: the app must already be running

sims proxy run <device> [--port N] [--har out.har] [--for 30s] [--all] [--quiet]
sims proxy ca [device] [--install]          # print the root certificate, or trust it on a device
sims proxy clean                            # put back what a capture killed mid-run left behind

sims image list [--all]                     # installed system images and simulator runtimes; --all adds downloadable
sims image install <image>                  # android only; iOS runtimes: xcodebuild -downloadPlatform iOS
sims device-type list [--image <image>]     # hardware profiles; --image keeps only those that run it

sims doctor                                 # toolchain check, exit 1 if something is missing
sims update [--check]                       # also refreshes installed copies of this skill
sims skill [install [--dir <skills-dir>] [--refresh]]   # print this file / install it for the agents on this machine

--image and --type accept an id or name from the matching list, but Android image names repeat across API levels (google_apis_playstore arm64-v8a exists for 30, 31, 35 and 36), so pass the Android image id. Without --type sims picks pixel_7 on Android and iPhone 17 Pro on iOS, falling back to the newest iPhone or the first type that runs the image. --ram, --cores and --disk are refused on iOS. --help on any subcommand prints the exact flags of the installed version.

proxy run holds until interrupted, so it needs --for or a timeout, exactly like the log streams. It prints one line per exchange (--json prints a record per flow, headers and both bodies included: requestBody and responseBody, decoded from gzip/brotli, with responseBodyEncoding: "base64" when the body is not text) and restores the device and this machine on exit. An iOS simulator has no network settings of its own, so its capture points this Mac's web proxy at sims for as long as it runs; other apps on the Mac are relayed untouched and are not captured unless --all is given. In the TUI the log and the traffic are two layers of one stream, toggled with l and t; shift+t on a device opens the capture as a table instead, where g groups it by domain, which is how a device's traffic is read when the app behind it is unknown. A device's connections do not say which app opened them, so traffic captured from a phone or an emulator is the whole device's; only a simulator or this machine names the sending process. Never report a captured request as a particular app's unless the flow's process field says so.

A tunnel line is traffic sims could not open, which means the app pins its certificate: that is a limit of every proxy, not a failure to report.

A flow carrying "abandoned": true is not an error either. The client closed the connection before the response finished, which is what a browser does when it has seen enough of an image and what a cancelled request looks like; the app got what it asked for. status is the one it received and responseSize counts what arrived, so the stored body stops short of responseHeaders' Content-Length. Only error means the exchange failed.

JSON shapes

device list, device get and every device action print this record. Actions print the device they acted on; boot --wait and wait print the refreshed record, so state and serial are current. Fields marked * are omitted when empty.

app list: bundleId, name, version, system (bool), running (bool), source (preinstalled, store, adb, simctl, process), process*. Running apps sort first, then by name.

On a physical iPhone devicectl often lists no apps at all, even unlocked with apps plainly running. sims falls back to the running processes there, which is why those entries carry "source": "process", a name and no bundleId. Commands that need a bundle id do not work on them.

image list: id (system-images;android-36;google_apis_playstore;arm64-v8a or com.apple.CoreSimulator.SimRuntime.iOS-26-5), name, version* (36, 26.5), installed, os*, platform.

device-type list: id (pixel_7, com.apple.CoreSimulator.SimDeviceType.iPhone-16), name, screen, minRuntime, maxRuntime, family, platform.

device hardware: ramMb, cores, diskGb.

connect and pair by address: {"address": "host:port"}. doctor, update and the log streams ignore --json.

Recipes

Boot, install, launch, follow the log for a minute:

ID=$(sims device list --json -p android | jq -r '.[] | select(.state=="Shutdown") | .id' | head -1)
sims device boot "$ID" --wait
sims app install "$ID" app/build/outputs/apk/debug/app-debug.apk
sims app launch "$ID" com.example.app
timeout 60 sims app logs "$ID" com.example.app > app.log || [ $? -eq 124 ]

Look at what is on screen. A screenshot is the way to check an app that draws its own interface, since a Unity or Flutter canvas puts no text in the accessibility tree:

sims device screenshot "$ID" /tmp/screen.png   # then read the image
sims device screenshot "$ID" - | <another command>

Find a running device on either platform:

sims device list --json | jq -r '.[] | select(.state=="Booted" or .state=="Connected") | "\(.platform) \(.id)"'

Create an emulator for an API level and boot it:

sims image list --json -p android | jq -r '.[] | select(.version=="35") | .id'   # empty? sims image list --all, then sims image install <id>
sims device-type list --json -p android | jq -r '.[].id' | grep -i pixel
sims device create Pixel_8_API_35 --image "system-images;android-35;google_apis_playstore;arm64-v8a" --type pixel_8 --boot

Create a simulator for a runtime (sims cannot install iOS runtimes):

sims image list --json -p ios                          # pick a runtime id or "iOS 26.5"
sims device-type list --json --image "iOS 26.5" | jq -r '.[].name'
sims device create "QA iPhone" --image "iOS 26.5" --type "iPhone 16"

Put a USB Android phone on wifi, or connect one that already has wireless debugging on:

sims device connect <serial>                 # switches the USB phone to adb over tcp, prints host:port
sims device pair 192.168.0.12:37123 482913   # pairing port and code from the phone's Wireless debugging screen
sims device connect 192.168.0.12:5555        # the connect port, not the pairing port

Watch what an app sends, then read it back:

ID=$(sims device list --json | jq -r '.[] | select(.state=="Booted") | .id' | head -1)
sims proxy run "$ID" --for 60s --har traffic.har --quiet
jq -r '.log.entries[] | "\(.response.status) \(.request.method) \(.request.url)"' traffic.har

When something fails

Exit status is 1 and the reason is on stderr after sims:. A usage mistake adds a see 'sims ... --help' line; a device that is not found does not. A listing whose one platform failed still prints the other and reports the failure on stderr, so check stderr even on exit 0.