Use
Commands & options
| Command | What it does |
|---|---|
| Look | |
looktap ls [--all] [--json] | Visible elements with a label, plus unlabelled buttons, each with an @ref. --all includes everything. --json prints {screen, elements}. While the screen is still loading (nothing labelled yet), waits up to --wait |
looktap wait <label|@ref> [--gone] | Until it's on screen (with --gone, until it isn't). Default up to 10 s, or --wait. Exits 2 on timeout |
looktap scrollto <label> [--up] | Swipes until the element is fully on screen. Fails at the end of the list, or after 15 swipes |
looktap shot <name> [--plain] [--scale f] | Saves <out>/<name>.png and prints its path |
looktap burst <dir> <seconds> | A frame each time the screen changes. Only distinct frames are kept |
looktap record start [name] · record stop | An MP4 of everything in between, saved to <out>/<name>.mp4; stop prints the path and the length. Android: at most 3 minutes, FLAG_SECURE screens black |
Act (add --ls to print the settled screen afterwards) | |
looktap tap <label|@ref> [--exact] | @ref from the last ls, or a label: exact, else a prefix/contains match that names a single label (ambiguous → exit 2). Prints what it tapped |
looktap longpress <label|@ref|x y> [ms] | Holds the touch for ms (default 800). Same targets as tap, or a point |
looktap zoom in|out [x y] [--scale f] | Two-finger pinch around a point (default: the screen centre). --scale sets how far apart the fingers end up (default 2.5) |
looktap tapxy <x> <y> | Taps a point (iOS points / Android dp) |
looktap type <text> | Types into the focused field. Text the keyboard can't type (accents, emoji, CJK) is pasted, which replaces the clipboard |
looktap key <name> … | return, escape, delete, tab, space. Android also back, home, any KEYCODE_*. iOS also selectall, paste |
looktap fill <label|@ref> <text> [--exact] | Focuses the field, clears it, types. Empty text just clears |
looktap hidekb | Dismisses the keyboard, checking after each method. Exits 2 if it's still up |
looktap swipe <x1> <y1> <x2> <y2> [ms] | Default 150 ms on iOS, 300 ms on Android |
looktap back | Android system Back · iOS: the navigation bar's back button, else a top-left "Back" button |
looktap open <url> | Opens a deep link |
looktap launch [app] | (Re)starts the app |
looktap bio match|nomatch | Face ID (iOS) or fingerprint (Android) |
looktap rotate [portrait|landscape|left|right|upsidedown] | Turns the device (landscape = left, turned counter-clockwise). ls, taps and screenshots follow the turned screen. Says so if the app doesn't support the orientation. Without an argument, prints the current one |
Debug ([app] defaults to --app / config, else the app in front) | |
looktap logs [app] [--errors] [--grep re] [--since 5m] [--lines n] [--all] | The app's log since the last logs (the first call covers the last minute). At most 80 lines, newest kept |
looktap crashes [app] [--since 1h] | Crashes, ANRs and low-memory kills since the last crashes (the first call covers the last hour) |
looktap app [app] | The app in front and its pid, and whether [app] is running |
App state (<app> from the argument or --app / config, never the app in front) | |
looktap install <path> [--grant] | iOS: a simulator .app. Android: an .apk, replacing an installed copy and keeping its data (--grant: all runtime permissions). Prints the app id |
looktap uninstall <app> | Removes the app |
looktap reset <app> | As if freshly installed: data and permissions cleared. iOS: the keychain survives |
looktap permission grant|revoke|reset <name> [app] | camera, microphone, location, location-always, photos, contacts, calendar, notifications, motion, all, … Android also takes android.permission.* |
| Conditions | |
looktap location <lat> <lon> · location clear | Simulated GPS. Android: emulators only, and the emulator keeps its last fix (no clear) |
looktap appearance [dark|light] | Dark mode. Without an argument, prints the current mode |
looktap textsize [size] | Dynamic Type (iOS) / font scale (Android): xs s m l xl xxl xxxl ax1…ax5, or iOS names such as accessibility-large. Without an argument, prints the current size |
looktap statusbar clean|live | A screenshot-clean status bar (9:41, full battery and Wi-Fi), or back to live values |
looktap network [offline|online] | Android only: airplane mode on or off, waiting until the device has lost (or regained) its connection. Without an argument, prints the current state |
looktap push <app> <payload> | iOS: a remote notification. The payload can be a .json file, inline JSON, or plain text for an alert |
| Batch, setup & info | |
looktap mcp [--config] | Serves these commands over MCP (stdio) for clients without a shell. --config prints a client config |
looktap run '<cmd>; <cmd> …' | Several commands in one process. run - reads them from stdin. Stops at the first failure and names it |
looktap skill [--install] | Prints the AI-agent guide, or installs it as a Claude Code skill |
looktap devices | Booted simulators and adb devices |
looktap doctor | Checks Node, Xcode and the simulator frameworks, adb, and booted devices |
looktap setup | Starts the helper ahead of time. Android: also adb reverse tcp:8081 for Metro |
looktap teardown | Stops the helper. Android: also removes adb reverse rules |
--ls works on tap, longpress, zoom, tapxy, fill, type, key, hidekb, swipe, back, open, launch, bio,
rotate and scrollto. After the action it waits for the screen to change (up to 1.5 s, or 6 s for launch/open), then for
it to stop changing, then prints it like ls.
Exit codes: 0 means OK. 2 means a usage problem: bad arguments, element not found, no device, or the
helper can't start. 1 means anything else failed. A script can set -e and stop at the first missing element.
Options, environment variables, config file
| Option | Meaning |
|---|---|
-p, --platform ios|android | Default: whichever has a booted device. Required when both do |
-d, --device <udid|serial> | Default: the only booted one |
-o, --out <dir> | Folder for screenshots and videos (default shots) |
--wait <seconds> | How long tap, fill and back look for their target (default 3). An ambiguous match fails at once |
--app <id> | App id for launch, open, logs, crashes, app, uninstall, reset and permission |
-h, --help · -v, --version |
| Environment variable | Meaning |
|---|---|
LOOKTAP_PLATFORM, LOOKTAP_DEVICE, LOOKTAP_OUT, LOOKTAP_WAIT | Defaults for -p, -d, -o, --wait |
LOOKTAP_SCALE | Override Android's px-per-dp (normally read from wm density) |
LOOKTAP_ANDROID_HELPER=0 | Plain adb + uiautomator dump instead of the helper (slower) |
LOOKTAP_EMULATOR_GRPC=0 | Don't take emulator frames over gRPC: use the emulator console |
LOOKTAP_IOS_HID=indigo|dtuhid | Force the iOS input path. Takes effect when the helper starts |
LOOKTAP_HOME | Where sockets, logs and state live (default ~/.looktap) |
Config file. looktap uses the nearest looktap.config.json, walking up from the current folder. Put it at
the root of your app's repo:
{
"out": "shots",
"wait": 3,
"ios": { "app": "com.example.myapp" },
"android": { "app": "com.example.myapp" }
}Precedence: command-line option, then environment variable, then config file, then built-in default.
Files looktap writes
| Path | What |
|---|---|
~/.looktap/sim-<udid prefix>.sock, .log | The iOS helper's socket and log |
~/.looktap/helpers.json | Which local port reaches each Android device's helper |
~/.looktap/refs/<device>.json | What @1…@N meant in the last ls on that device |
~/.looktap/marks/<device>.json | Where the last logs / crashes stopped |
~/.looktap/recordings.json | Recordings in progress, so record stop can find them |
~/.looktap/rec-<udid prefix>.log | The iOS recorder's output |
~/.looktap/shots/ | Where the MCP server saves screenshots unless -o / LOOKTAP_OUT / config says otherwise |
/data/local/tmp/looktap-server.jar (device) | The Android helper |
/data/local/tmp/looktap-recording.mp4 (device) | An Android recording in progress, removed when it's copied off |
<out>/<name>.png, <out>/<name>.mp4 | Your screenshots and videos |
Generated from README.md. Edit it there.