> ## Documentation Index
> Fetch the complete documentation index at: https://docs.revyl.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Drive a device

> Start, control, and debug Revyl cloud devices from the CLI.

You can use these devices without creating a Revyl test. See
[Device Infrastructure](/infrastructure) for custom harnesses, CI workflows,
and the Appium and Maestro connection requirements.

If you are new, start with [Device Quickstart](#quickstart).

## Choose Your Path

<CardGroup cols={2}>
  <Card title="Device Quickstart" icon="rocket" href="#quickstart">
    Learn the core session and action loop in minutes.
  </Card>
  <Card
    title="Auth And Session Prep"
    icon="key"
    href="/devices/session-prep"
  >
    How `session.before_script` and `session.auth_bypass` attach on `revyl
    device start`.
  </Card>
  <Card
    title="Live Observability"
    icon="chart-line"
    href="/devices/live-observability"
  >
    Stream perf, network, and device logs live, and pull post-session artifacts.
  </Card>
  <Card
    title="Troubleshooting"
    icon="wrench"
    href="/devices/troubleshooting"
  >
    Fix session, install, grounding, and action issues quickly.
  </Card>
</CardGroup>

## When To Use What

| Goal                                                                          | Best Entry Point                                           |
| ----------------------------------------------------------------------------- | ---------------------------------------------------------- |
| First end-to-end run on a cloud device                                        | [Device Quickstart](#quickstart)                |
| Signed-in starts via config (`session.before_script` / `session.auth_bypass`) | [Auth And Session Prep](/devices/session-prep) |
| Full command-level control                                                    | [Command Reference](/reference/cli)                |
| Agent-driven device control from IDE                                          | [MCP Setup](/agents/mcp)                                |
| CI orchestration of test and workflow runs                                    | [CI/CD Integration](/tests/ci)               |

## Core Ergonomics Loop

Whether you use CLI, SDK, or MCP, use the same reliable loop:

1. Take a screenshot or otherwise re-observe current state.
2. Choose one best action.
3. Verify the result immediately.
4. Repeat.

This avoids blind action chains and makes failures easier to debug.

## Quickstart

This is the fastest way to get a working device session and take real actions safely.

### 1. Install and Authenticate

<CodeGroup>

```bash CLI
curl -fsSL https://revyl.com/install.sh | sh
brew install RevylAI/tap/revyl    # Homebrew (macOS)
pipx install revyl                # pipx (cross-platform)
uv tool install revyl             # uv
pip install revyl                 # pip
```

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

</CodeGroup>

Then authenticate. The CLI prints an approval URL — open it in any browser and approve:

```bash
revyl auth login
```

You can also use an API key:

```bash
export REVYL_API_KEY="rev_..."
```

### 2. Start a Device Session

Run from the directory that owns `.revyl/` (or a subdirectory of it) so project
config is loaded.

<CodeGroup>

```bash CLI
revyl device start --platform android --timeout 600
revyl device info
```

```python Python SDK
from revyl import DeviceClient

device = DeviceClient.start(platform="android", timeout=600)
print(device.info())
```

</CodeGroup>

If `.revyl/config.yaml` declares `session.before_script` and/or
`session.auth_bypass`, the CLI runs `session.before_script` and applies
`session.auth_bypass` when each is configured for iOS and Android sessions.
Web (alpha) starts do not run `session.before_script`. See
[Auth And Session Prep](/devices/session-prep).

### 3. Install and Launch Your App

Use a direct build URL (APK or IPA). Launch defaults to the app you just
installed, so you do not need to know its bundle ID — pass `--bundle-id` only
to launch a different installed app.

<CodeGroup>

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

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

</CodeGroup>

### 4. Use the Safe Action Loop

Always re-observe before and after important actions.

<CodeGroup>

```bash CLI
revyl device screenshot --out before.png
revyl device tap --target "Sign In button"
revyl device type --target "Email field" --text "user@example.com"
revyl device screenshot --out after.png
```

```python Python SDK
device.screenshot(out="before.png")
device.tap(target="Sign In button")
device.type_text(target="Email field", text="user@example.com")
device.screenshot(out="after.png")
```

</CodeGroup>

### 5. Stop the Session

<CodeGroup>

```bash CLI
revyl device stop
```

```python Python SDK
device.stop_session()
```

</CodeGroup>

### Next

- Signed-in sessions: [Auth And Session Prep](/devices/session-prep)
- Full command coverage: [Command Reference](/reference/cli)
- Agent-driven device control: [MCP Setup](/agents/mcp)
- CI/CD test and workflow runs: [CI/CD Integration](/tests/ci)