Skip to main content
This page provides a complete reference for all Revyl CLI commands, flags, and configuration options.

Global Flags

These flags work with any command:
FlagShortDescription
--debugEnable debug logging
--devUse local development servers
--jsonOutput results as JSON (where supported)
--quiet-qSuppress non-essential output

Authentication Commands

revyl auth login

Authenticate with your API key.
revyl auth login
Prompts for your API key, validates it, and stores credentials in ~/.revyl/credentials.json.

revyl auth logout

Remove stored credentials.
revyl auth logout

revyl auth status

Show current authentication status.
revyl auth status [flags]
FlagDescription
--jsonOutput as JSON
Displays: email, user ID, organization ID, and masked API key.

Project Commands

revyl init

Initialize a project for Revyl CLI usage.
revyl init [flags]
FlagDescription
--project <id>Link to a specific Revyl project
-y, --non-interactiveSkip interactive wizard, generate config only
--hotreloadConfigure hot reload for an existing initialized project and exit
--detectOnly detect build system, don’t create files
--forceOverwrite existing configuration
Launches a 7-step interactive wizard: project setup, authentication, create apps (with conflict handling and pagination), hot reload setup, first build (with artifact path override), create test (with link/rename/skip on conflict + YAML auto-sync), and create workflow.

Sync Commands

revyl sync

Reconcile local tests, workflows, and app links in .revyl/config.yaml with your organization state.
revyl sync [flags]
FlagDescription
--testsSync tests only
--workflowsSync workflows only
--appsSync build platform app_id links only
--non-interactiveDisable prompts and apply deterministic defaults
--interactiveForce prompts (requires TTY stdin)
--pruneAuto-prune stale/deleted mappings
--dry-runShow planned actions without writing files
--skip-hotreload-checkSkip hot reload dev_client_build_id validation
--jsonOutput results as JSON
If no domain flags are provided, revyl sync runs tests + workflows + app links. Examples:
revyl sync
revyl sync --tests
revyl sync --workflows --apps
revyl sync --non-interactive --prune
revyl sync --dry-run --json

Publishing Commands (iOS / TestFlight)

revyl publish auth ios

Configure App Store Connect credentials.
revyl publish auth ios --key-id <id> --issuer-id <uuid> --private-key <path-to-p8>
FlagDescription
--key-id <id>App Store Connect API key ID
--issuer-id <uuid>App Store Connect issuer ID
--private-key <path>Path to .p8 private key
Also supports env vars: REVYL_ASC_KEY_ID, REVYL_ASC_ISSUER_ID, REVYL_ASC_PRIVATE_KEY_PATH, REVYL_ASC_PRIVATE_KEY.

revyl publish auth status

Show iOS/Android publishing credential status.
revyl publish auth status

revyl publish testflight

Upload/distribute iOS builds to TestFlight.
revyl publish testflight [flags]
FlagDescription
--ipa <path>Path to .ipa to upload (optional)
--group <a,b,c>Comma-separated TestFlight groups
--whats-new <text>”What to Test” notes
--version <value>Version override for upload
--build-number <value>Build number override for upload
--app-id <id>App Store Connect app ID
--waitWait for processing before distribution (default: true)
--timeout <duration>Processing timeout (default: 30m)
Defaults can come from .revyl/config.yaml (publish.ios.*) and env vars (REVYL_ASC_APP_ID, REVYL_TESTFLIGHT_GROUPS).

revyl publish status

Check iOS App Store Connect build/review status.
revyl publish status [flags]
FlagDescription
--platform <ios|android>Platform to check (ios supported today)
--build-id <id>Specific build ID
--app-id <id>App Store Connect app ID
For a complete guide, see iOS Publishing (TestFlight).

Test Management Commands

revyl test list

List local tests with sync status.
revyl test list [flags]
FlagDescription
--jsonOutput as JSON

revyl test remote

List all tests in your organization.
revyl test remote [flags]
FlagDescription
--limit <n>Limit number of results
--platform <ios|android>Filter by platform
--jsonOutput as JSON

revyl test pull

Pull tests from remote to local.
revyl test pull [name] [flags]
FlagDescription
--forceOverwrite local changes
--dry-runShow what would be pulled

revyl test push

Push local tests to remote.
revyl test push [name] [flags]
FlagDescription
--forceOverwrite remote changes
--dry-runShow what would be pushed

revyl test diff

Show differences between local and remote.
revyl test diff <name>

revyl test validate

Validate YAML test files.
revyl test validate [file] [flags]
FlagDescription
--jsonOutput results as JSON

Create Commands

revyl test create

Create a new test.
revyl test create <name> [flags]
FlagDescription
--platform <ios|android>Target platform (required)
--build-var <id>Associate with build variant
--from-file <path>Create from YAML file (copies to .revyl/tests/ and pushes)
--no-openDon’t open in browser
--no-syncDon’t sync to remote
--forceOverwrite if exists
--dry-runShow what would be created

revyl workflow create

Create a new workflow.
revyl workflow create <name> [flags]
FlagDescription
--tests <names>Comma-separated test names to include
--no-openDon’t open in browser
--no-syncDon’t sync to remote
--dry-runShow what would be created

Execution Commands

revyl run

Build and run a test or workflow in one command (recommended shortcut).
revyl run <name> [flags]
By default, builds and uploads the app, then runs the named test. Use -w/--workflow to run a workflow instead of a test. Use --no-build to skip the build step.
FlagShortDescription
--workflow-wRun a workflow instead of a test
--no-buildSkip build step; run against last uploaded build
--platform <name>Build platform to use (e.g. ios, android)
--openOpen report in browser when complete
--timeout <seconds>-tTimeout in seconds (default: 3600)
--retries <n>-rRetry attempts (1-5)
--jsonOutput results as JSON
--verbose-vShow detailed output
--no-waitQueue and exit without waiting
--hotreloadRun against local dev server (Expo)
--build-id <id>Run against a specific build version
Examples:
revyl run login-flow              # Build, upload, then run test
revyl run login-flow --no-build    # Run test without rebuilding
revyl run smoke-tests -w           # Build, upload, then run workflow
revyl run smoke-tests -w --no-build   # Run workflow without rebuilding

revyl test run

Run a single test.
revyl test run <name|id> [flags]
FlagDescription
--buildBuild and upload before running
--platform <name>Build platform to use (requires --build, or used with --hotreload)
--build-version-id <id>Run against specific build version
--retries <n>Number of retry attempts (default: 1)
--timeout <seconds>Maximum execution time (default: 600)
--no-waitQueue and exit immediately
--openOpen report in browser when complete
--jsonOutput as JSON
--verboseShow detailed logs
--github-actionsFormat for GitHub Actions
Execution Status: During execution, the CLI shows real-time status updates:
  • Setting up device… - Device is being acquired and initialized
  • running [X/Y steps] - Test is actively executing steps
Cancellation: Press Ctrl+C to cancel a running test. The CLI will:
  1. Send a cancellation request to the server
  2. Stop the test execution on the device
  3. Display “Test cancelled by user”
Use revyl run <name> to build, upload, and run a test in one command. Use revyl run <name> -w for a workflow.

revyl workflow run

Run a workflow.
revyl workflow run <name|id> [flags]
FlagDescription
--buildBuild and upload before running workflow
--platform <name>Build platform to use (requires --build)
--retries <n>Number of retry attempts (default: 1)
--timeout <seconds>Maximum execution time (default: 600)
--no-waitQueue and exit immediately
--openOpen report in browser when complete
--verboseShow detailed logs
--github-actionsFormat for GitHub Actions
--jsonOutput as JSON
Execution Status: During execution, the CLI shows real-time status updates:
  • Setting up device… - Device is being acquired and initialized
  • running [X/Y tests] - Workflow is actively running tests
Cancellation: Press Ctrl+C to cancel a running workflow. The CLI will:
  1. Send a cancellation request to the server
  2. Cancel all running and queued tests in the workflow
  3. Display “Workflow cancelled by user”

revyl test

Parent command for test management operations.
revyl test [command]
Available subcommands:
  • list - List tests with sync status
  • remote - List all tests in your organization
  • push - Push local test changes to remote
  • pull - Pull remote test changes to local
  • diff - Show diff between local and remote
  • validate - Validate YAML test files
  • run - Run a test
  • create - Create a new test
  • delete - Delete a test
  • open - Open a test in the browser
  • cancel - Cancel a running test
To build and run a test, use revyl run <name>. To build and run a workflow, use revyl run <name> -w. For more options, use revyl test run <name> or revyl workflow run <name>.

revyl workflow

Full pipeline: build → upload → run workflow.
revyl workflow <name|id> [flags]
FlagDescription
--platform <name>Build platform to use
--skip-buildSkip build step
--retries <n>Retry attempts for each test
--no-waitDon’t wait for completion
--openOpen report when complete
--timeout <seconds>Workflow timeout
--jsonJSON output
revyl workflow (with no subcommand) runs the full pipeline (build then run). Use revyl workflow run with --build when you want to build first, or without for quick re-runs against existing builds.

Build Commands

revyl build upload

Build and upload an app artifact.
revyl build upload [flags]
FlagDescription
--skip-buildUpload existing artifact
--version <string>Version label (default: git SHA)
--set-currentSet as current build
--platform <ios|android>Platform to build for
--name <string>Custom build name
--build-var <id>Build variant ID
--yesSkip confirmation prompts
--dry-runShow what would be uploaded
--jsonJSON output

revyl build list

List uploaded build versions.
revyl build list [flags]
FlagDescription
--platform <ios|android>Filter by platform
--build-var <id>Filter by build variant
--jsonJSON output

revyl build delete

Delete a build.
revyl build delete <app-id> [flags]
FlagDescription
--version <id>Delete a specific build version (otherwise deletes all versions)
--jsonJSON output

Open Commands

revyl test open

Open a test in the browser.
revyl test open <name|id>

revyl workflow open

Open a workflow in the browser.
revyl workflow open <name|id>

Hot Reload Commands

revyl init --hotreload

Configure or reconfigure hot reload for an existing initialized project.
revyl init --hotreload
This mode auto-detects your project type and writes hot reload settings under .revyl/config.yaml.

Hot Reload Flags

These flags work with test run, test create, and test open:
FlagDescription
--hotreloadEnable hot reload mode
--platform-key <name>Build platform key for dev client
--build-version-id <id>Explicit build version ID
--provider <name>Hot reload provider to use
--port <number>Override dev server port
Example:
revyl test run login-flow --hotreload --platform ios-dev
revyl test create checkout --hotreload --platform-key ios-dev --platform ios
revyl test open login-flow --hotreload --platform-key ios-dev
See Hot Reload documentation for complete setup guide.

Cancel Commands

revyl test cancel

Cancel a running test execution.
revyl test cancel <task_id>
FlagDescription
--jsonJSON output
The task ID is shown when you start a test (Task ID: abc123...) or in the report URL.
If you’re watching a test run in the terminal, simply press Ctrl+C to cancel it. The revyl test cancel command is useful for cancelling tests started with --no-wait or from another terminal.

revyl workflow cancel

Cancel a running workflow and all its child tests.
revyl workflow cancel <task_id>
FlagDescription
--jsonJSON output
If the test or workflow has already completed, failed, or been cancelled, the command will return an error with the current status.

Delete Commands

revyl test delete

Delete a test.
revyl test delete <name|id>
FlagDescription
--jsonJSON output
Deletes the test from your organization. The test must not be currently running. Local YAML files in .revyl/tests/ are not removed automatically.

revyl workflow delete

Delete a workflow.
revyl workflow delete <name|id>
FlagDescription
--jsonJSON output
Deletes the workflow from your organization. Individual tests within the workflow are not deleted.

Shell Completion

revyl completion

Generate shell completion scripts for tab-completion of commands, flags, and arguments.
# Add to ~/.bashrc
source <(revyl completion bash)

Diagnostic Commands

revyl doctor

Run diagnostic checks.
revyl doctor [flags]
FlagDescription
--jsonJSON output
Checks: version, authentication, API connectivity, config, build system, sync status. The sync status check verifies local test and workflow IDs against the server, reporting any that have been deleted remotely or exist only on the server.

revyl ping

Test API connectivity.
revyl ping [flags]
FlagDescription
--jsonJSON output

revyl version

Show version information.
revyl version [flags]
FlagDescription
--jsonOutput version, commit, and build date as JSON

revyl upgrade

Check for and install updates.
revyl upgrade [flags]
FlagDescription
--checkCheck only, don’t install
--forceForce reinstall
--prereleaseInclude prerelease versions
--jsonJSON output

revyl docs

Open documentation in browser.
revyl docs

Device Commands

Direct device interaction: provision cloud-hosted Android/iOS devices and control them from the CLI. See the Device Commands guide for detailed usage, examples, and AI grounding concepts.

revyl device start

Provision and start a new cloud device session.
revyl device start --platform <ios|android> [flags]
FlagDefaultDescription
--platformPlatform: ios or android (required)
--timeout300Idle timeout in seconds
--openfalseOpen viewer in browser
--jsonfalseOutput as JSON

revyl device stop

Stop a device session.
revyl device stop [flags]
FlagDefaultDescription
-s-1Session index (-1 = active)
--allfalseStop all sessions
--jsonfalseOutput as JSON

revyl device list

List all active device sessions.
revyl device list [flags]
FlagDescription
--jsonOutput as JSON

revyl device use

Switch the active session.
revyl device use <index>

revyl device info

Show session details (ID, platform, viewer URL, uptime).
revyl device info [flags]
FlagDefaultDescription
-s-1Session index
--jsonfalseOutput as JSON

revyl device doctor

Run diagnostics on auth, session, worker, and device health.
revyl device doctor [flags]
FlagDefaultDescription
-s-1Session index

revyl device screenshot

Capture a device screenshot.
revyl device screenshot [flags]
FlagDefaultDescription
--outOutput file path
-s-1Session index
--jsonfalseOutput as JSON

revyl device tap

Tap an element by description or coordinates.
revyl device tap [flags]
FlagDefaultDescription
--targetElement description (AI grounded)
--x0X coordinate (raw)
--y0Y coordinate (raw)
-s-1Session index
--jsonfalseOutput as JSON

revyl device double-tap

Double-tap an element.
revyl device double-tap [flags]
FlagDefaultDescription
--targetElement description (AI grounded)
--x0X coordinate
--y0Y coordinate
-s-1Session index
--jsonfalseOutput as JSON

revyl device long-press

Long press an element.
revyl device long-press [flags]
FlagDefaultDescription
--targetElement description (AI grounded)
--x0X coordinate
--y0Y coordinate
--duration1500Press duration in ms
-s-1Session index
--jsonfalseOutput as JSON

revyl device type

Type text into an element.
revyl device type [flags]
FlagDefaultDescription
--targetElement description (AI grounded)
--x0X coordinate
--y0Y coordinate
--textText to type (required)
--clear-firsttrueClear field before typing
-s-1Session index
--jsonfalseOutput as JSON

revyl device swipe

Swipe from an element in a direction.
revyl device swipe [flags]
FlagDefaultDescription
--targetElement description (AI grounded)
--x0X coordinate
--y0Y coordinate
--directionup, down, left, right (required)
--duration500Swipe duration in ms
-s-1Session index
--jsonfalseOutput as JSON

revyl device drag

Drag from one point to another (raw coordinates only).
revyl device drag [flags]
FlagDefaultDescription
--start-x0Starting X coordinate
--start-y0Starting Y coordinate
--end-x0Ending X coordinate
--end-y0Ending Y coordinate
-s-1Session index
--jsonfalseOutput as JSON

revyl device find

Find an element by description and return its coordinates without acting.
revyl device find <target> [flags]
FlagDefaultDescription
-s-1Session index
--jsonfalseOutput as JSON

revyl device install

Install an app from a URL onto the device.
revyl device install [flags]
FlagDefaultDescription
--app-urlURL to .apk or .ipa file (required)
--bundle-idBundle ID (auto-detected if omitted)
-s-1Session index
--jsonfalseOutput as JSON

revyl device launch

Launch an installed app by bundle ID.
revyl device launch [flags]
FlagDefaultDescription
--bundle-idApp bundle ID (required)
-s-1Session index
--jsonfalseOutput as JSON

Advanced Commands

revyl skill

Manage the embedded agent skill for AI coding tools.
revyl skill [command]
Available subcommands:
  • install - Install the skill to your AI tool’s skill directory
  • show - Print the skill content to stdout
  • export - Export the skill to a file

revyl skill install

Install the Revyl agent skill to the appropriate directory for your AI coding tool.
revyl skill install [flags]
FlagDescription
--cursorInstall for Cursor
--claudeInstall for Claude Code
--codexInstall for Codex
--globalInstall to user-level directory instead of project-level
--forceOverwrite existing installation
Without flags, auto-detects which tools are present by checking for their configuration directories. Examples:
revyl skill install              # Auto-detect and install
revyl skill install --cursor     # Cursor only (project-level)
revyl skill install --global     # Auto-detect, install globally
revyl skill install --force      # Overwrite existing skill

revyl skill show

Print the embedded agent skill content to stdout. Useful for piping or inspection.
revyl skill show
Examples:
revyl skill show                    # Print to terminal
revyl skill show | pbcopy           # Copy to clipboard (macOS)

revyl skill export

Export the embedded agent skill to a file on disk.
revyl skill export [flags]
FlagShortDescription
--output-oOutput file path (default: SKILL.md)

revyl schema

Output CLI schema for tooling integration.
revyl schema [flags]
FlagDescription
--format <json|markdown|llm>Output format

revyl mcp serve

Start MCP server for AI agent integration.
revyl mcp serve
Exposes tools for AI agents:
CategoryTools
Device Sessionstart_device_session, stop_device_session, get_session_info, list_device_sessions, switch_device_session
Device Actionsdevice_tap, device_double_tap, device_long_press, device_type, device_swipe, device_drag
Visionscreenshot
App Managementinstall_app, launch_app
Test Managementrun_test, run_workflow, list_tests, list_remote_tests, list_workflows, create_test, create_workflow, update_test
Test Operationsget_test_status, cancel_test, cancel_workflow, delete_test, delete_workflow
Build & Appslist_builds, upload_build, create_app, delete_app
Moduleslist_modules, get_module, create_module, delete_module, insert_module_block
Tagslist_tags, create_tag, delete_tag, get_test_tags, set_test_tags, add_remove_test_tags
Test Variableslist_variables, set_variable, delete_variable, delete_all_variables
Env Varslist_env_vars, set_env_var, delete_env_var, clear_env_vars
Workflow Configget_workflow_settings, set_workflow_location, clear_workflow_location, set_workflow_app, clear_workflow_app, add_tests_to_workflow, remove_tests_from_workflow
Scriptslist_scripts, get_script, create_script, update_script, delete_script, insert_script_block
Editor / Hot Reloadopen_test_editor, open_workflow_editor, stop_hot_reload, hot_reload_status
Schema / Validationvalidate_yaml, get_schema
Diagnosticsdevice_doctor, auth_status

Environment Variables

VariableDescription
REVYL_API_KEYAPI key for authentication (overrides stored credentials)
REVYL_DEBUGEnable debug logging
REVYL_VERSIONSpecify version for npm install

Exit Codes

CodeMeaning
0Success (test passed, command completed)
1Failure (test failed, error occurred)

Configuration File Schema

The .revyl/config.yaml file structure:
# Project identification
project:
  id: string           # Revyl project ID (optional)
  name: string         # Project name

# Build configuration
build:
  system: string       # Detected build system
  command: string      # Default build command
  output: string       # Build output path (glob supported)
  
  platforms:            # Named build platforms
    <name>:
      command: string  # Build command
      output: string   # Output path
      app_id: string   # Revyl app ID

# Test aliases (name → UUID)
tests:
  <name>: string       # Test UUID

# Workflow aliases (name → UUID)
workflows:
  <name>: string       # Workflow UUID

# Default settings
defaults:
  open_browser: boolean  # Open results in browser (default: true)
  timeout: number        # Default timeout in seconds (default: 600)

# Hot reload configuration
hotreload:
  default: string        # Default provider (expo, swift, android)
  providers:
    expo:
      port: number       # Dev server port (default: 8081)
      app_scheme: string # URL scheme from app.json
      use_exp_prefix: boolean  # Use exp+ prefix in deep links (default: false)

# Sync tracking (auto-managed)
last_synced_at: string   # RFC3339 timestamp of last sync operation

YAML Test Schema

See YAML Test Format for the complete test file schema. Quick reference:
name: string           # Test name
platform: ios | android
build_var_id: string   # Build variant ID

steps:
  - instruction: string      # Action to perform
  - validation: string       # Assertion to check
  - extraction:              # Extract value to variable
      instruction: string
      variable: string
  - manual:                  # System action
      action: wait | open_app | kill_app | go_home | navigate | set_location
      # action-specific parameters
  - if:                      # Conditional
      condition: string
      then: [steps]
      else: [steps]
  - while:                   # Loop
      condition: string
      steps: [steps]
      max_iterations: number