> ## 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.

# First Test

This guide takes you from zero to a passing test. By the end you'll have the CLI installed, a test written in YAML, and a report you can share.

**Time:** \~10 minutes

## Step 1: Install the CLI

<CodeGroup>
  ```bash Shell (macOS/Linux) theme={null}
  curl -fsSL https://revyl.com/install.sh | sh
  ```

  ```bash Homebrew (macOS) theme={null}
  brew install RevylAI/tap/revyl
  ```

  ```bash pipx (cross-platform) theme={null}
  pipx install revyl
  ```

  ```bash uv theme={null}
  uv tool install revyl
  ```

  ```bash pip theme={null}
  pip install revyl
  ```
</CodeGroup>

Verify it worked:

```bash theme={null}
revyl version
```

## Step 2: Authenticate

```bash theme={null}
revyl auth login
```

The CLI prints an approval URL and a short code and waits for you to approve in a browser. Open the URL, check the code matches, and approve.

```
Open this URL to approve, then confirm the code below:

  https://app.revyl.ai/cli/device?code=HTKD-4W2N
  Code: HTKD-4W2N

Waiting for approval (press Ctrl+C to cancel)...
✓ Authenticated as user@example.com
✓ Organization: My Company
✓ Credentials saved to ~/.revyl/credentials.json
```

On a machine with no one to approve, run `revyl auth login --api-key` and paste a key from [Account → API Keys](https://auth.revyl.ai/account/api_keys) instead.

<Callout type="tip" title="CI/CD?">
  For automated environments, set `REVYL_API_KEY` as an environment variable
  instead. See [CI/CD Integration](/guides/run-tests-ci-cd).
</Callout>

## Step 3: Initialize your project

```bash theme={null}
cd your-app
revyl init
```

The interactive wizard:

1. Detects your build system (Expo, Gradle, Xcode, Flutter, React Native)
2. Creates `.revyl/config.yaml`
3. Walks you through creating apps and uploading a build
4. Can continue into GitHub PR automation after authentication

To skip the wizard and configure manually:

```bash theme={null}
revyl init -y
```

## Step 4: Upload a build

If `revyl init` didn't upload a build for you, do it now:

```bash theme={null}
revyl build --profile development --platform android
```

This builds in the cloud. See [Build Configuration](/remote-builds/configuration)
for prerequisites.

<Callout type="info" title="Build artifact requirements">
  Default debug builds work everywhere. If you're uploading a custom build
  (release APK, `.ipa`, narrowed `abiFilters`), see [Build Artifact
  Requirements](/builds/artifact-requirements).
</Callout>

## Step 5: Write a YAML test

Create a file called `login-smoke.yaml`:

```yaml theme={null}
test:
  metadata:
    name: login-smoke
    platform: ios
    tags:
      - smoke
  build:
    name: my-ios-app
  blocks:
    - type: instructions
      step_description: Tap the Sign In button.
    - type: instructions
      step_description: Type "user@example.com" in the email field.
    - type: instructions
      step_description: Type "password123" in the password field.
    - type: instructions
      step_description: Tap Continue.
    - type: validation
      step_description: The home screen is visible.
```

Key fields:

* `test.metadata.name` — must be unique in your org
* `test.metadata.platform` — `ios` or `android`
* `test.build.name` — must match a Revyl app name exactly. Check with `revyl app list`.
* `test.blocks` — ordered list of steps (intent-level instructions, assertions in separate `validation` blocks)

## Step 6: Create the test

```bash theme={null}
revyl test create login-smoke --from-file ./login-smoke.yaml
```

This requires the selected project to already have a
`.revyl/config.yaml`; it never creates or migrates project configuration. If
the file is missing, first run `revyl config pull` for a project already
registered with Revyl, or `revyl init -y` for a new local project. For a legacy
file, run `revyl config migrate --check`, then `revyl config migrate`.

The create command then checks the YAML with backend validation, copies it to
`.revyl/tests/login-smoke.yaml`, and creates the remote test.

## Step 8: Run the test

```bash theme={null}
revyl test run login-smoke
```

The CLI queues the test, streams progress to your terminal, and opens the
completed report for a blocking human-terminal run.

### Useful run flags

| Flag | Description |
| - | - |
| `--open` | Explicitly request report opening for a supported blocking human-terminal run |
| `--no-open` | Do not open the completed report |
| `--retries <n>` | Retry attempts (default: 1) |
| `--timeout <seconds>` | Maximum execution time (default: 3600) |
| `--no-wait` | Queue and exit immediately |
| `--json` | Structured JSON output |
| `--build-version-id <id>` | Pin a specific build version |

No-wait, JSON, GitHub Actions, CI, SSH, and other headless runs never open a
browser.

## Step 9: Iterate

Edit `.revyl/tests/login-smoke.yaml`, then push and re-run:

```bash theme={null}
revyl test push login-smoke --force
revyl test run login-smoke
```

***

## YAML as Source of Truth

For teams that want test definitions version-controlled alongside code.

### Commit `.revyl/tests/` to git

The `.revyl/tests/` directory is **not gitignored** by default. These YAML files are your source of truth — commit them.

```bash theme={null}
git add .revyl/tests/
git commit -m "Add login-smoke test"
```

### Daily sync pattern

```bash theme={null}
# Start of day — pull any changes made in the browser editor
revyl test pull

# Work on tests locally in your IDE
# ...

# See what changed vs remote
revyl test diff login-smoke

# Push your changes
revyl test push
```

### Check sync status

```bash theme={null}
revyl test list
```

```
NAME              STATUS      PLATFORM   LAST MODIFIED
login-smoke       synced      ios        2 hours ago
checkout          modified    ios        5 minutes ago
onboarding        outdated    android    1 day ago
```

| Status | Meaning |
| - | - |
| `synced` | Local and remote are identical |
| `modified` | Local changes not yet pushed |
| `outdated` | Remote has newer changes |
| `local-only` | Exists locally but not on remote |

### Reconcile when things drift

```bash theme={null}
revyl test sync --dry-run         # Preview what test sync will change
revyl test sync --prune           # Reconcile and clean up stale test mappings
```

### Resolve conflicts

```bash theme={null}
revyl test diff checkout          # See the diff
revyl test pull checkout --force  # Keep remote version
revyl test push checkout --force  # Keep local version
```

***

## Quick Reference

| Task | Command |
| - | - |
| See available tests | `revyl test list` |
| View a test report | `revyl test report login-smoke` |
| Open in browser editor | `revyl test open login-smoke` |
| Cancel a running test | `revyl test cancel <task_id>` |
| Check sync status | `revyl test list` (shows synced/modified/outdated) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.