Device Commands - Revyl Documentation

The revyl device command group lets you provision cloud-hosted mobile devices, install apps, and interact with them directly from your terminal. Every command has an equivalent MCP tool for AI agent integration.

If you want task-oriented onboarding first, use Device Quickstart, then Python SDK Quickstart or Device Troubleshooting.

Overview

Device sessions are cloud-hosted Android or iOS devices that you can control remotely. The typical lifecycle is:

Start a session with revyl device start
Install an app with revyl device install
Interact using tap, type, swipe, and other action commands
Stop the session with revyl device stop

Sessions auto-terminate after 5 minutes of inactivity (configurable with --timeout).

AI-Powered Grounding

Action commands like tap, type, and swipe support natural language targeting. Instead of specifying pixel coordinates, describe the element you want to interact with:

revyl device tap --target "Sign In button"
revyl device type --target "email input field" --text "[email protected]"
revyl device swipe --target "product list" --direction down

The CLI takes a screenshot, sends your description to the AI grounding model, and resolves it to pixel coordinates automatically. You can also pass raw --x and --y coordinates as an override.

Multi-Session Support

You can run multiple device sessions simultaneously. Sessions are indexed starting at 0, and one session is always marked as “active”:

revyl device start --platform android    # Session 0 (active)
revyl device start --platform ios        # Session 1
revyl device use 1                       # Switch active to session 1
revyl device tap --target "button" -s 0  # Target session 0 explicitly

Common Flags

These flags are shared across most device commands:

Flag	Short	Default	Description
`--json`		`false`	Output results as JSON
`-s`		`-1`	Session index to target (`-1` = active session)

Session Management

`revyl device start`

Provision and start a new cloud device session.

revyl device start --platform <ios|android> [flags]

Flag	Default	Description
`--platform`		Platform: `ios` or `android` (required)
`--timeout`	`300`	Idle timeout in seconds
`--open`	`false`	Open the live viewer in your browser after the device is ready
`--json`	`false`	Output as JSON

Examples:

revyl device start --platform android
revyl device start --platform ios --open --timeout 600

The response includes a viewer_url you can open in your browser to watch the device live.

`revyl device stop`

Stop one or all device sessions.

revyl device stop [flags]

Flag	Default	Description
`-s`	`-1`	Session index to stop (`-1` = active session)
`--all`	`false`	Stop all sessions
`--json`	`false`	Output as JSON

Examples:

revyl device stop              # Stop active session
revyl device stop -s 2         # Stop session at index 2
revyl device stop --all        # Stop all sessions

`revyl device list`

List all active device sessions.

revyl device list [flags]

Flag	Default	Description
`--json`	`false`	Output as JSON

Output columns: # (index, * marks active), PLATFORM, STATUS, SESSION ID, UPTIME.

`revyl device use`

Switch the active session to a different index.

revyl device use <index>

Example:

revyl device use 2    # Make session 2 the active session

`revyl device info`

Show details about a device session: session ID, platform, viewer URL, and uptime.

revyl device info [flags]

Flag	Default	Description
`-s`	`-1`	Session index (`-1` = active session)
`--json`	`false`	Output as JSON

`revyl device doctor`

Run diagnostics on auth, session health, worker reachability, and device connectivity.

revyl device doctor [flags]

Flag	Default	Description
`-s`	`-1`	Session index (`-1` = active session)

Checks performed:

Authentication (API key / login status)
Active session existence
Worker reachability
Device connectivity (via health endpoint)
Lists all active sessions with markers

Device Actions

All action commands support two targeting modes:

Grounded (default): Pass --target "element description" and coordinates are resolved via AI
Raw coordinates: Pass --x and --y for direct pixel targeting

Describe what you see on screen. Prefer visible text/labels ("the 'Sign In' button"), visual characteristics ("blue rounded rectangle"), or spatial anchors ("text area below the 'Subject:' line"). Avoid abstract UI jargon.

`revyl device tap`

Tap an element by description or coordinates.

revyl device tap [flags]

Flag	Default	Description
`--target`		Element description (AI grounded)
`--x`	`0`	X coordinate (raw)
`--y`	`0`	Y coordinate (raw)
`-s`	`-1`	Session index
`--json`	`false`	Output as JSON

Examples:

revyl device tap --target "Sign In button"
revyl device tap --x 540 --y 960

`revyl device double-tap`

Double-tap an element by description or coordinates.

revyl device double-tap [flags]

Flag	Default	Description
`--target`		Element description (AI grounded)
`--x`	`0`	X coordinate (raw)
`--y`	`0`	Y coordinate (raw)
`-s`	`-1`	Session index
`--json`	`false`	Output as JSON

`revyl device long-press`

Long press an element with configurable duration.

revyl device long-press [flags]

Flag	Default	Description
`--target`		Element description (AI grounded)
`--x`	`0`	X coordinate (raw)
`--y`	`0`	Y coordinate (raw)
`--duration`	`1500`	Press duration in milliseconds
`-s`	`-1`	Session index
`--json`	`false`	Output as JSON

Example:

revyl device long-press --target "message bubble" --duration 2000

`revyl device type`

Type text into an element. Taps the target first, then inputs the text.

revyl device type [flags]

Flag	Default	Description
`--target`		Element description (AI grounded)
`--x`	`0`	X coordinate (raw)
`--y`	`0`	Y coordinate (raw)
`--text`		Text to type (required)
`--clear-first`	`true`	Clear the field before typing
`-s`	`-1`	Session index
`--json`	`false`	Output as JSON

Examples:

revyl device type --target "email input field" --text "[email protected]"
revyl device type --x 540 --y 400 --text "hello" --clear-first=false

`revyl device swipe`

Swipe from an element in a direction.

revyl device swipe [flags]

Flag	Default	Description
`--target`		Element description (AI grounded)
`--x`	`0`	X coordinate (raw)
`--y`	`0`	Y coordinate (raw)
`--direction`		Direction: `up`, `down`, `left`, `right` (required)
`--duration`	`500`	Swipe duration in milliseconds
`-s`	`-1`	Session index
`--json`	`false`	Output as JSON

Swipe direction semantics:

Direction	Finger Movement	Content Effect
`up`	Finger moves up	Scrolls content down (reveals below)
`down`	Finger moves down	Scrolls content up (reveals above)
`left`	Finger moves left	Scrolls content right
`right`	Finger moves right	Scrolls content left

Example:

revyl device swipe --target "product list" --direction down --duration 1000

`revyl device drag`

Drag from one point to another using raw coordinates.

revyl device drag [flags]

Flag	Default	Description
`--start-x`	`0`	Starting X coordinate
`--start-y`	`0`	Starting Y coordinate
`--end-x`	`0`	Ending X coordinate
`--end-y`	`0`	Ending Y coordinate
`-s`	`-1`	Session index
`--json`	`false`	Output as JSON

drag only supports raw coordinates, not AI grounding. Take a screenshot first and validate your start/end points before running the drag.

Example:

revyl device drag --start-x 100 --start-y 500 --end-x 100 --end-y 200

Vision

`revyl device screenshot`

Capture a screenshot of the device screen.

revyl device screenshot [flags]

Flag	Default	Description
`--out`		Output file path (e.g. `screen.png`)
`-s`	`-1`	Session index
`--json`	`false`	Output as JSON

Examples:

revyl device screenshot --out screen.png
revyl device screenshot -s 1 --out ~/Desktop/ios-screen.png

App Management

`revyl device install`

Install an app on the device from a remote URL.

revyl device install [flags]

Flag	Default	Description
`--app-url`		URL to download app from (required) — `.apk` or `.ipa`
`--bundle-id`		Bundle ID (optional, auto-detected from the binary)
`-s`	`-1`	Session index
`--json`	`false`	Output as JSON

Examples:

revyl device install --app-url "https://example.com/app.apk"
revyl device install --app-url "https://example.com/app.ipa" --bundle-id com.example.app

If you’ve already uploaded a build with revyl build upload, the MCP install_app tool also accepts a build_version_id so you don’t need to track URLs manually. See MCP Setup for details.

`revyl device launch`

Launch an installed app by bundle ID.

revyl device launch [flags]

Flag	Default	Description
`--bundle-id`		App bundle ID to launch (required)
`-s`	`-1`	Session index
`--json`	`false`	Output as JSON

Example:

revyl device launch --bundle-id com.example.app

MCP Tool Mapping

Every CLI device command has a corresponding MCP tool for AI agent integration:

CLI Command	MCP Tool
`device start`	`start_device_session`
`device stop`	`stop_device_session`
`device list`	`list_device_sessions`
`device use`	`switch_device_session`
`device info`	`get_session_info`
`device doctor`	`device_doctor`
`device tap`	`device_tap`
`device double-tap`	`device_double_tap`
`device long-press`	`device_long_press`
`device type`	`device_type`
`device swipe`	`device_swipe`
`device drag`	`device_drag`
`device screenshot`	`screenshot`
`device install`	`install_app`
`device launch`	`launch_app`

See MCP Server Setup for configuration and usage with AI coding tools.

Examples

Start a device, install an app, and interact

revyl device start --platform android --open
revyl device install --app-url "https://example.com/myapp.apk"
revyl device launch --bundle-id com.example.myapp
revyl device screenshot --out before.png
revyl device tap --target "Sign In button"
revyl device type --target "email field" --text "[email protected]"
revyl device type --target "password field" --text "secret123"
revyl device tap --target "Log In"
revyl device screenshot --out after.png
revyl device stop

Multi-session testing

revyl device start --platform android    # Session 0
revyl device start --platform ios        # Session 1

# Interact with Android (session 0)
revyl device tap --target "Get Started" -s 0

# Interact with iOS (session 1)
revyl device tap --target "Get Started" -s 1

revyl device stop --all

Target an element before acting

revyl device screenshot --out before-submit.png
revyl device tap --target "Submit button"
revyl device screenshot --out after-submit.png

Troubleshooting

Device won’t start

Check authentication: revyl auth status
Run diagnostics: revyl device doctor
Verify your account has available device slots

”no active device session”

Sessions auto-terminate after the idle timeout (default 5 minutes). Start a new session with revyl device start.

Grounding can’t find the element

Take a screenshot to see what’s actually on screen: revyl device screenshot --out debug.png
Use more specific descriptions: "blue 'Next' button" instead of "button"
Fall back to raw coordinates with --x/--y when needed

Actions seem to miss their target

The device resolution may differ from what you expect. Capture a fresh screenshot and switch to raw --x/--y targeting for precise control.

Next Steps

MCP Server Setup

Connect device tools to your AI coding agent.

Interactive Mode

Build tests step-by-step with live device feedback.

Running Tests

Execute tests and workflows from the CLI.

Command Reference

Full reference for all CLI commands.

Getting Started

Tests

Builds

Workflows

Monitoring

Integrations

CLI

CI/CD

Device Automation

​Overview

​AI-Powered Grounding

​Multi-Session Support

​Common Flags

​Session Management

​revyl device start

​revyl device stop

​revyl device list

​revyl device use

​revyl device info

​revyl device doctor

​Device Actions

​revyl device tap

​revyl device double-tap

​revyl device long-press

​revyl device type

​revyl device swipe

​revyl device drag

​Vision

​revyl device screenshot

​App Management

​revyl device install

​revyl device launch

​MCP Tool Mapping

​Examples

​Start a device, install an app, and interact

​Multi-session testing

​Target an element before acting

​Troubleshooting

​Device won’t start

​”no active device session”

​Grounding can’t find the element

​Actions seem to miss their target

​Next Steps

MCP Server Setup

Interactive Mode

Running Tests

Command Reference

Overview

AI-Powered Grounding

Multi-Session Support

Common Flags

Session Management

`revyl device start`

`revyl device stop`

`revyl device list`

`revyl device use`

`revyl device info`

`revyl device doctor`

Device Actions

`revyl device tap`

`revyl device double-tap`

`revyl device long-press`

`revyl device type`

`revyl device swipe`

`revyl device drag`

Vision

`revyl device screenshot`

App Management

`revyl device install`

`revyl device launch`

MCP Tool Mapping

Examples

Start a device, install an app, and interact

Multi-session testing

Target an element before acting

Troubleshooting

Device won’t start

”no active device session”

Grounding can’t find the element

Actions seem to miss their target

Next Steps