The Ramus CLI

The CLI starts Android emulators, uploads your builds, reads the screen, taps, types and captures evidence. Agents with a shell use it the same way you do. It needs Node.js 22 or later.

The package is ramus-cli and the command is ramus. Install it once, or run any command one-off with npx ramus-cli …:

npm i -g ramus-cli

npx checks the npm registry on every run, which adds roughly 5–8 seconds per command, so install it for repeated use. Agents that connect over MCP instead are covered in Connect an agent.

New: sign in from the terminal. Your browser opens to sign in with Ramus and approve the CLI:

ramus login

Over SSH or in a container, ramus login shows a code instead: approve it at ramus.dev/device on any device. When your coding agent runs ramus login, it gives you the link to approve and finishes with ramus login --wait. The terminal stays signed in until you run ramus logout or sign it out on Agents.

Where nobody can approve a sign-in, such as CI or a cloud agent, create an API key on Agents and set it as RAMUS_API_KEY wherever the CLI runs. Keep keys out of chat messages and URLs. ramus status shows who you are signed in as and your running sessions.

Start a device

ramus session start --apk app-debug.apk --wait

Replace app-debug.apk with the path to your build. Open the returned watchUrl to watch in your browser. It is view-only; to take control, run ramus session open and open that device page, signed in. If there is no watchUrl, run ramus session share.

ramus session start --pr owner/repo#123 --wait opens a pull request whose build is ready.
ramus session start --demo --wait opens a demo app.
ramus session install --session <id> app-debug.apk installs a new build on a running device and opens it. Use it instead of starting another device when you already have one, or when a start is refused at your device limit.

Commands act on your most recent session unless you pass --session <id>. End the device with ramus session end.

Verify a flow

ObserveRead the screen.
Get fresh refs.

ActTap, type, or swipe
on what you found.

VerifyCheck the result
against your goal.

Observe again before the next action

Observe, act, verify. Read a snapshot and its ref/gen values, act on what it shows, then check the result. Take fresh references before the next action. An accepted tap alone does not prove the flow worked.

Start by observing the screen:

ramus snapshot

The result lists visible elements with ref handles, plus a gen counter. Tap an element by the text it shows, or by its ref at that generation:

ramus tap --text "Sign in" --expect "Welcome"
ramus tap e3 --gen 1

Replace the expected text with the outcome you want to check. Every action returns the screen it led to, with fresh references, so the next step can use them directly; references from earlier looks expire.

type "hello" --ref <ref> --gen <gen> focuses a field and enters text. Check the returned verified value, then observe the result.
wait --text "Welcome" waits for a specific state; wait --stable waits for the screen to settle after navigation.
screenshot --out screen.jpg captures evidence. If the UI tree is incomplete, look at the screenshot and tap by normalized coordinates, such as tap 0.5,0.72.
logcat --filter AndroidRuntime reads a crash's stack trace (--limit 200 for the recent log). app launch brings the app back.
session share --permission watch makes a view-only link for someone who should not touch the device.
session share --own makes a link that gives each person their own device of your uploaded app; feedback reads the notes they send back. See Share a running app.

Prefix these with ramus. To edit code and see it on the device, continue to Local development.

Hand a device to your agent

Tell your agent to read ramus.dev/agents.md, then give it the APK path and a specific flow to verify. Ask it to report what it observed, with a screenshot and the watch link.

To hand over a device that is already open in your account, choose Connect to agent in the device page header. Its tabs set up each agent (Claude Code, Codex, Cursor, ChatGPT or the CLI), and Prompt carries the session ID and the commands to inspect that device. The agent's first successful observation confirms the connection. Share links grant browser access only, so the agent needs your sign-in or an API key from the device's owner.

To teach your agent the CLI, install the android-use skill for the version you have:

ramus skill install            # Claude Code, this project (.claude/skills)
ramus skill install --codex    # Codex

--global installs it for Claude Code in every project. The source is at github.com/ramus-dev/android-use.

Minutes and limits

Sessions you start use your plan's minutes and device limit. After session start the CLI prints the minutes left this month on metered plans. When you are out of minutes, starts fail with quota_exhausted until your minutes reset or you upgrade in Settings. See Plans and minutes.

Try without an account

A trial gives you or your agent a device without signing up:

npx ramus-cli trial
npx ramus-cli session start --apk app-debug.apk --wait

The trial saves a temporary key on your machine and lasts 15 minutes. It allows one active session and APKs up to 150 MB. PR previews and local development tunnels need a signed-in account.