### Quickstart Device Control with Python SDK

Source: https://github.com/revylai/revyl-cli/blob/main/docs/device-sdk/index.md

A basic example demonstrating how to start a device, perform actions like tapping and typing, and capture a screenshot using the DeviceClient.

```python
from revyl import DeviceClient

with DeviceClient.start(platform="ios") as device:
    device.tap(target="Get Started")
    device.type_text(target="Email field", text="user@test.com")
    device.screenshot(out="result.png")
```

--------------------------------

### Run Quick Start Example

Source: https://github.com/revylai/revyl-cli/blob/main/examples/sdk/README.md

Execute the quick start script to perform basic device interactions like starting a device, tapping, and taking a screenshot. The `--open` flag automatically opens the session in the browser.

```python
python examples/sdk/quick_start.py --open
```

--------------------------------

### Revyl CLI Setup and Initialization

Source: https://github.com/revylai/revyl-cli/blob/main/docs/getting-started.md

Run these commands to check your CLI setup, log in with your API key, initialize your project, and install agent skills.

```bash
revyl doctor
revyl auth login
cd your-app && revyl init
revyl skill install --force
```

--------------------------------

### Install and Initialize Revyl CLI

Source: https://github.com/revylai/revyl-cli/blob/main/docs/README.md

Follow these steps to install the Revyl CLI, check your environment, authenticate, initialize your project, install agent skills, build and upload, and start the development loop.

```bash
# 1. Install
curl -fsSL https://revyl.com/install.sh | sh

# 2. Check your environment
revyl doctor

# 3. Authenticate
revyl auth login

# 4. Initialize your project
cd your-app && revyl init

# 5. Install agent skills
# Available: revyl-cli-dev-loop (dev loop), revyl-cli-create (test authoring)
revyl skill install --force

# 6. Build and upload
revyl build upload

# 7. Start the dev loop
revyl dev
```

--------------------------------

### Install App from URL using Context Manager

Source: https://github.com/revylai/revyl-cli/blob/main/docs/device-sdk/scripting.md

Start a device session for Android and install an application directly from a URL using the context manager.

```python
APP_URL = "https://example.com/your-app.apk"

with DeviceClient.start(platform="android", app_url=APP_URL) as device:
    device.tap(target="Sign Up")
```

--------------------------------

### Full Python Example: Session Management and Streaming

Source: https://github.com/revylai/revyl-cli/blob/main/docs/device-sdk/streaming.md

A complete Python example demonstrating starting a device session, waiting for the stream URL, performing actions on the device, and noting that the stream remains live until the session ends.

```python
from revyl import DeviceClient

APP_URL = "https://example.com/your-app.tar.gz"

with DeviceClient.start(platform="ios", app_url=APP_URL) as device:
    whep_url = device.wait_for_stream(timeout=30)

    if whep_url:
        print(f"Live stream: {whep_url}")
        # Pass this URL to your dashboard, CI viewer, Slack bot, etc.

    device.tap("Login button")
    device.screenshot("after_login.png")

    # Stream stays live until the session ends

```

--------------------------------

### Revyl CLI Quick Start

Source: https://github.com/revylai/revyl-cli/blob/main/README.md

Initialize your project, install agent skills, upload a development binary, and launch the interactive development mode.

```bash
revyl doctor                            # Check CLI, auth, connectivity
```

```bash
revyl auth login                        # Browser-based login (if not already authed)
```

```bash
revyl init                              # Guided wizard: build system, apps
```

```bash
revyl skill install --force             # Install recommended agent skills
```

```bash
revyl build upload                      # Build and upload a dev binary
```

```bash
revyl dev                               # Launch TUI: live device + hot reload
```

--------------------------------

### Revyl CLI Quick Start Workflow

Source: https://github.com/revylai/revyl-cli/blob/main/docs/cli-index.md

A sequence of commands to quickly get started with Revyl CLI, including installation, environment check, authentication, project initialization, building, uploading, and starting the development loop.

```bash
# 1. Install the CLI
curl -fsSL https://revyl.com/install.sh | sh

# 2. Check your environment
revyl doctor

# 3. Authenticate
revyl auth login

# 4. Initialize your project
cd your-app
revyl init

# 5. Build and upload a dev binary
revyl build upload

# 6. Start the dev loop
revyl dev
```

--------------------------------

### Start Revyl Dev Loop

Source: https://github.com/revylai/revyl-cli/blob/main/docs/developer_loop/dev-loop.md

Initiates the development loop, starting the local dev server, creating a Revyl relay, installing the dev build on a cloud device, and opening the session in the browser. Use `--debug` for detailed diagnostics.

```bash
revyl dev
```

--------------------------------

### Fire-and-Forget Device Session Start

Source: https://github.com/revylai/revyl-cli/blob/main/docs/SDK.md

Start a device session without blocking, allowing for parallel setup. Use `wait_for_device_ready()` to block when needed and `stop_session()` to end the session.

```python
# For advanced users who want to do parallel setup work.
device = DeviceClient.start(platform="ios", app_url=url, wait_for_ready=False)
# ... do other setup ...
device.wait_for_device_ready()   # block when you need the device
device.screenshot(out="screen.png")
device.stop_session()
```

--------------------------------

### Run Quick Start with Custom App

Source: https://github.com/revylai/revyl-cli/blob/main/examples/sdk/README.md

Use the quick start script with your own application build by providing the app URL. The `--open` flag opens the session in the browser.

```python
python examples/sdk/quick_start.py --open --app-url https://your-host.com/app.apk
```

--------------------------------

### Install and Launch App (CLI)

Source: https://github.com/revylai/revyl-cli/blob/main/docs/device/quickstart.md

Install an application from a direct URL and launch it by its bundle ID using the Revyl CLI.

```bash
revyl device install --app-url "https://example.com/app.apk"
```

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

--------------------------------

### Start Device with Explicit Platform

Source: https://github.com/revylai/revyl-cli/blob/main/docs/device/troubleshooting.md

Retry starting a device session by explicitly specifying the platform if the initial attempt fails.

```bash
revyl device start --platform ios
```

--------------------------------

### Start Device Session with DeviceClient

Source: https://github.com/revylai/revyl-cli/blob/main/docs/SDK.md

Start a device session using DeviceClient. The `start` method blocks until the device is API-ready by default. The context manager ensures the session is stopped automatically.

```python
from revyl import DeviceClient

# start() blocks until the device is API-ready (default).
# Report URL auto-prints when the session closes.
with DeviceClient.start(platform="ios", app_url=url) as device:
    device.screenshot(out="screen.png")
    device.tap(target="Login button")
    device.type_text(target="Email", text="user@test.com")
```

```python
from revyl import DeviceClient

with DeviceClient.start(platform="android") as device:
    device.tap(target="Get Started")
    device.swipe(target="feed", direction="down")
# Session is stopped automatically on exit; report URL is printed.
```

--------------------------------

### Install Expo if Missing

Source: https://github.com/revylai/revyl-cli/blob/main/docs/developer_loop/dev-setup.md

If the Expo provider fails because `expo` is not listed in the local `package.json`, install it using `npx expo install`.

```bash
npx expo install expo
```

--------------------------------

### Prompt Example: CLI Dev-Loop

Source: https://github.com/revylai/revyl-cli/blob/main/docs/integrations/skills.md

Example prompt for using the `revyl-cli-dev-loop` skill. It outlines the steps for detecting the app stack, starting the dev loop, and verifying with a screenshot.

```text
Use the revyl-cli-dev-loop skill. Detect the app stack, start or attach to the Revyl dev loop, keep it running after Dev loop ready, and verify with revyl device screenshot before changing strategy.
```

--------------------------------

### CLI Workflow for Multi-Session Management

Source: https://github.com/revylai/revyl-cli/blob/main/docs/device-sdk/multi-session.md

A comprehensive CLI workflow showing how to start, install apps on, interact with, and tear down multiple device sessions.

```bash
# 1. Start two devices
revyl device start --platform android    # session 0
revyl device start --platform ios        # session 1

# 2. Install an app on each
revyl device install --app-url "https://example.com/app.apk" -s 0
revyl device install --app-url "https://example.com/app.ipa" -s 1

# 3. Interact with each device using -s
revyl device tap --target "Get Started" -s 0
revyl device tap --target "Get Started" -s 1

revyl device type --target "Email field" --text "user@test.com" -s 0
revyl device type --target "Email field" --text "user@test.com" -s 1

# 4. Take screenshots from each
revyl device screenshot --out android-home.png -s 0
revyl device screenshot --out ios-home.png -s 1

# 5. Tear down
revyl device stop --all
```

--------------------------------

### Install and Launch App (Python SDK)

Source: https://github.com/revylai/revyl-cli/blob/main/docs/device/quickstart.md

Programmatically install an app from a URL and launch it by bundle ID using the Revyl Python SDK.

```python
device.install_app(app_url="https://example.com/app.apk")
device.launch_app(bundle_id="com.example.app")
```

--------------------------------

### Revyl CLI Project Initialization

Source: https://github.com/revylai/revyl-cli/blob/main/docs/COMMANDS.md

Initialize a new Revyl project. The interactive wizard guides through setup, while flags allow for non-interactive configuration, specifying providers, linking projects, re-running detection, overwriting existing files, and customizing hot-reloading schemes.

```bash
revyl init
```

```bash
revyl init -y
```

```bash
revyl init --provider expo
```

```bash
revyl init --project ID
```

```bash
revyl init --detect
```

```bash
revyl init --force
```

```bash
revyl init --hotreload-app-scheme myapp
```

```bash
revyl init --xcode-scheme ios-dev=MyAppDev
```

--------------------------------

### Example config.yaml

Source: https://github.com/revylai/revyl-cli/blob/main/docs/CONFIGURATION.md

A comprehensive example of a `config.yaml` file, demonstrating project name, build system configuration (Expo), platform-specific build commands, hot reload settings, and default options.

```yaml
project:
  name: "my-app"

build:
  system: Expo
  command: "npx --yes eas-cli build --platform ios --profile development --local --output build/app.tar.gz"
  output: "build/app.tar.gz"
  no_build: false

  platforms:
    ios-dev:
      command: "npx --yes eas-cli build --platform ios --profile development --local --output build/dev-ios.tar.gz"
      output: "build/dev-ios.tar.gz"
      app_id: "uuid-of-ios-dev-app"
      setup: "npm ci"
      scheme: "MyApp"
    ios-ci:
      command: "npx --yes eas-cli build --platform ios --profile preview --local --output build/ci-ios.tar.gz"
      output: "build/ci-ios.tar.gz"
      app_id: "uuid-of-ios-ci-app"
    android-dev:
      command: "npx --yes eas-cli build --platform android --profile development --local --output build/dev-android.apk"
      output: "build/dev-android.apk"
      app_id: "uuid-of-android-dev-app"

hotreload:
  default: expo
  providers:
    expo:
      app_scheme: "my-app"
      port: 8081
      platform_keys:
        ios: ios-dev
        android: android-dev

defaults:
  open_browser: true
  timeout: 1800

last_synced_at: "2026-02-10T14:30:00Z"  # Auto-updated on sync operations

```

--------------------------------

### Start Dev Loop with Context and Launch Variables

Source: https://github.com/revylai/revyl-cli/blob/main/skills/revyl-cli-auth-bypass-expo/SKILL.md

Start a fresh development loop with a specific context and attach the necessary launch variables. Ensure the dev session is new if reusing an old one.

```bash
# Start a fresh dev loop with the launch vars attached.
export REVYL_CONTEXT="${USER:-agent}-expo-auth-$$"
revyl dev --context "$REVYL_CONTEXT" --no-build \
  --launch-var REVYL_AUTH_BYPASS_ENABLED \
  --launch-var REVYL_AUTH_BYPASS_TOKEN
```

--------------------------------

### Start Device with Launch Variable

Source: https://github.com/revylai/revyl-cli/blob/main/docs/COMMANDS.md

Starts a raw device session and applies a global launch variable. Multiple --launch-var flags can be used.

```bash
revyl device start --platform ios --launch-var API_URL
```

--------------------------------

### Start Device Session (CLI)

Source: https://github.com/revylai/revyl-cli/blob/main/docs/device/quickstart.md

Start a new device session with a specified platform and timeout using the Revyl CLI.

```bash
revyl device start --platform ios --timeout 600
```

```bash
revyl device info
```

--------------------------------

### Start Development Loop for Specific Platform

Source: https://github.com/revylai/revyl-cli/blob/main/skills/revyl-cli-dev-loop/SKILL.md

Explicitly start the development loop for a specific platform like iOS or Android.

```bash
revyl dev --platform ios
```

```bash
revyl dev --platform android
```

--------------------------------

### Basic Python SDK Usage

Source: https://github.com/revylai/revyl-cli/blob/main/python/README.md

Use the DeviceClient from the Revyl Python SDK to interact with a mobile device. This example demonstrates starting an iOS device, tapping a button, typing text, and taking a screenshot.

```python
from revyl import DeviceClient

with DeviceClient.start(platform="ios") as device:
    device.tap(target="Login button")
    device.type_text(target="Email", text="user@example.com")
    device.screenshot(out="after-login.png")
```

--------------------------------

### Install Revyl CLI via uv

Source: https://github.com/revylai/revyl-cli/blob/main/docs/cli-index.md

Install the Revyl CLI using the uv tool.

```bash
uv tool install revyl
```

--------------------------------

### Quick Start: Revyl CLI Commands

Source: https://github.com/revylai/revyl-cli/blob/main/examples/yaml-tests/README.md

Basic commands to initialize a project, create, validate, push, and run tests.

```bash
revyl init                          # creates .revyl/config.yaml
revyl test create login-flow        # creates .revyl/tests/login-flow.yaml
# edit the YAML file
revyl test validate                 # check syntax
revyl test push                     # push to Revyl
revyl test run login-flow           # run it
```

--------------------------------

### Install Revyl SDK

Source: https://github.com/revylai/revyl-cli/blob/main/docs/device-sdk/index.md

Install the Revyl SDK using pip. The SDK automatically detects the CLI if installed via Homebrew.

```bash
pip install revyl[sdk]
```

--------------------------------

### Install Revyl Python SDK

Source: https://github.com/revylai/revyl-cli/blob/main/python/README.md

Install the Python SDK for Revyl, which includes the CLI. The SDK is also included in the base package, so `pip install revyl` also works.

```bash
pip install revyl[sdk]                  # Python SDK (includes CLI)
```

--------------------------------

### Run Checkout Flow Example

Source: https://github.com/revylai/revyl-cli/blob/main/examples/sdk/README.md

Run the checkout flow example to simulate a full e-commerce checkout process with validation at each stage. Use the `--open` flag to view the session in the browser.

```python
python examples/sdk/checkout_flow.py --open
```

--------------------------------

### DeviceClient.start

Source: https://github.com/revylai/revyl-cli/blob/main/docs/device-sdk/reference.md

Starts a device session and returns a connected client. By default, it blocks until the device is API-ready.

```APIDOC
## DeviceClient.start(platform, ..., wait_for_ready=True, ready_timeout=60, auto_report=True) -> DeviceClient

Class method. Start a device session and return a connected client.

By default, blocks until the device is API-ready. Pass `wait_for_ready=False` for fire-and-forget provisioning.

### Parameters
- `platform` (str) - Required - "ios" or "android"
- `timeout` (Optional[int]) - Idle timeout in seconds
- `open_viewer` (bool) - Open the live viewer in the browser
- `app_id` (Optional[str]) - Revyl app ID to preinstall
- `build_version_id` (Optional[str]) - Specific build version to install
- `app_url` (Optional[str]) - URL to an `.ipa` or `.apk` to preinstall
- `app_link` (Optional[str]) - Deep link to open after launch
- `device_model` (Optional[str]) - Target device model (e.g. "iPhone 16"). Must be paired with `os_version`.
- `os_version` (Optional[str]) - Target OS version (e.g. "iOS 18.5"). Must be paired with `device_model`.
- `cli` (Optional[RevylCLI]) - Custom CLI instance
- `wait_for_ready` (bool) - Block until device is API-ready (default `True`). Set `False` for fire-and-forget.
- `ready_timeout` (float) - Max seconds to wait for readiness when `wait_for_ready=True` (default `60`).
- `auto_report` (bool) - Auto-print report/video URLs on `close()` (default `True`).
- `verbose` (bool) - Show animated spinner during provisioning (default `True`). Set `False` for CI.
```

--------------------------------

### Install Revyl Python SDK

Source: https://github.com/revylai/revyl-cli/blob/main/docs/device-sdk/scripting.md

Install the Revyl Python SDK, which includes the CLI. Ensure you are logged in via `revyl auth login` before running scripts.

```bash
pip install revyl[sdk]
revyl auth login
```

--------------------------------

### Prompt Example: CLI Create

Source: https://github.com/revylai/revyl-cli/blob/main/docs/integrations/skills.md

Example prompt for using the `revyl-cli-create` skill to generate a smoke test from a given flow, validate it, push it, and run it.

```text
Use the revyl-cli-create skill. Create a checkout smoke test from this flow, validate it, push it, and run it once.
```

--------------------------------

### Start a Revyl Device

Source: https://github.com/revylai/revyl-cli/blob/main/examples/pr-review/agent-playbook.md

Starts a mobile device for testing. Ensure the REVYL_APP_ID environment variable is set.

```bash
revyl device start --platform ios --app-id $REVYL_APP_ID --json
```

--------------------------------

### Start Expo Dev-Client with Launch Variables

Source: https://github.com/revylai/revyl-cli/blob/main/skills/revyl-cli-auth-bypass-expo/SKILL.md

Start the Expo dev-client session with the specified launch variables before opening the auth link. The `--no-build` flag can speed up development loops.

```bash
revyl dev --no-build \
  --launch-var REVYL_AUTH_BYPASS_ENABLED \
  --launch-var REVYL_AUTH_BYPASS_TOKEN
```

--------------------------------

### Start Development Mode

Source: https://github.com/revylai/revyl-cli/blob/main/docs/COMMANDS.md

Automatically picks a branch-matched build if available. If not, it falls back to the latest build and issues a warning.

```bash
revyl dev                                     # Auto-picks branch-matched build
```

--------------------------------

### Start Development Loop

Source: https://github.com/revylai/revyl-cli/blob/main/docs/COMMANDS.md

Starts a local development loop with hot reloading and live device connection. Defaults to iOS platform. Use flags to specify platform, context, or disable automatic browser opening.

```bash
revyl dev                              # Start hot reload + live device (defaults to iOS)
revyl dev --platform android           # Explicit platform
revyl dev --context ios-main           # Named context for parallel loops
revyl dev --no-open                    # SSH/headless: keep device running but don't open browser
revyl dev --platform ios --build       # Force a fresh dev build before start
revyl dev --app-id <app-id>            # Use explicit app override
revyl dev --build-version-id <id>      # Use explicit build override
revyl dev --platform-key ios-dev       # Use explicit platform key
revyl dev --force-hot-reload           # Diagnostic launch after Expo relay transport
revyl dev --no-build --tunnel "<expo-dev-client-link>"  # Use an existing Expo tunnel/deep link
```

--------------------------------

### CLI in CI: Install and Run Revyl Commands

Source: https://github.com/revylai/revyl-cli/blob/main/docs/ci-cd.md

Installs the Revyl CLI and sets up the environment variables for API key and PATH. Useful for any CI environment.

```bash
curl -fsSL https://revyl.com/install.sh | sh
export PATH="$HOME/.revyl/bin:$PATH"
export REVYL_API_KEY=${{ secrets.REVYL_API_KEY }}

revyl test run login-flow --no-wait --json    # Queue and exit immediately
revyl workflow run smoke-tests --no-wait      # Queue a workflow
```

--------------------------------

### List, Install, and Refresh Skills

Source: https://github.com/revylai/revyl-cli/blob/main/docs/integrations/skills.md

Use these commands to manage your AI agent's skills. `list` shows available skills, `install` adds them, and `--force` ensures the latest version.

```bash
revyl skill list
```

```bash
revyl skill install --force
```

```bash
revyl skill install --global --force
```

--------------------------------

### Start Device Session with DeviceClient

Source: https://github.com/revylai/revyl-cli/blob/main/docs/device-sdk/reference.md

Start a device session using DeviceClient as a context manager. The session automatically stops and prints a report URL upon exiting the block.

```python
from revyl import DeviceClient

# start() blocks until the device is API-ready (default).
# Report URL auto-prints when the session closes.
with DeviceClient.start(platform="ios", app_url=url) as device:
    device.screenshot(out="screen.png")
    device.tap(target="Login button")
    device.type_text(target="Email", text="user@test.com")
```

--------------------------------

### Global Skill Installation

Source: https://github.com/revylai/revyl-cli/blob/main/docs/integrations/skills.md

Install skills at the user level for use across all projects. Use the `--global` flag for user-wide availability.

```bash
revyl skill install --global --force
```

```bash
revyl skill install --global --cursor --force
```

--------------------------------

### install_app

Source: https://github.com/revylai/revyl-cli/blob/main/docs/device-sdk/reference.md

Installs an application on the device. Supports installation from a URL (IPA or APK) or a previously uploaded build version. Requires either `app_url` or `build_version_id`.

```APIDOC
## install_app(app_url=None, build_version_id=None, bundle_id=None, session_index=None)

### Description
Install an app from a URL (`.ipa` or `.apk`) or a previously uploaded build version. Provide exactly one of `app_url` or `build_version_id`.

### Parameters
#### Path Parameters
- **app_url** (string) - Optional - The URL of the application package (.ipa or .apk).
- **build_version_id** (string) - Optional - The ID of a previously uploaded build version.
- **bundle_id** (string) - Optional - The bundle ID of the app to install.
- **session_index** (int) - Optional - The index of the session to target.
```

--------------------------------

### Example Bazel Build Configuration

Source: https://github.com/revylai/revyl-cli/blob/main/docs/developer_loop/dev-setup.md

Defines build commands and expected output paths for iOS and Android platforms using Bazel.

```yaml
build:
  system: Bazel
  platforms:
    ios:
      command: "bazel build //ios:MyApp -c dbg"
      output: "bazel-bin/ios/MyApp.app"
    android:
      command: "bazel build //android:app -c dbg"
      output: "bazel-bin/android/app.apk"
```

--------------------------------

### Start Expo Dev Client

Source: https://github.com/revylai/revyl-cli/blob/main/internal/hotreload/testdata/expo_manifests/README.md

Use this command to start an Expo development client for a specific app directory and port. Ensure you are in the repository root.

```sh
APP_DIR=internal-apps/bug-bazaar
PORT=19081
cd "$APP_DIR"
npx expo start --dev-client --localhost --port "$PORT"
```

--------------------------------

### Revyl Project Structure Example

Source: https://github.com/revylai/revyl-cli/blob/main/examples/yaml-tests/README.md

Illustrates the typical directory structure for a Revyl project, including configuration and test files.

```tree
your-app/
  .revyl/
    config.yaml              # project config (see config.yaml example)
    tests/
      login-flow.yaml        # one file per test
      checkout.yaml
```

--------------------------------

### Start Development Server

Source: https://github.com/revylai/revyl-cli/blob/main/docs/developer_loop/dev-setup.md

After manually adding the hotreload config in older CLI versions, use this command to start the development server for iOS.

```bash
revyl dev --platform ios
```

--------------------------------

### Shell Completion Setup

Source: https://github.com/revylai/revyl-cli/blob/main/docs/COMMANDS.md

Instructions for setting up shell completion for Revyl CLI in Bash, Zsh, Fish, and PowerShell.

```bash
# Bash (add to ~/.bashrc)
source <(revyl completion bash)
```

```bash
# Zsh (add to ~/.zshrc)
source <(revyl completion zsh)
```

```bash
# Fish
revyl completion fish | source
```

```bash
# PowerShell
revyl completion powershell | Out-String | Invoke-Expression
```

--------------------------------

### Start MCP Server for AI Agent Integration

Source: https://github.com/revylai/revyl-cli/blob/main/docs/COMMANDS.md

These commands start the MCP server with different profiles, each offering a varying number of composite tools for AI agent integration. The 'core' profile is recommended for development loops and test creation, while 'full' includes additional management tools.

```bash
revyl mcp serve
```

```bash
revyl mcp serve --profile core
```

```bash
revyl mcp serve --profile full
```

--------------------------------

### Example Prompts for Agent Skills

Source: https://github.com/revylai/revyl-cli/blob/main/README.md

Illustrative prompts demonstrating how to invoke specific agent skills for different tasks. These examples show the expected phrasing to activate skills like dev loop, test creation, and auth bypass.

```text
Use the revyl-cli-dev-loop skill. Detect the app stack, start or attach to the Revyl dev loop, keep it running after Dev loop ready, and verify with revyl device screenshot before changing strategy.
```

```text
Use the revyl-cli-create skill. Create a checkout smoke test from this flow, validate it, push it, and run it once.
```

```text
Use the revyl-cli-auth-bypass skill. Set up test-only auth bypass for this app and verify valid and rejected links on a Revyl device.
```

--------------------------------

### Initial Setup: Clone and Sync

Source: https://github.com/revylai/revyl-cli/blob/main/docs/tests/syncing-tests.md

Commands for setting up a project after cloning, including logging in, bootstrapping configuration mappings, and verifying test linkage.

```bash
revyl auth login
```

```bash
revyl sync --bootstrap              # Rebuild config mappings from _meta.remote_id values
```

```bash
revyl test list                     # Verify everything is linked
```

--------------------------------

### Upload Build and Preview

Source: https://github.com/revylai/revyl-cli/blob/main/docs/COMMANDS.md

Build and upload a new version of your application. Use the `--dry-run` flag to preview the upload process without actually performing it.

```bash
revyl build upload                       # Build and upload (--dry-run to preview)
```

--------------------------------

### Run Bug Detection Example

Source: https://github.com/revylai/revyl-cli/blob/main/examples/sdk/README.md

Execute the bug detection example to demonstrate catching a known cart bug using SDK's `extract` and `validation` features. The `--open` flag is used to open the session.

```python
python examples/sdk/bug_detection.py --open
```

--------------------------------

### Install Revyl CLI and Run Workflow

Source: https://github.com/revylai/revyl-cli/blob/main/examples/ci-generic/README.md

Install the Revyl CLI using curl and execute a workflow. Ensure the REVYL_API_KEY environment variable is set. Exit codes 0 for pass and 1 for fail are standard.

```bash
curl -fsSL https://revyl.com/install.sh | sh
export REVYL_API_KEY="$YOUR_SECRET"
revyl workflow run <workflow-name>
```

--------------------------------

### Verify Revyl Installation and MCP Server

Source: https://github.com/revylai/revyl-cli/blob/main/docs/integrations/mcp-setup.md

Check your authentication status and start the MCP server. Press Ctrl+C to stop the server.

```bash
revyl auth status   # Should show "Authenticated"
```

```bash
revyl mcp serve     # Should start the MCP server (Ctrl+C to stop)
```

--------------------------------

### Create and Insert Scripts

Source: https://github.com/revylai/revyl-cli/blob/main/skills/revyl-cli-create/SKILL.md

Create reusable scripts for setup, seeding, or assertions. Use `script insert` to add them to your test flow.

```bash
revyl script create seed-user --file scripts/seed_user.py --runtime python
```

```bash
revyl script insert seed-user
```

```bash
revyl script usage seed-user
```

--------------------------------

### GitLab CI: Run Revyl Workflow

Source: https://github.com/revylai/revyl-cli/blob/main/docs/ci-cd.md

Example of setting up a GitLab CI job to install the Revyl CLI and run a workflow. The API key is passed as an environment variable.

```yaml
test:
  script:
    - curl -fsSL https://revyl.com/install.sh | sh
    - export PATH="$HOME/.revyl/bin:$PATH"
    - revyl workflow run smoke-tests
  variables:
    REVYL_API_KEY: $REVYL_API_KEY
```

--------------------------------

### Get Stream URL with Python SDK

Source: https://github.com/revylai/revyl-cli/blob/main/docs/device-sdk/streaming.md

Obtain the WHEP stream URL for an active device session using the Revyl Python SDK. The stream URL becomes available a few seconds after the session starts.

```python
from revyl import DeviceClient

with DeviceClient.start(platform="ios", app_url="...") as device:
    whep_url = device.wait_for_stream(timeout=30)
    print(whep_url)
    # https://customer-xxx.cloudflarestream.com/<id>/webRTC/play
```

--------------------------------

### Start a Cloud Device Session

Source: https://github.com/revylai/revyl-cli/blob/main/docs/COMMANDS.md

Initiate a new cloud device session. Options include specifying platform, opening the viewer, using a pre-installed app, applying launch variables, selecting a named device preset, or specifying model and OS version.

```bash
revyl device start
```

```bash
revyl device start --platform android --open
```

```bash
revyl device start --platform ios --app-url https://example.com/app.ipa
```

```bash
revyl device start --platform ios --launch-var API_URL --launch-var DEBUG
```

```bash
revyl device start --device-name revyl-ios-iphone
```

```bash
revyl device start --device-model "iPhone 16" --os-version "iOS 18.5"
```

--------------------------------

### Create SDK 55 Expo App

Source: https://github.com/revylai/revyl-cli/blob/main/internal/hotreload/testdata/expo_manifests/README.md

Create a temporary Expo app using the SDK 55 blank template. This is useful for testing or refreshing SDK 55 fixtures. It installs dependencies and starts the development server.

```sh
tmpapp=$(mktemp -d)
cd "$tmpapp"
npx create-expo-app@latest app --template expo-template-blank@sdk-55 --no-install
cd app
npm install --ignore-scripts --no-audit --no-fund
npx expo start --dev-client --localhost --port 19085
```

--------------------------------

### DeviceClient.start

Source: https://github.com/revylai/revyl-cli/blob/main/docs/SDK.md

Starts a device session and returns a connected client. By default, it blocks until the device is API-ready. You can disable this behavior by setting `wait_for_ready=False` for fire-and-forget provisioning.

```APIDOC
## DeviceClient.start(platform, ..., wait_for_ready=True, ready_timeout=60, auto_report=True) -> DeviceClient

Class method. Start a device session and return a connected client.

By default, blocks until the device is API-ready. Pass `wait_for_ready=False` for fire-and-forget provisioning.

| Parameter | Type | Description |
|-----------|------|-------------|
| `platform` | `str` | `"ios"` or `"android"` |
| `timeout` | `Optional[int]` | Idle timeout in seconds |
| `open_viewer` | `bool` | Open the live viewer in the browser |
| `app_id` | `Optional[str]` | Revyl app ID to preinstall |
| `build_version_id` | `Optional[str]` | Specific build version to install |
| `app_url` | `Optional[str]` | URL to an `.ipa` or `.apk` to preinstall |
| `app_link` | `Optional[str]` | Deep link to open after launch |
| `device_model` | `Optional[str]` | Target device model (e.g. `"iPhone 16"`). Must be paired with `os_version`. |
| `os_version` | `Optional[str]` | Target OS version (e.g. `"iOS 18.5"`). Must be paired with `device_model`. |
| `cli` | `Optional[RevylCLI]` | Custom CLI instance |
| `wait_for_ready` | `bool` | Block until device is API-ready (default `True`). Set `False` for fire-and-forget. |
| `ready_timeout` | `float` | Max seconds to wait for readiness when `wait_for_ready=True` (default `60`). |
| `auto_report` | `bool` | Auto-print report/video URLs on `close()` (default `True`). |
| `verbose` | `bool` | Show animated spinner during provisioning (default `True`). Set `False` for CI. |
```

--------------------------------

### Install Revyl Skills for Expo Auth

Source: https://github.com/revylai/revyl-cli/blob/main/skills/revyl-cli-auth-bypass-expo/SKILL.md

Install the necessary Revyl skills for Expo authenticated-state work. Use `--force` to overwrite existing installations if needed.

```bash
# Install the auth-bypass entrypoint and this Expo leaf when setting up an agent
# for Expo authenticated-state work.
revyl skill install --name revyl-cli-auth-bypass --force
revyl skill install --name revyl-cli-dev-loop --force
revyl skill install --name revyl-cli-auth-bypass-expo --force
```

--------------------------------

### Start Session with Named Device Presets

Source: https://github.com/revylai/revyl-cli/blob/main/docs/device/live-observability.md

Launch a new device session using a predefined configuration by specifying a device name. This is an alternative to manually setting the device model and OS version. The `--open` flag can be used to automatically open the session.

```bash
revyl device start --device-name revyl-ios-iphone
```

```bash
revyl device start --device-name revyl-android-phone --open
```

--------------------------------

### Install Dependencies

Source: https://github.com/revylai/revyl-cli/blob/main/docs/integrations/expo-dashboard.md

Install necessary dependencies for your Expo project before building.

```bash
cd my-expo-app
npm install
```

--------------------------------

### Initialize Revyl Project

Source: https://github.com/revylai/revyl-cli/blob/main/docs/tests/first-test.md

Initialize your project with Revyl. The interactive wizard detects your build system and creates `.revyl/config.yaml`. Use `-y` to skip the wizard and configure manually.

```bash
cd your-app
revyl init
```

```bash
revyl init -y
```

--------------------------------

### Install Skills

Source: https://github.com/revylai/revyl-cli/blob/main/docs/integrations/skills.md

Installs various Revyl CLI skills, with the `--force` option to overwrite existing installations. This includes core skills and platform-specific auth bypass leaves.

```bash
revyl skill install --name revyl-cli-dev-loop --force
```

```bash
revyl skill install --name revyl-cli-create --force
```

```bash
revyl skill install --name revyl-cli-auth-bypass --force
```

```bash
revyl skill install --name revyl-cli-auth-bypass-expo --force
```

```bash
revyl skill install --name revyl-cli-auth-bypass-react-native --force
```

```bash
revyl skill install --name revyl-cli-auth-bypass-ios --force
```

```bash
revyl skill install --name revyl-cli-auth-bypass-android --force
```

```bash
revyl skill install --name revyl-cli-auth-bypass-flutter --force
```

```bash
revyl skill install --name revyl-cli-create --cursor --force
```

--------------------------------

### Install Skills for Specific AI Tools

Source: https://github.com/revylai/revyl-cli/blob/main/docs/integrations/skills.md

Install skills optimized for particular AI coding tools like Cursor, Codex, or Claude Code. Add the tool flag to the install command.

```bash
revyl skill install --cursor --force
```

```bash
revyl skill install --codex --force
```

```bash
revyl skill install --claude --force
```

--------------------------------

### Start Bare React Native Dev Loop

Source: https://github.com/revylai/revyl-cli/blob/main/docs/COMMANDS.md

Starts the development loop for bare React Native projects, launching Metro via `npx react-native start`. Supports specifying the platform.

```bash
revyl dev                    # Starts Metro via `npx react-native start`
revyl dev --platform android
```

--------------------------------

### CI/CD Pipeline Setup

Source: https://github.com/revylai/revyl-cli/blob/main/docs/tests/running-tests.md

Commands for setting up a CI/CD pipeline. This includes setting the API key, uploading a build, and running a regression workflow.

```bash
# In your CI script
export REVYL_API_KEY=${{ secrets.REVYL_API_KEY }}

# Build and upload
revyl build upload --platform android --version $GITHUB_SHA

# Run workflow, fail pipeline if tests fail
revyl workflow run regression --retries 2
```

--------------------------------

### Install Revyl CLI via pip

Source: https://github.com/revylai/revyl-cli/blob/main/docs/cli-index.md

Install the Revyl CLI using pip.

```bash
pip install revyl
```

--------------------------------

### Full Pipeline: Build, Upload, and Workflow

Source: https://github.com/revylai/revyl-cli/blob/main/docs/tests/running-tests.md

Execute the full pipeline for a workflow, including building the app, uploading it, and running all tests within the workflow. This is the recommended approach for building and running workflows. Use `--no-build` to skip the build step.

```bash
revyl run smoke-tests -w
```

```bash
revyl run smoke-tests -w --platform android
```

```bash
revyl workflow run smoke-tests --build --platform android
```

--------------------------------

### Install Revyl CLI

Source: https://github.com/revylai/revyl-cli/blob/main/python/README.md

Install the Revyl CLI using curl for macOS/Linux, Homebrew, pipx, uv, or pip. The shell installer downloads a native binary, while pip, pipx, and uv auto-download it on first use.

```bash
curl -fsSL https://revyl.com/install.sh | sh       # Shell (macOS / Linux)
```

```bash
brew install RevylAI/tap/revyl          # Homebrew (macOS)
```

```bash
pipx install revyl                      # pipx (cross-platform)
```

```bash
uv tool install revyl                   # uv
```

```bash
pip install revyl                       # pip
```

--------------------------------

### Create or Update Launch Vars

Source: https://github.com/revylai/revyl-cli/blob/main/skills/revyl-cli-auth-bypass/SKILL.md

Set up the necessary launch variables for authentication bypass. Use 'create' if they don't exist, or 'update' if they do.

```bash
export REVYL_AUTH_BYPASS_TOKEN="<test-only-token>"
revyl global launch-var create REVYL_AUTH_BYPASS_ENABLED=true
revyl global launch-var create REVYL_AUTH_BYPASS_TOKEN="$REVYL_AUTH_BYPASS_TOKEN"
```

```bash
revyl global launch-var update REVYL_AUTH_BYPASS_TOKEN --value "$REVYL_AUTH_BYPASS_TOKEN"
```

--------------------------------

### Install Revyl CLI via pipx

Source: https://github.com/revylai/revyl-cli/blob/main/docs/cli-index.md

Install the Revyl CLI cross-platform using pipx.

```bash
pipx install revyl
```

--------------------------------

### DeviceClient.start

Source: https://github.com/revylai/revyl-cli/blob/main/docs/device-sdk/reference.md

Starts a new device session. By default, it blocks until the device is API-ready. The session is automatically stopped and a report URL is printed upon exiting the context manager.

```APIDOC
## DeviceClient.start(platform, app_url=None, wait_for_ready=True)

### Description
Starts a new device session. By default, it blocks until the device is API-ready. The session is automatically stopped and a report URL is printed upon exiting the context manager.

### Parameters
#### Path Parameters
- `platform` (str) - The target platform (e.g., "ios", "android").
- `app_url` (Optional[str]) - URL of the application to install and launch.
- `wait_for_ready` (bool) - If `True`, blocks until the device is API-ready. If `False`, returns immediately.
```

--------------------------------

### Verify Revyl CLI Installation

Source: https://github.com/revylai/revyl-cli/blob/main/docs/cli-index.md

Run this command to check if the Revyl CLI has been installed correctly and to display its version.

```bash
revyl version
```

--------------------------------

### Install Revyl CLI via Homebrew

Source: https://github.com/revylai/revyl-cli/blob/main/docs/cli-index.md

Install the Revyl CLI on macOS using the Homebrew package manager.

```bash
brew install RevylAI/tap/revyl
```

--------------------------------

### Install Revyl CLI

Source: https://github.com/revylai/revyl-cli/blob/main/README.md

Use these commands to install the Revyl CLI on macOS, Linux, or other platforms using pipx or uv.

```bash
curl -fsSL https://revyl.com/install.sh | sh  # Shell (macOS / Linux)
```

```bash
brew install RevylAI/tap/revyl          # Homebrew (macOS)
```

```bash
pipx install revyl                      # pipx (cross-platform)
```

```bash
uv tool install revyl                   # uv
```

--------------------------------

### Build Upload Troubleshooting

Source: https://github.com/revylai/revyl-cli/blob/main/docs/tests/running-tests.md

Tips for resolving build upload failures. Ensure your build command produces output, check file permissions, and use `--dry-run` to preview the upload.

```bash
--dry-run
```

--------------------------------

### DeviceClient.start_session

Source: https://github.com/revylai/revyl-cli/blob/main/docs/SDK.md

Starts a device session with the same parameters as `DeviceClient.start` (excluding `cli`). It returns a dictionary containing session information, including the session `index`.

```APIDOC
## start_session(platform, timeout=None, open_viewer=False, app_id=None, build_version_id=None, app_url=None, app_link=None, device_model=None, os_version=None) -> dict

Start a device session. Same parameters as `start()` (except `cli`). Returns session info including the session `index`.
```

--------------------------------

### Install and Manage Revyl Agent Skills

Source: https://github.com/revylai/revyl-cli/blob/main/README.md

Use these commands to list, install, and manage Revyl agent skills. The `--force` flag is used to overwrite existing installations. Specific skills are available for dev loops, test authoring, and authentication bypass scenarios.

```bash
revyl skill list
```

```bash
revyl skill install --force
```

```bash
revyl skill install --name revyl-cli-dev-loop --force
```

```bash
revyl skill install --name revyl-cli-create --force
```

```bash
revyl skill install --name revyl-cli-auth-bypass --force
```

```bash
revyl skill install --name revyl-cli-auth-bypass-expo --force
```

```bash
revyl skill install --name revyl-cli-auth-bypass-react-native --force
```

```bash
revyl skill install --name revyl-cli-auth-bypass-ios --force
```

```bash
revyl skill install --name revyl-cli-auth-bypass-android --force
```

```bash
revyl skill install --name revyl-cli-auth-bypass-flutter --force
```

```bash
revyl skill install --cursor --force
```

```bash
revyl skill install --codex --force
```

```bash
revyl skill install --claude --force
```

```bash
revyl skill install --global --force
```

```bash
revyl skill show --name revyl-cli-dev-loop
```

```bash
revyl skill export --name revyl-cli-create -o SKILL.md
```

--------------------------------

### Install Revyl CLI

Source: https://github.com/revylai/revyl-cli/blob/main/docs/device/quickstart.md

Install the Revyl CLI using various package managers. Choose the method that best suits your environment.

```bash
curl -fsSL https://revyl.com/install.sh | sh
```

```bash
brew install RevylAI/tap/revyl    # Homebrew (macOS)
```

```bash
pipx install revyl                # pipx (cross-platform)
```

```bash
uv tool install revyl             # uv
```

```bash
pip install revyl                 # pip
```

--------------------------------

### Install Revyl CLI via Shell Script

Source: https://github.com/revylai/revyl-cli/blob/main/docs/cli-index.md

Use this command to install the Revyl CLI using a shell script for macOS and Linux.

```bash
curl -fsSL https://revyl.com/install.sh | sh
```

--------------------------------

### GitLab CI Example for Revyl CLI

Source: https://github.com/revylai/revyl-cli/blob/main/docs/guide-authentication.md

This example demonstrates how to use the REVYL_API_KEY variable in GitLab CI to authenticate Revyl commands in your pipeline.

```yaml
test:
  script:
    - revyl workflow run smoke-tests
  variables:
    REVYL_API_KEY: $REVYL_API_KEY
```

--------------------------------

### Manage Revyl Skills

Source: https://github.com/revylai/revyl-cli/blob/main/docs/COMMANDS.md

Commands for listing, installing, and showing Revyl skills. Use `--force` to overwrite existing skills or install recommended ones. Specific skills can be installed by name, and certain tools like Cursor, Codex, or Claude Code can be forced if auto-detection is ambiguous.

```bash
revyl skill list
```

```bash
revyl skill install --force
```

```bash
revyl skill install --name revyl-cli-dev-loop --force
```

```bash
revyl skill install --name revyl-cli-create --force
```

```bash
revyl skill install --name revyl-cli-auth-bypass --force
```

```bash
revyl skill install --name revyl-cli-auth-bypass-expo --force
```

```bash
revyl skill install --name revyl-cli-auth-bypass-react-native --force
```

```bash
revyl skill install --name revyl-cli-auth-bypass-ios --force
```

```bash
revyl skill install --name revyl-cli-auth-bypass-android --force
```

```bash
revyl skill install --name revyl-cli-auth-bypass-flutter --force
```

```bash
revyl skill install --cursor --force
```

```bash
revyl skill install --codex --force
```

```bash
revyl skill install --claude --force
```

```bash
revyl skill show --name revyl-cli-dev-loop
```

```bash
revyl skill export --name revyl-cli-create -o FILE
```

--------------------------------

### Install Revyl CLI with Package Managers

Source: https://github.com/revylai/revyl-cli/blob/main/docs/getting-started.md

Install the Revyl CLI using Homebrew on macOS, pipx for cross-platform compatibility, or pip for Python environments.

```bash
brew install RevylAI/tap/revyl
```

```bash
pipx install revyl
```

```bash
pip install revyl
```

--------------------------------

### Start Device Session and Wait for Readiness

Source: https://github.com/revylai/revyl-cli/blob/main/docs/SDK.md

Initiates a device session, optionally pre-installing an app. The `wait_for_device_ready` method polls diagnostics until the device is API-ready, with a configurable timeout. This is automatically called by `DeviceClient.start` when `wait_for_ready` is true.

```python
device = DeviceClient.start(platform="ios", app_url=url, wait_for_ready=False)
# ... parallel setup ...
device.wait_for_device_ready(timeout=90)
```

--------------------------------

### Device-First Development Flow

Source: https://github.com/revylai/revyl-cli/blob/main/docs/COMMANDS.md

Starts a plain device session first, then attaches the development loop to it. Reuses the attached session for subsequent `revyl dev` commands within the same context.

```bash
revyl device start --platform ios
revyl dev attach active                # or: revyl dev attach <session-id>
revyl dev                              # reuses the attached session
```

--------------------------------

### GitHub Actions Example for Revyl CLI

Source: https://github.com/revylai/revyl-cli/blob/main/docs/guide-authentication.md

This example shows how to set the REVYL_API_KEY secret in GitHub Actions to run Revyl commands within a workflow.

```yaml
- name: Run Revyl Tests
  env:
    REVYL_API_KEY: ${{ secrets.REVYL_API_KEY }}
  run: |
    revyl workflow run smoke-tests
```

--------------------------------

### instruction

Source: https://github.com/revylai/revyl-cli/blob/main/docs/device-sdk/reference.md

Executes a single instruction step against an active device session. The description should be a natural-language action.

```APIDOC
## instruction(description, session_index=None)

### Description
Execute one instruction step. The description is a natural-language action like `"Open Settings and tap Wi-Fi"`.

### Parameters
#### Path Parameters
- **description** (string) - Required - The natural-language description of the action to perform.
- **session_index** (int) - Optional - The index of the session to target.
```

--------------------------------

### Build, Zip, Upload, and Test iOS App

Source: https://github.com/revylai/revyl-cli/blob/main/docs/builds/ios-native.md

Use this command sequence to build your iOS app for a simulator, package it, upload it to Revyl, and run a test. Ensure your project uses `.xcodeproj` and targets the `iphonesimulator` SDK.

```bash
# 1. Build for simulator
xcodebuild \
  -project YourApp.xcodeproj \
  -scheme YourApp \
  -configuration Debug \
  -sdk iphonesimulator \
  -derivedDataPath build \
  -quiet

# 2. Zip and upload
cd build/Build/Products/Debug-iphonesimulator
zip -r ../../../../build/app.zip YourApp.app
cd ../../../../
revyl build upload --file build/app.zip --platform ios

# 3. Run a test
revyl test run login-smoke
```

--------------------------------

### Revyl CLI Dev Loop Prompt Example

Source: https://github.com/revylai/revyl-cli/blob/main/docs/integrations/mcp-setup.md

A prompt for the revyl-cli-dev-loop skill to verify sign-in and home screen access using CLI commands. Includes steps for initialization, running the dev loop, creating, and running tests.

```text
Use the revyl-cli-dev-loop skill.
Goal: verify I can sign in and reach Home using CLI flow.
Use only Revyl CLI commands (no MCP tool calls).

Steps:
1) start from project root
2) run revyl init if needed
3) run revyl dev and wait for readiness
4) summarize exact actions I should perform in app
5) convert successful flow into a test:
   - revyl dev test create login-smoke --platform ios
   - revyl dev test open login-smoke
   - revyl test push login-smoke --force
   - revyl test run login-smoke
6) if run fails, fetch report with revyl test report login-smoke --json and classify failure
```

--------------------------------

### Start Expo Tunnel with Dev Client

Source: https://github.com/revylai/revyl-cli/blob/main/skills/revyl-cli-dev-loop/SKILL.md

Starts an Expo development server in tunnel mode with the dev client enabled. This command should be run in a long-running terminal.

```bash
CURSOR_AGENT=1 npx expo start --tunnel --dev-client
```

--------------------------------

### Prompt Example: Auth Bypass

Source: https://github.com/revylai/revyl-cli/blob/main/docs/integrations/skills.md

Example prompt for using the `revyl-cli-auth-bypass` skill to set up test-only authentication bypass, select a platform recipe, and verify link handling.

```text
Use the revyl-cli-auth-bypass skill. Set up test-only auth bypass for this app, choose the platform recipe after inspecting the repo, and verify valid and rejected links on a Revyl device.
```