Agents and CLI

Give your coding agent a running Android app to test. The Ramus CLI (ramus-cli) starts an emulator, reads the screen, taps, types, and captures evidence. It requires Node.js 22 or later.

Start with a trial

Open the demo app without an account:

npx ramus-cli trial
npx ramus-cli session start --demo --wait

To test your own build, replace the second command with:

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 require an API key from a signed-in account. Signing up gives you 30 free minutes a month; see Plans and minutes.

npx checks the npm registry on every run, which adds roughly 5–8 seconds per command. For repeated use, install the CLI once with npm i -g ramus-cli and run ramus directly. The commands are otherwise identical.

Open the returned watchUrl to watch or take control in your browser. If there is none, run npx ramus-cli session share. Anyone with this link can operate the app, so share it only with the reviewers you intend. See Preview sessions for expiry and relaunch behavior.

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:

npx ramus-cli snapshot

The result lists visible elements with ref handles, plus a gen counter. Base your next action on those values. For example, if it shows a clickable e3 at generation 1:

npx ramus-cli tap e3 --gen 1 --expect "Welcome"

Replace the expected text with the outcome you want to check. Take a fresh snapshot before you choose another action: references expire after an accepted action or a newer snapshot.

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 --limit 200 reads the device log after a crash. app launch brings the app back.
session install --session <id> app-debug.apk installs a new build on a running device and opens it. The device keeps running, so use it instead of starting another session when you already have one, or when a start is refused at your device limit.

Prefix these commands with npx ramus-cli. They act on your most recent session unless you pass --session <id>. When everyone is finished, end the session with npx ramus-cli session end.

Connect your agent

To hand an agent a device already open in your account, choose Connect to agent in the device page header. Set an API key from the same account in your agent's environment, then copy the Agent prompt. It contains the current session ID and the commands to inspect that device. The MCP tab gives the server URL and setup instructions for an MCP client. Copying the instructions does not connect anything; the agent's first successful observation confirms the connection.

Anonymous share links grant browser access only. Connecting through the CLI or MCP requires an API key that belongs to the device's owner.

Ask 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 when available.

For Claude Code, save the android-use skill as .claude/skills/android-use/SKILL.md in your project, or clone it from github.com/ramus-dev/android-use. Other agents can use the same workflow through the CLI.

Clients without shell access can use the remote MCP server at https://api.ramus.dev/api/mcp. Clients that support MCP OAuth, such as ChatGPT and Codex, connect by signing in to Ramus and approving the connection; others use an API key. See the agent reference for authentication and supported tools. Uploading a local APK and running a development tunnel still require the CLI.

Use your account

Create an API key in Settings and set RAMUS_API_KEY wherever your CLI or agent runs. Keep the key out of chat messages and URLs. Run npx ramus-cli status to check authentication and active sessions.

Sessions you start with your key 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.

To open a PR preview whose build is ready:

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

To work on local changes with Fast Refresh or hot reload, continue to Local development.