Your first test from the CLI

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 CLICopy Anchor Link

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

Verify it worked:

revyl version

Step 2: AuthenticateCopy Anchor Link

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)...
✓ Successfully authenticated as user@example.com
Organization: <org-id>
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 instead.

Step 3: Initialize your projectCopy Anchor Link

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:

revyl init -y

Step 4: Upload a buildCopy Anchor Link

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

revyl build --profile development --platform android

This builds in the cloud. See Build Configuration for prerequisites.

Step 5: Write a YAML testCopy Anchor Link

Create a file called login-smoke.yaml:

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 testCopy Anchor Link

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 testCopy Anchor Link

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 flagsCopy Anchor Link

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

Step 9: IterateCopy Anchor Link

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

revyl test push login-smoke --force
revyl test run login-smoke

YAML as Source of TruthCopy Anchor Link

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

Commit .revyl/tests/ to gitCopy Anchor Link

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

git add .revyl/tests/
git commit -m "Add login-smoke test"

Daily sync patternCopy Anchor Link

# 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 statusCopy Anchor Link

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

Reconcile when things driftCopy Anchor Link

revyl test sync --dry-run         # Preview what test sync will change
revyl test sync --prune           # Reconcile and clean up stale test mappings

Resolve conflictsCopy Anchor Link

revyl test diff checkout          # See the diff
revyl test pull checkout --force  # Keep remote version
revyl test push checkout --force  # Keep local version

Quick ReferenceCopy Anchor Link