ramus-cli

Drive live Ramus Android emulators from a terminal or coding agent: upload an APK, open a ready PR build, inspect the UI, and share a browser session with a human. Requires Node.js 22+.

Explore coding-agent testing, browser APK testing, or GitHub PR previews.

Start without an account

npx ramus-cli trial
npx ramus-cli session start --demo --wait
npx ramus-cli snapshot
npx ramus-cli screenshot --out screen.jpg

For your own build, replace --demo with --apk app-debug.apk. The trial credential lasts 15 minutes and is stored locally. Trials allow one active session and a 150 MB APK, with no GitHub features or adb/dev. For signed-in access, create a key at Settings and set RAMUS_API_KEY in your environment. Do not paste keys into chat or URLs.

Share the returned watchUrl with the user: it lets them watch and control the emulator without an account. Links expire after 72 hours by default. While valid, a link can offer a fresh launch after the session ends, subject to relaunch limits, capacity, and the app or build remaining available; it does not restore old device state. If absent, mint a link with session share while live. Minting replaces and revokes the previous link, including the original watch URL, so share the replacement. session share --revoke revokes the link. End with session end when the session is no longer needed; ending the session does not revoke its link.

Drive and verify

Commands use the last session unless given --session <id>. session install --session <id> app.apk installs a new build on a running session and opens it, keeping the device; prefer it over starting another session (a start at the device limit is refused with the live session ids).

1. Read snapshot, or snapshot --find "label". Choose a clickable element and use its returned values in tap <ref> --gen <gen>.
2. Add --expect "result" or --expect-gone "old text" to verify the tap. For fields, type "hello" --ref <ref> --gen <gen> focuses, replaces, and attempts read-back; inspect verified in the result.
3. Re-observe before the next action. Accepted actions and later snapshots invalidate refs. On stale_ref, take a new snapshot and resolve again.

Use wait --text "Welcome", wait --gone "Loading", or wait --stable after navigation. If the tree is incomplete, inspect a screenshot and tap normalized coordinates such as tap 0.5,0.72. press IME_HIDE hides the keyboard; app launch restores the app after HOME, backing out, or a crash. Collect logcat --limit 200 before recovering from a crash or hang.

With a signed-in key, camera --image qr.png shows a still on the device's back camera and mic --audio hello.wav [--loop] plays a PCM WAV into its microphone; both stay until replaced, --off, or the session ends.

npx ramus-cli help lists commands; append --help for flags. Command results and handled errors are JSON; top-level help is plain text. Handled failures exit 1 and progress may appear on stderr. Screenshots default to ./ramus-screen.jpg.

PR previews

A signed-in key, GitHub access, and the Ramus GitHub App on the repository are required. status reports the current repository's state. install returns a URL for a human to complete setup; install --wait polls it.

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

Local development

With a signed-in key and local Android platform-tools, adb opens a tunnel and connects the emulator to your adb server. Use the returned serial with adb -s <serial> for installs, logs, and port reversal. adb --status inspects it; adb --close closes it.

dev detects Expo, React Native, Flutter, or Gradle in the current directory, starts or reuses a session, and runs local tooling against it. It requires the project's SDKs; the first build can take minutes. Use --app-dir or --shape to override detection and --apk for a prebuilt APK where supported.

npx ramus-cli dev
npx ramus-cli dev status
npx ramus-cli dev reload
npx ramus-cli dev stop

Expo/RN use Fast Refresh. dev reload triggers Flutter hot reload (--full restarts) or Gradle reinstall. dev stop stops the process and tunnel, keeping the session. Avoid adb root, adb unroot, and adb reboot, which can break the session, and adb reverse --remove-all, which removes dev port mappings.

Configuration and reference

| Variable | Purpose | | --- | --- | | RAMUS_API_KEY | Signed-in API key; otherwise the CLI uses its stored trial credential. | | RAMUS_API_ORIGIN | API origin; defaults to https://api.ramus.dev. | | RAMUS_CONFIG_DIR | Local state, daemon socket, and dev logs; defaults to ~/.ramus. Use separate directories for independent CLI state. |

status reports connection and credential state. Session commands can start a local daemon to reuse the session connection; daemon --stop stops it. It exits after ten idle minutes.

• Agent guide: task walkthrough.
• Agent reference: current limits and capabilities.
• Installable skill: reusable agent workflow.
• Documentation index.

MCP is available at https://api.ramus.dev/api/mcp (Streamable HTTP, Bearer API key). Discover android_* tools with tools/list. It supports driving and demo/PR/known-URI session starts; local APK upload, adb tunnels, and the dev loop require the CLI. The underlying HTTP API is not a stable public contract.

MIT © Ramus