Command Reference - Revyl Documentation

Authentication

revyl auth login     # Authenticate with Revyl
revyl auth logout    # Remove stored credentials
revyl auth status    # Show authentication status

Project Setup

revyl init                                    # Detect and write the local project config
revyl init -y                                 # Write it without interactive follow-up
revyl init --project <uuid>                   # Store this project ID locally
revyl init --detect                           # Re-run framework and build detection
revyl init --force                            # Replace an existing canonical local config
revyl init --xcode-scheme ios=MyAppDev        # Embed an Xcode scheme in generated commands (repeatable)

Initialization always writes a stable local project.id. When detection succeeds, it also writes the detected build.framework and named profiles for the detected iOS and/or Android platforms. Supplying --project writes that ID into the local file; it does not validate, register, attach, or publish a server project. An Xcode scheme supplied during setup is materialized into the generated build commands, not stored as separate runtime state. Use -y to accept only deterministic local choices without prompts and stop after config creation. Interactive initialization may continue through the existing optional authentication, app, skill, and first-build onboarding after the local file is written. If authentication is needed, the CLI prints an approval URL and short code that may be approved in any signed-in browser. After it writes the project config, authenticated setup can also continue into the same GitHub PR-automation flow as revyl github setup. The locally written project.id remains unverified and unpublished unless that separate server-backed flow succeeds.

Project Config

Inspect, validate, and migrate the nearest local .revyl/config.yaml. Use the global -C <directory> option to select another project root in the same worktree.

revyl config path                                 # Print the selected config path
revyl config show                                 # Show the local project config
revyl config show --json                          # JSON for scripting
revyl config validate                             # Validate locally and, with authentication and a supported GitHub origin, against Revyl
revyl config migrate                              # Summarize, confirm, back up, and replace a legacy file
revyl config migrate --check                      # Summarize a legacy conversion without writing
revyl config migrate --write                      # Back up and replace without confirmation
revyl config migrate --project <uuid>             # Use this project ID in the local conversion
revyl config push                                 # Publish the complete config when authority is manual
revyl config push --force                         # Publish once without leaving default-branch management
revyl config pull                                 # Restore or replace from server state, backing up divergence
revyl config pull --project <uuid>                # Assert the expected configured project ID before pulling
revyl config authorize-cursor-proof               # Authorize Cursor proof runs for the current project

config path and config show use the same nearest-config selection as other project commands. config show expects the canonical contract; migrate a legacy file first. To change settings, edit .revyl/config.yaml directly and validate it; the config commands have no separate command for mutating individual YAML keys. config migrate only mutates local project files. A successfully prepared legacy migration uses the same concise clean-or-lossy human summary; a write creates an exact-byte backup. JSON --check contains the complete migration proposal and migration ledger. Legacy top-level test aliases become conflict-checked .revyl/tests/<alias>.yaml files. A matching file for the same remote test is preserved byte-for-byte; any other destination conflict fails migration. The retired top-level workflow alias cache is reported and removed. The default mode asks for confirmation, creates an exact-byte config backup, creates only missing alias files, and atomically replaces the config. --check creates no backup and writes no file; --write performs the same local changes without confirmation. When authenticated, migration may make read-only lookups to reuse or interactively select a project from the verified repository, resolve enabled legacy PR-build app names to exact platform app IDs, and resolve legacy PR workflow names—including the implicit smoke workflow from smoke_every_pr—through authenticated exact-name lookup. Missing, duplicate, or inaccessible workflow matches are omitted and reported instead of stopping the remaining conversion. An enabled PR build is never silently removed: unresolved app or framework meaning is reported as lossy and omitted from the best-effort proposal. Inspect JSON --check before writing; afterward, compare the reported backup or ask a coding agent to reconcile omissions. Use --project when you need to supply the local project identity explicitly. Migration never creates or attaches a server project, pulls or publishes configuration, or otherwise mutates server state. config validate always validates the discovered project config locally. When authenticated and a supported GitHub origin is available, it also verifies GitHub access and checks the project identity, repository root, configuration path, and referenced Revyl resources without writing anything. Validation requires a stable project.id; it does not convert or scaffold a legacy config. config push requires a readable local project config, authentication, and verified access to its GitHub repository. Recovery errors name the exact config migrate, config pull or init, auth login or auth status, github status or github connect, Git-origin or repository-access repair, config validate, or retry command needed for the failed prerequisite. Push then reads the current server state and publishes with an exact absent-or-hash precondition. It makes a single publish attempt so an ambiguous network result cannot be retried as a new write. Projects managed from the default branch reject ordinary manual publication; validate the file and commit the designated .revyl/config.yaml instead. config push --force is an explicit one-publication override. It keeps default-branch management and its reconciliation position intact, so a later default-branch configuration change can replace the forced aggregate. Under manual authority, --force does not change behavior. When no local config exists, config pull verifies the GitHub repository, selects the nearest configured project root containing the current directory, verifies its configuration hash, and atomically creates .revyl/config.yaml at that root. --project may select an explicitly identified, more-specific registered project beneath an ancestor local config, but it never rebinds an applicable active local project with a different ID. It does not replace a legacy or invalid file. With an existing valid file, semantic equality remains a no-op. Divergence creates an exact-byte backup and atomically replaces the file. When the local project was deleted and exactly one active replacement owns the same root, pull performs that backup/replacement without trusting the retired ID. Pull reports the backup path and does not require an interactive confirmation, including in JSON and non-interactive invocations. config authorize-cursor-proof records server-owned human authority for unattended Cursor proof runs after Revyl confirms the caller can launch cloud agents and the caller’s live Cursor repository catalog includes the project repository. It does not edit or publish .revyl/config.yaml, and works for both manual and default-branch configuration authority.

Inherited Launch Configuration

REVYL_INHERITED_LAUNCH_ENV_VAR_IDS is a comma-separated list of stored launch-configuration UUIDs applied automatically by revyl dev, revyl test run, revyl workflow run, and raw revyl device start commands. Cloud Agent Conversations sets it from the launch selection. Explicit --launch-var and --launch-arg-set values remain additive; --no-inherited-launch-vars ignores it entirely. Restart an existing device or dev session before changing launch configuration.

Running Tests

revyl test run login-flow                 # Run against last uploaded build
revyl test run login-flow --build         # Build, upload, then run

revyl workflow run smoke-tests            # Run a workflow
revyl workflow run smoke-tests --build    # Build then run workflow

Advanced Run Flags

--retries 3       # Retry on failure (1-5, default 1)
--build-id <id>   # Run against a specific build version
--no-wait         # Queue and exit without waiting for results
--verbose / -v    # Show step-by-step execution progress
--timeout 3600    # Max execution time in seconds

Explore

Build or refresh an Atlas map from the terminal:

revyl explore run "My App"                # Explore the latest build and wait
revyl explore run --platform android       # Use the configured Android app
revyl explore run "My App" --no-wait --json
revyl explore status <run-id>
revyl explore cancel <run-id>

Common run flags:

--build-id <id>                # Pin an uploaded build
--explorers 4                  # Parallel explorers (default 3)
--strategy surface-sweep       # balanced, surface-sweep, journey-focus, hard-edges
--instructions "Cover checkout"
--auth-instructions "Use the test account"
--launch-var <key-or-id>       # Stored launch variable (repeatable)
--device-model "iPhone 16"
--os-version "iOS 18.5"
--max-duration 20m
--idle-timeout 10m
--timeout 30m                  # Local wait limit; does not cancel the run
--open

See Explore from the CLI for output, outcome, and CI semantics.

Dev Loop

revyl dev starts a local development loop backed by a cloud device session. Both Expo and bare React Native projects are supported, plus native Swift/iOS and Android projects via rebuild-based loops. Each revyl dev start creates a dev context — a named, worktree-local dev loop bound to one resolved profile/platform recipe. Use --context for same-repo concurrency; separate worktrees use the default context automatically. The context keeps that recipe for subsequent rebuilds.

revyl dev --profile development --platform ios  # Explicit profile and platform
revyl dev --platform android           # Infer the profile when only one remains eligible
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 --profile development --platform ios --build  # Force a fresh build
revyl dev --app-id <app-id>            # Use explicit app override
revyl dev --build-version-id <id>      # Use explicit build override
revyl dev --launch-var API_URL         # Add a stored variable by key (UUID also accepted)
revyl dev --no-inherited-launch-vars   # Ignore inherited launch-variable IDs
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

Profile and platform selection applies explicit flags first. Without --profile, revyl dev prefers one uniquely named development-like profile, then falls back to a sole eligible choice. Development-like names contain a dev or development token, so dev, development, and ios-dev match but device does not. Any remaining interactive ambiguity prompts; a non-interactive run fails with the choices and the required flag. There is no active/default profile or default platform. revyl dev:

starts your local dev server (Expo via npx expo start --dev-client, or Metro via npx react-native start)
creates a Revyl relay to expose it to cloud devices
resolves the latest build for your current git branch from the selected recipe’s app, then installs it
- if no branch-matching build exists, it falls back to the latest available build and prints a warning
uses the same resolved recipe for a forced local build, remote build, and every rebuild in the context
opens a cloud device session wired to the deep link

Normal revyl dev runs suppress advisory HMR diagnostics. Use revyl dev --debug when you specifically need relay/HMR troubleshooting output. In cloud-agent environments, keep the Revyl relay running after Dev loop ready and use device screenshots or revyl device report --session-id <id> --json as source of truth before switching to an external Expo tunnel. For Expo manifest readiness timeouts, use --force-hot-reload as the first diagnostic path. Revyl still starts Expo and verifies relay transport; the flag skips only the manifest and bundle proof so the device can be the source of truth. If the app loads, keep working. If the dev client shows a project load error, restart Expo/Metro or capture a session report with revyl device report --session-id <id> --json. For externally managed Expo tunnels, start Expo yourself and pass either the full dev-client link Expo prints or the raw https://... tunnel URL:

npx expo start --tunnel --dev-client
revyl dev --no-build --app-id <app-id> --tunnel "<deep-link-from-expo>"

When you pass the full Expo dev-client link, revyl dev uses its scheme and prefix directly, so selected-build metadata is not required. For a raw tunnel URL or normal startup, Expo scheme and prefix information comes from the selected build’s metadata. After the dev loop is running, use revyl device commands to interact:

revyl device screenshot
revyl device tap --target "Login button"
revyl device instruction "verify the dashboard loads"

Device-first flow

Start a plain device session first, then attach and run the dev loop on it:

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

When a context has an attached session, revyl dev --context <name> reuses it instead of provisioning a new device. Attached sessions are left running when the dev loop exits — use revyl device stop to end them.

Context management

revyl dev list                         # List dev contexts in the current worktree
revyl dev use ios-main                 # Switch the current context
revyl dev status                       # Show context status (JSON)
revyl dev rebuild                      # Trigger a rebuild
revyl dev stop                         # Stop the current context
revyl dev stop --all                   # Stop all contexts

Hot reload providers

Expo deep-links into a dev client via app_scheme; bare React Native loads the JS bundle directly over the Revyl→Metro relay. For provider config schema and the full per-framework setup walkthrough, see Dev Loop Overview.

New Branch Build Flow

Use this when you create a new branch and want revyl dev to run that branch’s build:

git checkout -b feature/new-login
revyl build --profile development --platform ios
revyl dev --profile development --platform ios

If you need to pin exactly one build:

revyl dev --build-version-id <build-id>

New Branch Direct File Flow (No Build Step)

Use this when you already have a local artifact and want to upload it without running the build command.

Build the artifact with your normal local or CI build command.
Upload it with revyl build upload --file.
Run revyl dev.

git checkout -b feature/new-login
revyl build upload --file build/dev-ios.tar.gz --platform ios
revyl dev --profile development --platform ios

Optional explicit version label:

revyl build upload --file build/dev-ios.tar.gz --platform ios --version feature-new-login-20260227-153000

Plain device sessions (no hot reload — these are the base layer revyl dev builds on):

revyl device start --platform ios
# Want hot reload? Run: revyl dev attach active

Builds and Dev Mode

All revyl build and revyl build upload commands push to an app container. For config-driven builds, that is the app_id on the resolved recipe. When Git metadata is available, each upload includes its branch and commit. When you run revyl dev, the CLI scans the selected recipe’s app for a build matching your current git branch. If found, it uses that build. If not, it falls back to the latest available build and prints a warning. Each developer gets their own cloud device session, relay, and local dev server — builds are the only shared resource. When you need a new build (by project type):

Expo / React Native: Dev mode serves your JS/TS live from your local Metro via a Revyl relay. The binary is just a “dev client shell.” You only need a new build when native dependencies change (new native modules, Podfile changes, Gradle dependency changes, app.json native config).
Swift: Every code change requires a new build. The binary is the app.
Kotlin/Android (coming soon): Every code change requires a new build.

Team workflow commands:

revyl build list --branch HEAD               # Does my branch have a build?
revyl build --profile development --platform ios  # Build/upload tagged with current branch
revyl dev --profile development --platform ios    # Use that recipe and branch build
revyl dev --build-version-id <id>            # Pin a specific build

Tip: For Expo/React Native, multiple developers can use the same dev build and still see their own code changes, since JS is served locally. For native projects, each developer should upload their own branch build.

App Management

An app is a named container for your uploaded builds (e.g. “My App Android”). Tests run against an app.

revyl app create --name "My App" --platform android   # Create an app
revyl app list                                         # List all apps
revyl app list --platform ios                          # Filter by platform
revyl app delete "My App"                              # Delete an app

Build Management

revyl build                              # Build from config and upload
revyl build --profile development --platform android  # Build one named recipe locally
revyl build --profile development --platform android --remote  # Same recipe on a cloud runner
revyl build upload --file ./app.apk --app <id>  # Upload a local artifact directly
revyl build upload --url <artifact-url> --app <id>  # Ingest from a remote URL
revyl build upload --file ./app.apk --app <id> --preview --json  # Also print a click-to-launch preview URL
revyl build list                         # List uploaded builds
revyl build list --app <app-id>          # List builds for a specific app

Direct builds select one customer-named profile and its ios or android recipe. There is no active/default profile. If an omitted value has one eligible choice, the CLI resolves it; otherwise interactive use prompts and non-interactive use fails with the available choices. Local and remote builds execute the same inherited recipe from the selected project root.

Remote Build Caches

revyl cache list                         # List configured caches
revyl cache delete <key>                 # Delete a configured cache

These commands manage configured path caches. Automatic compilation caches are controlled through the remote build configuration. See Caching.

Uploading a Build

Use revyl build any time you want to refresh the binary on Revyl without re-running tests. Common flow:

Make sure your app is configured and credentials are available.
Run:

cd your-app
revyl build --profile development --platform ios

When --version is omitted, the CLI defaults to a branch-aware version label: <branch-slug>-<timestamp> (for example feature-new-login-20260227-153000). In detached-head/non-git contexts it falls back to timestamp-only.

Use the uploaded binary by running tests against the latest upload:

revyl test run login-flow

Or let Revyl handle build + upload automatically:

revyl test run login-flow --build --profile development --platform ios

Useful companion commands:

revyl build list to verify uploads and inspect platform/app history
revyl test run <test> --build-id <id> to pin a specific build

For Expo projects, authenticate any tools named by the selected recipe before running the build. Revyl executes the authored command arrays without rewriting eas.json or switching EAS profiles.

Uploading from a URL

For teams that store builds in internal artifact storage (Artifactory, S3, GCS, GitHub Actions), the CLI can ingest an artifact directly from a URL without downloading it locally first:

# Public or pre-signed URL
revyl build upload --url https://artifacts.internal.company.com/builds/app-latest.ipa --app <id>

# Authenticated URL with custom headers
revyl build upload --url https://example.com/builds/app.apk \
  --header "Authorization: Bearer <token>" \
  --app <id>

# Multiple headers
revyl build upload --url https://example.com/builds/app.ipa \
  --header "Authorization: Bearer <token>" \
  --header "X-Custom-Header: value" \
  --app <id>

The backend downloads, validates, and stores the artifact server-side. The --url flag is mutually exclusive with --file.

Preview a just-uploaded build

--preview prints a URL that auto-starts a simulator with that exact build when a signed-in org member opens it. Upload itself does not start a device. Opening the link lands in the normal session viewer. The launch page reads platform from the uploaded build’s app. --json stays the same envelope and adds optional preview_url on the build object (/sessions/launch?buildId=<id>). Refreshing /sessions/launch while a start is in flight opens the same session; after that start settles, opening the durable URL again starts a new device. /sessions/launch?appId=<app_id> resolves the app’s latest build at open time instead of pinning one upload.

revyl build upload --file ./app.apk --app <id> --yes --preview --json

Native iOS: Build in Xcode, then `revyl dev`

For native iOS developers, revyl dev automatically detects the most recent simulator .app from Xcode DerivedData. Build your app in Xcode as you normally would, then run:

revyl dev                     # Auto-finds and uploads the local simulator build
revyl dev --build             # Force a rebuild from the configured build command
revyl dev --build-version-id <id>  # Pin a specific uploaded build

The discovery scans ~/Library/Developer/Xcode/DerivedData/<Project>-*/Build/Products/Debug-iphonesimulator/*.app for the most recently modified non-test .app that matches the project in the current directory. Test runner bundles (*Tests.app, *UITests.app) are automatically excluded.

Test Management

For the end-to-end CLI authoring workflow, see Test Configuration.

# Test lifecycle
revyl test create login-flow --platform android   # Create + auto-sync YAML to .revyl/tests/
revyl test create --from-session <session-id> login-flow --app <app-id>
revyl test run login-flow                          # Run a test
revyl test run login-flow --no-open                # Keep a blocking terminal run from opening its completed report
revyl test run login-flow --no-inherited-launch-vars # Ignore inherited launch-variable IDs
revyl test open login-flow                         # Open test in browser editor
revyl test rename login-flow new-login-flow        # Rename while preserving history
revyl test duplicate login-flow                    # Clone an existing test
revyl test delete login-flow                       # Delete a test
revyl test cancel <task-id>                        # Cancel a running test

# Sync & inspect
revyl test sync                   # Reconcile local and remote tests
revyl test sync --dry-run         # Preview test reconciliation changes
revyl test sync --prune           # Reconcile tests and prune stale mappings
revyl test list                   # Show local tests with sync status
revyl test remote                 # List all tests in your organization
revyl test push                   # Push local changes to remote
revyl test pull                   # Pull remote changes to local
revyl test diff login-flow        # Show diff between local and remote

# Execution status & reports
revyl test status login-flow                       # Latest execution status
revyl test history login-flow                      # Execution history (table)
revyl test report login-flow                       # Detailed report (latest execution)
revyl test report <task-uuid> --json               # Report by task ID, JSON output
revyl test report login-flow --no-steps            # Summary only, no step breakdown
revyl test share login-flow                        # Generate shareable report link
revyl test share login-flow --open                 # Share link and open in browser

# Versioning
revyl test versions login-flow                     # Show saved versions for a test
revyl test restore login-flow                      # Restore to a previous version

# YAML-first creation (requires .revyl/config.yaml)
revyl test create login-flow --from-file ./login-flow.yaml
revyl test create --from-session <session-id> login-flow --app <app-id>
revyl test push login-flow --force

# Per-command flags
#   --dry-run    Available on: test create, test push, test pull

# Live verify during a dev session, then promote to a regression
revyl dev
revyl device validation -s 0 "Home screen is visible"
revyl test create login-flow --from-session <session-id>
revyl test run login-flow

revyl sync is a deprecated compatibility alias for revyl test sync. Both forms reconcile tests only. Project configuration remains explicit through revyl init, revyl config pull, and revyl config push.

Test Variables

Per-test variables referenced in step descriptions via {{name}} syntax and substituted at runtime. Names may contain letters, numbers, hyphens, or underscores.

revyl test var list login-flow                              # List variables on a test
revyl test var get login-flow username                      # Read a single value
revyl test var set login-flow [email protected] # Add or update (upsert)
revyl test var set login-flow "password=my secret"          # Values may contain spaces
revyl test var set login-flow otp-code                      # Name-only (runtime-filled)
revyl test var rename login-flow old-name new-name          # Preserve value, change name
revyl test var delete login-flow username                   # Delete one
revyl test var clear login-flow                             # Delete ALL (needs --force in non-TTY)

Test variables are distinct from Global Variables (org-wide {{global.name}}) and Global Launch Variables (org-wide reusable launch env vars).

Module Management

Reusable modules can be imported into tests with module_import blocks. For examples, see Creating Tests.

revyl module list                                  # List modules
revyl module list --search login                   # Filter modules by name/description
revyl module get login                             # Show module blocks and metadata
revyl module create login-flow --from-file blocks.yaml
revyl module update login --from-file new-blocks.yaml
revyl module insert login                          # Print a module_import YAML snippet
revyl module usage login                           # Show tests that import this module
revyl module versions login                        # List saved versions (who changed what and when)
revyl module restore login --version 2             # Restore blocks + metadata to a prior version
revyl module delete login                          # Delete a module

Scripts

Manage code-execution scripts used by code_execution blocks in tests. Supported runtimes: python, javascript, typescript, bash.

revyl script list                                             # List all scripts
revyl script list --runtime python                            # Filter by runtime
revyl script list --json                                      # JSON output
revyl script get my-validator                                 # Show metadata + source
revyl script create my-validator --runtime python --file validate.py
revyl script create price-check --runtime javascript --file check.js --description "Validate prices"
revyl script update my-validator --file validate.py           # Replace source
revyl script update my-validator --name new-name              # Rename
revyl script update my-validator --description "Updated"      # Change description
revyl script delete my-validator --force                      # Delete
revyl script usage my-validator                               # Show tests that use this script
revyl script insert my-validator                              # Print a code_execution YAML snippet

File Management

Manage files (certificates, configs, images, media) in your organization’s file library. Tests reference uploaded files via revyl-file:// URIs.

revyl file list                                               # List files
revyl file list --limit 10 --offset 20                        # Paginate
revyl file upload ./certs/staging.pem                         # Upload a file
revyl file upload ./config.json --name "App Config" --description "Feature flags"
revyl file download staging.pem                               # Download to ./staging.pem
revyl file download staging.pem ./certs/                      # Download into a directory
revyl file download staging.pem ./renamed.pem                 # Download to exact path
revyl file edit staging.pem --name "prod-cert.pem"            # Rename
revyl file edit staging.pem --file ./new-cert.pem             # Replace content (preserves ID)
revyl file delete staging.pem --force                         # Delete

Supported types (with size limits): certificates .pem .cer .crt .key .p12 .pfx .der (50 MB), config .json .xml .yaml .yml .toml .csv .txt .conf .cfg .ini .properties (50 MB), images .png .jpg .jpeg .gif .pdf (250 MB), media .mp4 .mp3 (500 MB).

Global Resources

Org-wide resources available across all tests.

Global Variables

Shared variables referenced via {{global.name}}. Local test variables with the same name take precedence. Use --secret for credentials or tokens; secret values are encrypted and shown as ******** in list/get output.

revyl global var list                                         # List all
revyl global var get login-email                              # Read one (secrets are masked)
revyl global var set [email protected]         # Add or update (upsert)
revyl global var set "password=my secret" --secret            # Store as encrypted secret
revyl global var set "password=new value" --no-secret         # Convert/update as plaintext
revyl global var set otp-code                                 # Name-only (runtime-filled)
revyl global var delete login-email                           # Delete

Global Launch Configuration

Reusable launch configurations are stored at the org level and attached to tests from the web UI. Environment configurations hold key-value startup settings. iOS argument sets hold exact ordered argv tokens and are created and edited in Library > Launch Configurations. Either type can be secret. Getting started with raw device sessions:

revyl global launch-var create API_URL=https://staging.example.com
revyl device start --platform ios --launch-var API_URL

Create an environment configuration with a KEY=VALUE pair, then pass its key or UUID to --launch-var. Select a stored iOS argument set by name or UUID with repeatable --launch-arg-set. Append non-secret inline tokens with repeatable --launch-arg=<token>.

revyl global launch-var list                                  # Show non-secret values; secrets stay masked
revyl global launch-var get API_URL                           # Show one
revyl global launch-var create API_URL=https://staging.example.com
revyl global launch-var create API_TOKEN=token --secret       # Store encrypted; never readable
revyl global launch-var create DEBUG=true --description "Enable debug startup"
revyl global launch-var update API_URL --value https://prod.example.com
revyl global launch-var update API_URL --secret               # Encrypt the current plaintext value
revyl global launch-var update API_TOKEN --secret=false --value replacement
revyl global launch-var update API_URL --key API_BASE_URL --description "Shared API endpoint"
revyl global launch-var delete API_URL --force                # Also detaches from any tests

Aliases: launch-var, launch-vars, launch-variable.

Workflow Management

# Lifecycle
revyl workflow list                                              # List all workflows
revyl workflow list --json                                       # JSON output
revyl workflow info smoke-tests                                  # Tests, overrides, run config, last run
revyl workflow create smoke-tests --tests login-flow,checkout    # Create workflow
revyl workflow add-tests smoke-tests payment                     # Add test(s) to workflow
revyl workflow remove-tests smoke-tests checkout                 # Remove test(s) from workflow
revyl workflow rename smoke-tests regression-smoke               # Rename (preserves history)
revyl workflow run smoke-tests                                   # Run workflow
revyl workflow run smoke-tests --no-open                         # Keep a blocking terminal run from opening its completed report
revyl workflow run smoke-tests --build                           # Build + upload before running
revyl workflow run smoke-tests --build --profile development --platform ios
revyl workflow run smoke-tests --ios-app <uuid> --android-app <uuid>  # Override apps for this run
revyl workflow run smoke-tests --location "37.7749,-122.4194"    # Override GPS for this run
revyl workflow run smoke-tests --launch-var API_URL              # Stored variable key (UUID also accepted)
revyl workflow run smoke-tests --launch-env FEATURE_PREVIEW=true # Inline launch var for every test
revyl workflow run smoke-tests --launch-arg-set AuthTestArgs      # Stored iOS argument set
revyl workflow run smoke-tests --launch-arg=--route --launch-arg="sign in" # Exact inline tokens
revyl workflow run smoke-tests --no-inherited-launch-vars        # Ignore inherited launch-variable IDs
revyl workflow open smoke-tests                                  # Open in browser
revyl workflow delete smoke-tests                                # Delete workflow
revyl workflow cancel <task-id>                                  # Cancel running workflow

# Execution status & reports
revyl workflow status smoke-tests                                # Latest execution status
revyl workflow history smoke-tests                               # Execution history (table)
revyl workflow report smoke-tests                                # Detailed report (latest)
revyl workflow report <task-uuid> --json                         # Report by task ID, JSON
revyl workflow share smoke-tests                                 # Generate shareable link
revyl workflow share smoke-tests --open                          # Share and open in browser

Blocking human-terminal test and workflow runs open their completed report by default. Use --no-open to suppress it. No-wait, JSON, GitHub Actions, CI, SSH, and other headless executions never open a browser, even when --open is present. All four launch flags are repeatable. For duplicate keys, inline --launch-env values override --launch-var, and --launch-var overrides values attached to an individual test. Prefer stored --launch-var values for secrets because inline values are non-secret and may be visible in shell history, process arguments, and execution reports. Stored argument sets are flattened in attachment/flag order, then inline tokens are appended in flag order. Mixed workflows skip argument sets for Android children; Android-only runs reject them.

Workflow Settings

Stored overrides and run configuration that apply to every execution of a workflow.

# Location override (all tests in workflow use this GPS)
revyl workflow location set my-workflow --lat 37.7749 --lng -122.4194
revyl workflow location show my-workflow
revyl workflow location clear my-workflow

# App override (per platform)
revyl workflow app set my-workflow --ios <app-uuid>
revyl workflow app set my-workflow --android <app-uuid>
revyl workflow app set my-workflow --ios <ios-uuid> --android <android-uuid>
revyl workflow app show my-workflow
revyl workflow app clear my-workflow

# Run config (parallelism, retries)
revyl workflow config show my-workflow
revyl workflow config set my-workflow --parallel 3 --retries 2

Workflow Quarantine

Quarantined tests still run but their failures are ignored when computing overall workflow pass/fail — useful for unblocking CI while flaky tests are investigated.

revyl workflow quarantine list smoke-tests                             # Show tests and status
revyl workflow quarantine add smoke-tests login-flow                   # Quarantine one
revyl workflow quarantine add smoke-tests login-flow checkout payment  # Quarantine several
revyl workflow quarantine remove smoke-tests login-flow                # Unquarantine

GitHub PR Automation

Connect the Revyl GitHub App and configure PR automation for the project root selected by the nearest .revyl/config.yaml.

revyl github connect                     # Install or verify GitHub repository access
revyl github status                      # Show the GitHub App connection status
revyl github setup                       # Configure the selected project root
revyl -C apps/mobile github setup        # Configure a nested monorepo project

github connect only installs or verifies repository access. It never edits or publishes project configuration.
github setup guides the selected project through a managed-profile or finished-artifact CI-upload policy, writes pr_review, and validates the project config. Under manual authority, it confirms publication and publishes the same complete aggregate as revyl config push. Under Git authority, it prepares the designated file for commit without publishing.
GitHub installation is repository-wide, while setup, publication, authority, and reconciliation are project-root-specific. Run setup separately from each intended root in a monorepo.
Ordinary config push uses an absent-or-hash precondition and is rejected when the project is managed from its designated default-branch config. github setup prepares the designated file for commit in that mode. Run revyl config validate and commit the file, or use revyl config push --force for a deliberate one-time publication that keeps default-branch management enabled.
A successful default-branch reconciliation makes that project Git-owned. Fetch or validation failures preserve its current state. Removing the designated file returns only that project to manual authority while retaining its last accepted aggregate and automation; it does not delete the project.

Project roots are immutable. Manual projects can be deleted from the GitHub integration in the web app and recreated at the correct root. Git-owned projects must first return to manual authority through the designated-file flow above. Deletion preserves the repository connection, GitHub installation, repository report destination, historical results, and already-frozen review and build work, which may finish. Pending Cursor proof that has not launched fails closed because deletion removes its live authorization. Deleting the last project shows No projects configured and Add project. There is no CLI project-delete command; after creating a same-root replacement, use revyl -C <replacement-root> config pull to back up and replace a stale local file. Pull adopts a replacement automatically only when exactly one active project owns the old root; otherwise Revyl does not assume where the replacement belongs. The standalone github init and github push commands no longer exist; config push is the direct publication command and never scaffolds. See the GitHub integration for the pr_review schema and the exact server-stored configuration groups.

Device Management

# Session lifecycle
revyl device start                             # Start a cloud device session (defaults to iOS)
revyl device start --platform android --open   # Start and open viewer in browser
revyl device start --platform ios --app-url https://example.com/app.ipa # Start a raw session with a preinstalled app
revyl device start --platform ios --launch-var API_URL --launch-var DEBUG # Stored variable keys (UUIDs also accepted)
revyl device start --platform ios --launch-arg-set AuthTestArgs --launch-arg=--debug # Stored set, then inline token
revyl device start --platform ios --no-inherited-launch-vars # Ignore inherited launch-variable IDs
revyl device start --device-name revyl-ios-iphone  # Use a named device preset
revyl device start --device-model "iPhone 16" --os-version "iOS 18.5"  # Specific model + runtime
revyl device stop                              # Stop the active session
revyl device stop --all                        # Stop all sessions
revyl device list                              # List all active sessions
revyl device use <index>                       # Switch active session
revyl device attach <session-id>               # Attach to an existing session by ID
revyl device info                              # Show session details (includes `whep_url` in JSON when available)
revyl device history                           # Show recent device session history
revyl device doctor                            # Run session diagnostics
revyl device targets                           # List available device models and OS versions
revyl device targets --platform android --json # Filter / JSON output

# Interaction (use --target for AI grounding, or --x/--y for coordinates)
revyl device tap --target "Login button"                         # AI-grounded tap
revyl device tap --x 200 --y 400                                 # Coordinate tap
revyl device double-tap --target "item"                          # Double-tap
revyl device long-press --target "icon" --duration 1500          # Long press (ms)
revyl device type --target "Email field" --text "[email protected]"  # Type text
revyl device swipe --target "list" --direction down              # Swipe gesture
revyl device drag --start-x 100 --start-y 200 --end-x 300 --end-y 400  # Drag

# Utility
revyl device screenshot                        # Capture screenshot
revyl device screenshot --out screen.png       # Save to file
revyl device wait --duration-ms 1000           # Fixed wait on the session
revyl device pinch --x 200 --y 400 --scale 1.5 # Pinch / zoom gesture
revyl device clear-text --target "Search"      # Clear text in a field
revyl device back                              # Android back / provider back action
revyl device key --key ENTER                   # ENTER or BACKSPACE
revyl device shake                             # Trigger shake gesture
revyl device home                              # Return to home screen
revyl device open-app --app settings           # Open a system app
revyl device navigate --url https://example.com # Open URL or deep link
revyl device set-location --lat 37.77 --lon -122.42 # Set GPS location
revyl device download-file --url https://example.com # Download file to device
revyl device download-file --url https://example.com --filename report.pdf # Override destination filename
revyl device install --app-url <url>           # Install app from URL
revyl device launch                            # Launch the app this session installed
revyl device launch --bundle-id com.app.id     # Launch a specific installed app
revyl device kill-app                          # Kill the current installed app

# Live step execution on an active session
revyl device instruction "Open Settings and tap Wi-Fi"           # Execute one instruction step
revyl device validation "Verify the Settings title is visible"   # Execute one validation step
# A false/missing validation verdict exits non-zero; --json stdout remains parseable with success=false
revyl device extract "Extract the visible account email" --variable-name account_email # Execute one extract step
revyl device code-execution script_123                          # Execute one code-execution step

# UI inspection
revyl device hierarchy                         # Dump UI hierarchy (Android XML / iOS JSON)

# Live observability (perf, network, logs) and post-session artifacts
revyl device perf                              # Stream CPU% / memory / FPS from active session
revyl device requests                          # Stream live network requests
revyl device logs                              # Stream captured device logs (logcat / OSLog)
revyl device logs --no-follow                  # Single snapshot of recent log lines
revyl device logs --json | jq -r '.items[]'    # JSON per poll; pipe to jq for scripting
revyl device network --disconnected            # Toggle airplane mode (network off)
revyl device network --connected               # Restore network
revyl device report                            # View the report for the active session
revyl device report --session-id <uuid>        # View report by session ID
revyl device report --artifact perf --download # Download a session artifact (perf|network|trace)

See Live Observability for the full reference on perf, requests, logs, report --artifact, network, and --device-name presets. For raw device sessions, URL-based app flows work in two modes:

revyl device start --app-url ... preinstalls the app before the session is ready.
To inject launch config at boot, use --launch-var <key-or-id> for stored environment values, --launch-arg-set <name-or-id> for stored iOS argument sets, and --launch-arg=<token> for non-secret inline iOS tokens.
revyl device install --app-url ... installs into an already running raw session.
revyl device download-file --url ... only downloads the file to device storage; it does not install the app.

Live Stream URL

Every active session streams the device screen over WebRTC. The --json output from device info and device list includes a whep_url field — a standard WHEP playback URL you can embed in your own platform or feed into any WHEP-compatible player.

# Get the raw stream URL for the active session
revyl device info --json | jq -r '.whep_url'

# List all sessions with their stream URLs
revyl device list --json | jq '.[].whep_url'

Device Session Flags

-s <index|id>       # Target a session by local index or server-issued session ID
--session-id <uuid> # Target a session by server-issued ID (explicit spelling)
--json              # Output as JSON (useful for scripting)
--timeout <secs>    # Idle timeout for start (default: 300)

Every revyl device command that acts on a session accepts both spellings. -s takes either form: -s 2 is a local index from revyl device list, while -s 9f3c1a2b-... is the server-issued session_id returned by revyl device start --json. REVYL_SESSION_ID scopes an entire shell to one session, so batch workers do not have to repeat the flag:

export REVYL_SESSION_ID=9f3c1a2b-4d5e-4f60-8a71-b2c3d4e5f607
revyl device screenshot --out screen.png

Precedence is --session-id, then -s, then REVYL_SESSION_ID, then the active local session. Setting --session-id and -s to different sessions is an error rather than a silent pick. REVYL_SESSION_ID applies only to commands that accept -s. The revyl dev commands pick their session from the dev context instead, so exporting it for a batch leaves them alone. revyl device stop --all ignores REVYL_SESSION_ID, -s, and --session-id and still stops every session revyl device list would show. Use a per-ID device stop when a batch worker should release only its own device.

Local indexes live in a per-project file that every CLI process in the directory shares. Writes to it are serialized, so concurrent device start runs no longer drop each other’s sessions, but an index still only means anything relative to that file. Session IDs are resolved straight from the backend in a single call and never touch the file, so prefer them for anything running more than one session at a time.

Parallel batches

Start each session, keep its session_id, and drive every later command by ID:

SESSION_A=$(revyl device start --platform ios --json | jq -r '.session_id')
SESSION_B=$(revyl device start --platform ios --json | jq -r '.session_id')

revyl device instruction "Sign in as the test user" -s "$SESSION_A" --json &
revyl device instruction "Open the settings tab" -s "$SESSION_B" --json &
wait

revyl device stop -s "$SESSION_A"
revyl device stop -s "$SESSION_B"

# Or stop every session. --all ignores REVYL_SESSION_ID.
# revyl device stop --all

Shell Completion

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

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

# Fish
revyl completion fish | source

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

Diagnostics & Utilities

revyl doctor     # Check CLI health, connectivity, auth, sync status
revyl ping       # Test API connectivity and latency
revyl upgrade    # Check for and install CLI updates; refresh existing agent skills after successful upgrades
revyl --version  # Show CLI version (short format)
revyl version    # Show version, commit, and build date (--json for CI)
revyl docs       # Open Revyl documentation in browser
revyl schema     # Display CLI command schema (for integrations)
revyl mcp serve                         # Start MCP server for AI agent integration (legacy flat mode)
revyl mcp serve --profile dev           # 11 focused setup, dev-loop, and device tools
revyl mcp serve --profile core          # Broad device + test/build compatibility surface
revyl mcp serve --profile full          # Core plus workflow/module/script/tag/file/variable management
revyl skill list                                      # List first-class skills
revyl skill install --force                          # Install recommended skills
revyl skill install --name revyl-cli-dev-loop --force # Dev loop + device exploration
revyl skill install --name revyl-cli-atlas --force    # Visual Atlas understanding
revyl skill install --name revyl-cli-create --force   # Stable YAML test authoring
revyl skill install --name revyl-cli-auth-bypass --force # Auth bypass setup
revyl skill install --cursor --force                 # Force Cursor if auto-detect is ambiguous
revyl skill install --codex --force                  # Force Codex if auto-detect is ambiguous
revyl skill install --claude --force                 # Force Claude Code if auto-detect is ambiguous
revyl skill show --name revyl-cli-dev-loop           # Print a named skill to stdout
revyl skill show --name revyl-cli-atlas              # Print the Atlas visual workflow
revyl skill export --name revyl-cli-create -o FILE   # Export a named skill to a file
make device-prod-smoke-ios    # Local iOS branch smoke against production device relay
make device-prod-smoke-android # Local Android branch smoke against production device relay
make device-prod-sdk-smoke-ios # Local iOS SDK smoke against production
make device-prod-sdk-smoke-android # Local Android SDK smoke against production

Global Flags

These flags are available on all commands:

--debug       # Enable debug logging
--json        # Output as JSON (where supported)
--version     # Show CLI version and exit
--quiet / -q  # Suppress non-essential output

​Authentication

​Project Setup

​Project Config

​Inherited Launch Configuration

​Running Tests

​Advanced Run Flags

​Explore

​Dev Loop

​Device-first flow

​Context management

​Hot reload providers

​New Branch Build Flow

​New Branch Direct File Flow (No Build Step)

​Builds and Dev Mode

​App Management

​Build Management

​Remote Build Caches

​Uploading a Build

​Uploading from a URL

​Preview a just-uploaded build

​Native iOS: Build in Xcode, then revyl dev

​Test Management

​Test Variables

​Tags

​Module Management

​Scripts

​File Management

​Global Resources

​Global Variables

​Global Launch Configuration

​Workflow Management

​Workflow Settings

​Workflow Quarantine

​GitHub PR Automation

​Device Management

​Live Stream URL

​Device Session Flags

​Parallel batches

​Shell Completion

​Diagnostics & Utilities

​Global Flags

Authentication

Project Setup

Project Config

Inherited Launch Configuration

Running Tests

Advanced Run Flags

Explore

Dev Loop

Device-first flow

Context management

Hot reload providers

New Branch Build Flow

New Branch Direct File Flow (No Build Step)

Builds and Dev Mode

App Management

Build Management

Remote Build Caches

Uploading a Build

Uploading from a URL

Preview a just-uploaded build

Native iOS: Build in Xcode, then `revyl dev`

Test Management

Test Variables

Tags

Module Management

Scripts

File Management

Global Resources

Global Variables

Global Launch Configuration

Workflow Management

Workflow Settings

Workflow Quarantine

GitHub PR Automation

Device Management

Live Stream URL

Device Session Flags

Parallel batches

Shell Completion

Diagnostics & Utilities

Global Flags