ramus-cli

Drive live Ramus Android emulator sessions from a terminal or a coding agent: create a session from an APK or a pull request's preview build, read the UI tree, tap, type, take screenshots, read logcat, and hand a human a share link to try the app in their browser.

Current agent-facing reference: https://ramus.dev/agents.md

Setup

export RAMUS_API_KEY=...   # create one at https://ramus.dev/settings (API keys)

Never paste keys into chat or URLs — set the environment variable.

Quick start

npx ramus-cli session start --apk app/build/outputs/apk/debug/app-debug.apk --wait
npx ramus-cli snapshot                 # UI tree with ref handles
npx ramus-cli tap e3 --gen 1           # act by ref (stale refs error, never mis-tap)
npx ramus-cli screenshot --out screen.jpg
npx ramus-cli session share            # 72h link anyone can open to try the app
npx ramus-cli session end

All commands print JSON on stdout; errors are JSON with exit code 1 and name the next command to run. ramus help lists everything. screenshot writes ./ramus-screen.jpg unless --out is given.

Session commands auto-spawn a small local daemon (~/.ramus) that holds the session WebSocket so repeated commands skip reconnect overhead. It receives your credentials per request (never stores them), exits after 10 idle minutes, and ramus daemon --stop stops it immediately.

The driving loop

Observe → act → observe. snapshot returns elements with ref handles and a gen; act by ref (tap e3 --gen 2); refs go stale when the screen changes and return an error telling you to re-snapshot. After navigation, wait --stable. When the tree is thin (games, some WebViews), fall back to screenshot and normalized coordinates (tap 0.5,0.72).

PR previews

Requires the Ramus GitHub App on the repository — installing it needs a human in a browser. ramus status reports the current repo's state; ramus install prints the install URL to hand to the user, and ramus install --wait polls until the installation lands. Then:

npx ramus-cli session start --pr owner/repo#123 --wait

Hot reload: the emulator as a local adb device

ramus adb tunnels the session's adbd to a port on your machine and adb connects it, so the cloud emulator shows up in adb devices and every local toolchain works as if it were plugged in — including adb reverse, so Metro on your laptop is localhost:8081 inside the emulator.

npx ramus-cli adb                      # -> { serial: "127.0.0.1:53124", ... }
adb -s 127.0.0.1:53124 install -r app-debug.apk
adb -s 127.0.0.1:53124 reverse tcp:8081 tcp:8081

ramus dev is the shape-aware version: it detects Expo / React Native / Flutter / Gradle in the current directory (or --app-dir), starts a session if none is live, opens the tunnel, and runs the framework's own dev loop against the emulator. Edit a file; Expo/RN Fast Refresh and Flutter hot reload apply it live.

npx ramus-cli dev                      # expo: expo run:android; RN: run-android + Metro;
                                       # flutter: flutter run; gradle: installDebug + launch
npx ramus-cli dev --apk app-debug.apk  # install a build you already have, then Metro
npx ramus-cli dev reload [--full]      # flutter: hot reload / restart; gradle: reinstall
npx ramus-cli dev status | stop        # stop ends the loop, keeps the session

Expo/RN debug builds need the local Android SDK for the first build; Flutter must build locally (the attaching SDK has to match the APK). Do not run adb root, adb unroot, adb reboot or adb reverse --remove-all on the tunneled device: adbd restarts and the session ends.

MCP

For clients that cannot shell out, the same verbs are exposed as android_* tools by the Ramus MCP server (Streamable HTTP, Authorization: Bearer with your API key) — see https://ramus.dev/agents.md for the current endpoint.

MIT © Ramus