Skip to content
Ramus
Menu
Sign inStart free

Agents and CLI

Give your coding agent a running Android app to inspect. The Ramus CLI can start an emulator, read the screen, tap, type, and capture evidence. It requires Node.js 22 or later.

Start with a trial

Run these commands to 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 stores a temporary key locally and lasts 60 minutes. It allows one active session and APKs up to 150 MB. GitHub previews and local development tunnels require a signed-in API key.

Open the returned watchUrl to follow along or take control in your browser. If it is missing, run npx ramus-cli session share. Anyone with this link can operate the app, so share it only with intended reviewers. 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 that observation, then check the result. Repeat with fresh references for the next action. An accepted tap alone does not prove the flow worked.

Start with an observation:

npx ramus-cli snapshot

The result includes visible elements with ref handles and a gen counter. Use values from that result for your next action. 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 choosing another action; old references expire after an accepted action or a later snapshot.

  • Use type "hello" --ref <ref> --gen <gen> to focus a field and enter text. Check the returned verified value and observe the result.
  • Use wait --text "Welcome" for a specific state, or wait --stable after navigation.
  • Capture evidence with screenshot --out screen.jpg. If the UI tree is incomplete, inspect the screenshot and use normalized coordinates, such as tap 0.5,0.72.
  • Read logcat --limit 200 after a crash. Use app launch to return to the app.

Prefix these commands with npx ramus-cli. Commands use the most recent session unless you pass --session <id>. End a session with npx ramus-cli session end when everyone is finished.

Connect your agent

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 and include a screenshot and the watch link when available.

For Claude Code, save the Ramus skill as .claude/skills/ramus/SKILL.md in your project. 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. See the agent reference for authentication and supported tools. Uploading a local APK and running a development tunnel require the CLI.

Use your account

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

For a ready GitHub preview build:

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.