Device quickstart

Build your app in the cloud, start an iOS simulator or Android emulator, and control it from your own tools. No Revyl test or AI agent is required.

Want to run your own app and verify a change? Use the mobile quickstart.

Before you start, install the Revyl CLI and authenticate with revyl auth login. Sessions and remote builds use your organization's cloud resources. Use test data and keep API keys and screenshots private.

Set up with an agent

Paste one prompt and your coding agent does the rest.

Copy setup promptPreview prompt

Setup prompt

Copy

Build this app remotely, run it on a Revyl cloud device, and capture evidence.

Read https://docs.revyl.com/infrastructure/quickstart.md and follow it. It's the current Revyl guide for this, so prefer it over anything you remember about Revyl.

Run `revyl init -y`. Create a Revyl app with `revyl app create --name <app-name> --platform ios`, or `android` if the app is Android only, and put its ID in that platform's recipe `app_id`. Build with `revyl build --remote --profile <profile> --platform ios`, naming the profile when the config has more than one. Start a session on that build with `revyl device start --platform ios` and take one `revyl device screenshot --out first-screen.png` of the first screen.

You're done when you've shown me a screenshot from the device and stopped the device.

Ask me before anything that needs my login or approval.

1. Build remotelyCopy Anchor Link

From your app's project directory, run revyl init once. Review the detected recipe and its Revyl app ID using the remote build setup, then run the command for your platform:

revyl build --remote --platform ios

The build runs on Revyl's cloud infrastructure and uploads the artifact to the Revyl branch named after your Git branch, which the upload creates if needed (Build branches). No local Xcode or Android SDK is needed. If more than one build profile matches, pass --profile <name>; an interactive terminal also lets you pick one. For unattended CI, follow the remote build configuration guide.

Already uploaded a build? Skip this step. iOS needs a simulator .app or zipped .app; Android needs a compatible .apk. For project setup, dependencies, and framework recipes, see Remote Builds and Framework Guides.

2. Start a device with your appCopy Anchor Link

Use the matching app_id from your project's .revyl/config.yaml:

revyl device start --platform ios --app-id YOUR_IOS_APP_ID

Revyl selects a default device and installs the default build of your Git branch when it has a usable build, otherwise of the app's default branch. If your build is on another branch, add --branch <name>. For the other build choices, see Run options. The command prints the session ID and a live viewer link. Keep the session ID for the next steps; use the viewer to watch the device.

The start waits until the device is ready, which takes longer when devices are queued. As soon as Revyl accepts it, the command names the session on stderr, and revyl device list shows that session as queued or starting, with no local index, until its device is ready; target it by session ID in the meantime.

For a repeatable CI run, select one exact build with --build-version-id instead of --app-id. A build ID is different from a remote build job ID. If you pass both, the build must belong to that app; otherwise device start names the app it belongs to and stops.

3. Control the device and capture evidenceCopy Anchor Link

Web sessionsCopy Anchor Link

Web sessions require a Web app and a URL or managed bundle build. Start the app's latest build, or create or reuse one from an HTTPS URL before starting:

revyl app create --name "My Web App" --platform web --json
revyl device start --platform web --app YOUR_WEB_APP_ID --json
revyl device start --platform web --app YOUR_WEB_APP_ID --url https://example.com/ --json
revyl device start --platform web --app YOUR_WEB_APP_ID --build-version-id YOUR_BUILD_ID --viewport 1280x800 --json

--app-id remains an alias for the app selection. --commit optionally identifies the URL build when used with --url. URLs cannot contain credentials, query strings, or fragments. No project input or local build is required. Managed Web builds run in the session's app container. Revyl verifies the bundle, starts its command (or a static server), and checks its health before opening Chrome. Runtime settings and secrets come from organization launch variables named by run.env_keys and run.secret_names; only the app process receives their values.

The default viewport is 1280x800 and the default Web idle timeout is 600 seconds, unless session configuration or --timeout overrides it.

While a Web session is running, organization members who can control it can click, scroll, type, and press Enter, Tab, Backspace, Escape, and the arrow keys in the live viewer. Each input is recorded as a Manual control step, and typed text is never written to the report. Viewers and shared report links get a view-only player. Drag and hover are not available in the viewer; use CLI or MCP actions for them.

Use the returned session_id for screenshots, navigation, taps, typing, reports, and stopping. Web screenshots include a local screen_token; grounded actions carry the matching observation token automatically. A stale target requires a fresh screenshot and target resolution. Do not automatically repeat an action reported as applied or uncertain.

For private text, use revyl device type --session-id YOUR_SESSION_ID --target "password field" --text-env PASSWORD_ENV_NAME. The value stays out of command arguments and CLI output; on Web, the target must be a password field. Web does not support phone-only actions such as app installation, Home, or pinch.

Phone sessionsCopy Anchor Link

Replace the placeholder with your session ID:

SESSION_ID="YOUR_SESSION_ID"
revyl device screenshot --session-id "$SESSION_ID" --out app.png
revyl device home --session-id "$SESSION_ID"
revyl device screenshot --session-id "$SESSION_ID" --out home.png

Inspect the screenshots to confirm the app opened and the home command changed the screen. Your harness owns the assertions; a saved screenshot alone does not prove a test passed. See the device command reference for taps, typing, app lifecycle, and other actions.

4. Stop the deviceCopy Anchor Link

revyl device stop --session-id "$SESSION_ID"

Always release the session your job created, including when a test fails. Do not stop every session in a shared organization.

Appium and MaestroCopy Anchor Link

This quickstart uses Revyl's native device commands. An unchanged Appium or Maestro suite needs a framework connection layer; a viewer URL is not an automation endpoint. The Appium driver and Maestro runner are source-installed integrations that run a native command subset against existing device sessions. Get them from RevylAI/appium-revyl-driver and RevylAI/maestro-revyl-driver. The Maestro runner embeds the Maestro runtime; it is not a plugin for stock maestro test. Neither provides standard UiAutomator2/XCUITest or full Maestro compatibility; each page lists the commands it supports.

Optional: a complete script for CICopy Anchor Link

The script below starts one device, opens Settings or an uploaded build, saves screenshots, and stops only that session on exit. It needs Bash and jq. It is a lifecycle smoke check, not an Appium or Maestro adapter.

Save the script as smoke.sh, then run bash smoke.sh ios or bash smoke.sh android. Add a platform-matching build ID as the second argument to open your own app instead of Settings.

The script sets a 600-second idle timeout as a fallback; an abrupt runner termination can still prevent its cleanup trap from running. Give CI jobs their own timeout, keep the returned session ID, and collect private screenshots even when a job fails. Review the images before treating them as visual proof.