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.
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 startInstall an app with revyl device installInteract using tap, type, swipe, and other action commandsStop 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
Session indices are stable — stopping session 0 does not renumber session 1. The first started session is automatically set as the active session. If the active session is stopped, the CLI switches to the lowest remaining index.
For detailed workflows (CLI, MCP, Python SDK), cross-client sync, and troubleshooting, see the Multi-Session Guide .
Common Flags These flags are shared across most device commands:
Flag Short Default Description --jsonfalseOutput results as JSON -s-1Session index to target (-1 = active session)
Session Management revyl device startProvision and start a new cloud device session.
revyl device start [flags]
Flag Default Description --platformiosPlatform: ios or android --timeout300Idle timeout in seconds --openfalseOpen the live viewer in your browser after the device is ready --app-idApp ID to resolve latest build from --app-urlDirect app artifact URL (.apk/.ipa/.zip) --build-version-idBuild version ID to install --app-linkDeep link to launch after app start --devicefalseInteractively select device model and OS version --device-modelTarget device model (e.g. "iPhone 16") --os-versionTarget OS version (e.g. "iOS 18.5") --jsonfalseOutput as JSON
Examples: revyl device start revyl device start --platform android --open --timeout 600 revyl device start --platform ios --device-model "iPhone 16" --os-version "iOS 18.5"
The response includes a viewer_url you can open in your browser to watch the device live.
revyl device stopStop one or all device sessions.
revyl device stop [flags]
Flag Default Description -s-1Session index to stop (-1 = active session) --allfalseStop all sessions --jsonfalseOutput 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 listList all active device sessions.
revyl device list [flags]
Flag Default Description --jsonfalseOutput as JSON
Output columns: # (index, * marks active), PLATFORM, STATUS, SESSION ID, UPTIME.
revyl device useSwitch the active session to a different index.
Example: revyl device use 2 # Make session 2 the active session
revyl device infoShow details about a device session: session ID, platform, viewer URL, and uptime.
revyl device info [flags]
Flag Default Description -s-1Session index (-1 = active session) --jsonfalseOutput as JSON
revyl device doctorRun diagnostics on auth, session health, worker reachability, and device connectivity.
revyl device doctor [flags]
Flag Default Description -s-1Session index (-1 = active session) --jsonfalseOutput as JSON
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 AIRaw 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 tapTap an element by description or coordinates.
Flag Default Description --targetElement description (AI grounded) --x0X coordinate (raw) --y0Y coordinate (raw) -s-1Session index --jsonfalseOutput as JSON
Examples: revyl device tap --target "Sign In button" revyl device tap --x 540 --y 960
revyl device double-tapDouble-tap an element by description or coordinates.
revyl device double-tap [flags]
Flag Default Description --targetElement description (AI grounded) --x0X coordinate (raw) --y0Y coordinate (raw) -s-1Session index --jsonfalseOutput as JSON
revyl device long-pressLong press an element with configurable duration.
revyl device long-press [flags]
Flag Default Description --targetElement description (AI grounded) --x0X coordinate (raw) --y0Y coordinate (raw) --duration1500Press duration in milliseconds -s-1Session index --jsonfalseOutput as JSON
Example: revyl device long-press --target "message bubble" --duration 2000
revyl device typeType text into an element. Taps the target first, then inputs the text.
revyl device type [flags]
Flag Default Description --targetElement description (AI grounded) --x0X coordinate (raw) --y0Y coordinate (raw) --textText to type (required) --clear-firsttrueClear the field before typing -s-1Session index --jsonfalseOutput 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 swipeSwipe from an element in a direction.
revyl device swipe [flags]
Flag Default Description --targetElement description (AI grounded) --x0X coordinate (raw) --y0Y coordinate (raw) --directionDirection: up, down, left, right (required) --duration500Swipe duration in milliseconds -s-1Session index --jsonfalseOutput as JSON
Swipe direction semantics: Direction Finger Movement Content Effect upFinger moves up Scrolls content down (reveals below) downFinger moves down Scrolls content up (reveals above) leftFinger moves left Scrolls content right rightFinger moves right Scrolls content left
Example: revyl device swipe --target "product list" --direction down --duration 1000
revyl device dragDrag from one point to another using raw coordinates.
revyl device drag [flags]
Flag Default Description --start-x0Starting X coordinate --start-y0Starting Y coordinate --end-x0Ending X coordinate --end-y0Ending Y coordinate -s-1Session index --jsonfalseOutput 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
revyl device pinchPinch or zoom an element.
revyl device pinch [flags]
Flag Default Description --targetElement description (AI grounded) --x0X coordinate (raw) --y0Y coordinate (raw) --scale2Zoom scale (>1 zooms in, <1 zooms out) --duration300Pinch duration in milliseconds -s-1Session index --jsonfalseOutput as JSON
Examples: revyl device pinch --target "map" --scale 1.5 revyl device pinch --target "photo" --scale 0.5 # Zoom out
revyl device clear-textClear text in an input element.
revyl device clear-text [flags]
Flag Default Description --targetElement description (AI grounded) --x0X coordinate (raw) --y0Y coordinate (raw) -s-1Session index --jsonfalseOutput as JSON
Example: revyl device clear-text --target "Search field"
Control Commands revyl device waitPause for a fixed duration.
revyl device wait [flags]
Flag Default Description --duration-ms1000Wait duration in milliseconds -s-1Session index --jsonfalseOutput as JSON
Example: revyl device wait --duration-ms 2000
revyl device backPress the Android back button.
revyl device back [flags]
Flag Default Description -s-1Session index --jsonfalseOutput as JSON
This command only works on Android devices. It will return an error on iOS.
revyl device keySend a non-printable key to the focused field.
Flag Default Description --keyKey to send: ENTER or BACKSPACE -s-1Session index --jsonfalseOutput as JSON
Examples: revyl device key --key ENTER revyl device key --key BACKSPACE
revyl device shakeTrigger a shake gesture on the device.
revyl device shake [flags]
Flag Default Description -s-1Session index --jsonfalseOutput as JSON
revyl device homeReturn to the device home screen.
revyl device home [flags]
Flag Default Description -s-1Session index --jsonfalseOutput as JSON
revyl device kill-appKill the installed app on the device.
revyl device kill-app [flags]
Flag Default Description -s-1Session index --jsonfalseOutput as JSON
revyl device open-appOpen a system app by name or bundle ID.
revyl device open-app [flags]
Flag Default Description --appApp name (e.g. settings, safari, chrome) or raw bundle ID (required) -s-1Session index --jsonfalseOutput as JSON
Examples: revyl device open-app --app settings revyl device open-app --app safari revyl device open-app --app com.google.chrome.ios
revyl device navigateOpen a URL or deep link on the device.
revyl device navigate [flags]
Flag Default Description --urlURL or deep link to open (required) -s-1Session index --jsonfalseOutput as JSON
Examples: revyl device navigate --url https://example.com revyl device navigate --url "myapp://settings/profile"
revyl device set-locationSet the device GPS coordinates.
revyl device set-location [flags]
Flag Default Description --lat0Latitude (-90 to 90) (required) --lon0Longitude (-180 to 180) (required) -s-1Session index --jsonfalseOutput as JSON
Example: revyl device set-location --lat 37.7749 --lon -122.4194
revyl device download-fileDownload a file to the device from a URL.
revyl device download-file [flags]
Flag Default Description --urlURL to download from (required) --filenameOptional destination filename on the device -s-1Session index --jsonfalseOutput as JSON
Example: revyl device download-file --url https://example.com/report.pdf --filename report.pdf
Vision revyl device screenshotCapture a screenshot of the device screen.
revyl device screenshot [flags]
Flag Default Description --outOutput file path (e.g. screen.png) -s-1Session index --jsonfalseOutput as JSON
Examples: revyl device screenshot --out screen.png revyl device screenshot -s 1 --out ~/Desktop/ios-screen.png
App Management revyl device installInstall an app on the device from a remote URL or a previously uploaded build.
revyl device install [flags]
Flag Default Description --app-urlURL to download app from (.apk or .ipa) --build-version-idBuild version ID from a previous upload; download URL is resolved automatically --bundle-idBundle ID (optional, auto-detected from the binary) -s-1Session index --jsonfalseOutput as JSON
Provide either --app-url or --build-version-id, not both.
Examples: revyl device install --app-url "https://example.com/app.apk" revyl device install --build-version-id bv_abc123 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, use --build-version-id so you don’t need to track URLs manually. The MCP install_app tool also accepts this flag. See MCP Setup for details. revyl device launchLaunch an installed app by bundle ID.
revyl device launch [flags]
Flag Default Description --bundle-idApp bundle ID to launch (required) -s-1Session index --jsonfalseOutput as JSON
Example: revyl device launch --bundle-id com.example.app
Live Steps Execute individual test steps against an active device session without creating a full test. These commands use the same AI-powered step execution engine used in revyl test run.
revyl device instructionRun one natural-language instruction step on the active device. The AI agent interprets the description and performs the necessary actions (tap, type, swipe, etc.) to complete it.
revyl device instruction < descriptio n > [flags]
Flag Default Description -s-1Session index --jsonfalseOutput as JSON
Examples: revyl device instruction "Open Settings and tap Wi-Fi" revyl device instruction "Log in with [email protected] and password secret123" revyl device instruction "Scroll down and tap the 'Save Changes' button"
revyl device validationRun one natural-language validation step. Asserts that a condition is true on the current screen.
revyl device validation < descriptio n > [flags]
Flag Default Description -s-1Session index --jsonfalseOutput as JSON
Examples: revyl device validation "Verify the Settings title is visible" revyl device validation "The inbox shows at least one unread message" revyl device validation "The price displayed is $9 .99"
Run one natural-language extract step. Pulls data from the current screen and returns it.
revyl device extract < descriptio n > [flags]
Flag Default Description --variable-nameOptional variable name to tag the extracted value for downstream use -s-1Session index --jsonfalseOutput as JSON
Examples: revyl device extract "Extract the visible account email" revyl device extract "Extract the total price" --variable-name total_price
revyl device code-executionRun a code execution step on the active device session.
Three modes:
By script ID: revyl device code-execution <script-id>From local file: revyl device code-execution --file ./script.py --runtime pythonInline code: revyl device code-execution --code "print('hello')" --runtime python
Modes 2 and 3 create an ephemeral script on the backend, execute it, then clean up.
revyl device code-execution [script-id] [flags]
Flag Default Description --fileRun code from a local file (creates ephemeral script) --codeRun inline code string (creates ephemeral script) --runtimeScript runtime for --file/--code: python, javascript, typescript, or bash -s-1Session index --jsonfalseOutput as JSON
Examples: revyl device code-execution script_abc123 revyl device code-execution --file ./tests/check_state.py --runtime python revyl device code-execution --code "console.log('ok')" --runtime javascript
Utilities revyl device reportView the report for the active device session, including steps executed, actions taken, video URL, and status.
revyl device report [flags]
Flag Default Description -s-1Session index --jsonfalseOutput as JSON
revyl device targetsList available device models and OS versions for each platform.
revyl device targets [flags]
Flag Default Description --platformFilter to a specific platform: ios or android --jsonfalseOutput as JSON
Examples: revyl device targets revyl device targets --platform ios
revyl device historyShow recent device session history from the server.
revyl device history [flags]
Flag Default Description --limit20Maximum number of sessions to show --jsonfalseOutput as JSON
Every CLI device command has a corresponding MCP tool for AI agent integration:
CLI Command MCP Tool device startstart_device_sessiondevice stopstop_device_sessiondevice listlist_device_sessionsdevice useswitch_device_sessiondevice infoget_session_infodevice doctordevice_doctordevice tapdevice_tapdevice double-tapdevice_double_tapdevice long-pressdevice_long_pressdevice typedevice_typedevice swipedevice_swipedevice dragdevice_dragdevice pinchdevice_pinchdevice clear-textdevice_clear_textdevice screenshotscreenshotdevice installinstall_appdevice launchlaunch_appdevice waitdevice_waitdevice backdevice_backdevice keydevice_keydevice shakedevice_shakedevice homedevice_go_homedevice kill-appdevice_kill_appdevice open-appdevice_open_appdevice navigatedevice_navigatedevice set-locationdevice_set_locationdevice download-filedevice_download_filedevice instructiondevice_instructiondevice validationdevice_validationdevice extractdevice_extractdevice code-executiondevice_code_executiondevice reportget_session_report
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
Use live steps for a complex flow revyl device start --platform ios --open revyl device install --app-url "https://example.com/myapp.ipa" revyl device instruction "Log in with [email protected] and navigate to the Settings page" revyl device validation "The Settings page header is visible" revyl device extract "Extract the current plan name" --variable-name plan 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
Device Quickstart Task-oriented onboarding with your first device session.
MCP Server Setup Connect device tools to your AI coding agent.
Dev Loop Guide Run focused local verification loops with cloud devices.
Command Reference Full reference for all CLI commands.
