This page provides a complete reference for all Revyl CLI commands, flags, and configuration options.
Global Flags
These flags work with any command:
| Flag | Short | Description |
|---|
--debug | | Enable debug logging |
--dev | | Use local development servers |
--json | | Output results as JSON (where supported) |
--quiet | -q | Suppress non-essential output |
Authentication Commands
revyl auth login
Authenticate with your API key.
Prompts for your API key, validates it, and stores credentials in ~/.revyl/credentials.json.
revyl auth logout
Remove stored credentials.
revyl auth status
Show current authentication status.
revyl auth status [flags]
| Flag | Description |
|---|
--json | Output as JSON |
Displays: email, user ID, organization ID, and masked API key.
Project Commands
revyl init
Initialize a project for Revyl CLI usage.
| Flag | Description |
|---|
--project <id> | Link to a specific Revyl project |
-y, --non-interactive | Skip interactive wizard, generate config only |
--hotreload | Configure hot reload for an existing initialized project and exit |
--detect | Only detect build system, don’t create files |
--force | Overwrite 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.
| Flag | Description |
|---|
--tests | Sync tests only |
--workflows | Sync workflows only |
--apps | Sync build platform app_id links only |
--non-interactive | Disable prompts and apply deterministic defaults |
--interactive | Force prompts (requires TTY stdin) |
--prune | Auto-prune stale/deleted mappings |
--dry-run | Show planned actions without writing files |
--skip-hotreload-check | Skip hot reload dev_client_build_id validation |
--json | Output 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>
| Flag | Description |
|---|
--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]
| Flag | Description |
|---|
--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 |
--wait | Wait 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]
| Flag | Description |
|---|
--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.
| Flag | Description |
|---|
--json | Output as JSON |
revyl test remote
List all tests in your organization.
revyl test remote [flags]
| Flag | Description |
|---|
--limit <n> | Limit number of results |
--platform <ios|android> | Filter by platform |
--json | Output as JSON |
revyl test pull
Pull tests from remote to local.
revyl test pull [name] [flags]
| Flag | Description |
|---|
--force | Overwrite local changes |
--dry-run | Show what would be pulled |
revyl test push
Push local tests to remote.
revyl test push [name] [flags]
| Flag | Description |
|---|
--force | Overwrite remote changes |
--dry-run | Show what would be pushed |
revyl test diff
Show differences between local and remote.
revyl test validate
Validate YAML test files.
revyl test validate [file] [flags]
| Flag | Description |
|---|
--json | Output results as JSON |
Create Commands
revyl test create
Create a new test.
revyl test create <name> [flags]
| Flag | Description |
|---|
--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-open | Don’t open in browser |
--no-sync | Don’t sync to remote |
--force | Overwrite if exists |
--dry-run | Show what would be created |
revyl workflow create
Create a new workflow.
revyl workflow create <name> [flags]
| Flag | Description |
|---|
--tests <names> | Comma-separated test names to include |
--no-open | Don’t open in browser |
--no-sync | Don’t sync to remote |
--dry-run | Show what would be created |
Execution Commands
revyl run
Build and run a test or workflow in one command (recommended shortcut).
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.
| Flag | Short | Description |
|---|
--workflow | -w | Run a workflow instead of a test |
--no-build | | Skip build step; run against last uploaded build |
--platform <name> | | Build platform to use (e.g. ios, android) |
--open | | Open report in browser when complete |
--timeout <seconds> | -t | Timeout in seconds (default: 3600) |
--retries <n> | -r | Retry attempts (1-5) |
--json | | Output results as JSON |
--verbose | -v | Show detailed output |
--no-wait | | Queue and exit without waiting |
--hotreload | | Run 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]
| Flag | Description |
|---|
--build | Build 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-wait | Queue and exit immediately |
--open | Open report in browser when complete |
--json | Output as JSON |
--verbose | Show detailed logs |
--github-actions | Format 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:
- Send a cancellation request to the server
- Stop the test execution on the device
- 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]
| Flag | Description |
|---|
--build | Build 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-wait | Queue and exit immediately |
--open | Open report in browser when complete |
--verbose | Show detailed logs |
--github-actions | Format for GitHub Actions |
--json | Output 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:
- Send a cancellation request to the server
- Cancel all running and queued tests in the workflow
- Display “Workflow cancelled by user”
revyl test
Parent command for test management operations.
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]
| Flag | Description |
|---|
--platform <name> | Build platform to use |
--skip-build | Skip build step |
--retries <n> | Retry attempts for each test |
--no-wait | Don’t wait for completion |
--open | Open report when complete |
--timeout <seconds> | Workflow timeout |
--json | JSON 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]
| Flag | Description |
|---|
--skip-build | Upload existing artifact |
--version <string> | Version label (default: git SHA) |
--set-current | Set as current build |
--platform <ios|android> | Platform to build for |
--name <string> | Custom build name |
--build-var <id> | Build variant ID |
--yes | Skip confirmation prompts |
--dry-run | Show what would be uploaded |
--json | JSON output |
revyl build list
List uploaded build versions.
| Flag | Description |
|---|
--platform <ios|android> | Filter by platform |
--build-var <id> | Filter by build variant |
--json | JSON output |
revyl build delete
Delete a build.
revyl build delete <app-id> [flags]
| Flag | Description |
|---|
--version <id> | Delete a specific build version (otherwise deletes all versions) |
--json | JSON 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.
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:
| Flag | Description |
|---|
--hotreload | Enable 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>
| Flag | Description |
|---|
--json | JSON 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>
| Flag | Description |
|---|
--json | JSON 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>
| Flag | Description |
|---|
--json | JSON 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>
| Flag | Description |
|---|
--json | JSON 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.
| Flag | Description |
|---|
--json | JSON 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.
| Flag | Description |
|---|
--json | JSON output |
revyl version
Show version information.
| Flag | Description |
|---|
--json | Output version, commit, and build date as JSON |
revyl upgrade
Check for and install updates.
| Flag | Description |
|---|
--check | Check only, don’t install |
--force | Force reinstall |
--prerelease | Include prerelease versions |
--json | JSON output |
revyl docs
Open documentation in browser.
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]
| Flag | Default | Description |
|---|
--platform | | Platform: ios or android (required) |
--timeout | 300 | Idle timeout in seconds |
--open | false | Open viewer in browser |
--json | false | Output as JSON |
revyl device stop
Stop a device session.
revyl device stop [flags]
| Flag | Default | Description |
|---|
-s | -1 | Session index (-1 = active) |
--all | false | Stop all sessions |
--json | false | Output as JSON |
revyl device list
List all active device sessions.
revyl device list [flags]
| Flag | Description |
|---|
--json | Output as JSON |
revyl device use
Switch the active session.
revyl device info
Show session details (ID, platform, viewer URL, uptime).
revyl device info [flags]
| Flag | Default | Description |
|---|
-s | -1 | Session index |
--json | false | Output as JSON |
revyl device doctor
Run diagnostics on auth, session, worker, and device health.
revyl device doctor [flags]
| Flag | Default | Description |
|---|
-s | -1 | Session index |
revyl device screenshot
Capture a device screenshot.
revyl device screenshot [flags]
| Flag | Default | Description |
|---|
--out | | Output file path |
-s | -1 | Session index |
--json | false | Output as JSON |
revyl device tap
Tap an element by description or coordinates.
| Flag | Default | Description |
|---|
--target | | Element description (AI grounded) |
--x | 0 | X coordinate (raw) |
--y | 0 | Y coordinate (raw) |
-s | -1 | Session index |
--json | false | Output as JSON |
revyl device double-tap
Double-tap an element.
revyl device double-tap [flags]
| Flag | Default | Description |
|---|
--target | | Element description (AI grounded) |
--x | 0 | X coordinate |
--y | 0 | Y coordinate |
-s | -1 | Session index |
--json | false | Output as JSON |
revyl device long-press
Long press an element.
revyl device long-press [flags]
| Flag | Default | Description |
|---|
--target | | Element description (AI grounded) |
--x | 0 | X coordinate |
--y | 0 | Y coordinate |
--duration | 1500 | Press duration in ms |
-s | -1 | Session index |
--json | false | Output as JSON |
revyl device type
Type text into an element.
revyl device type [flags]
| Flag | Default | Description |
|---|
--target | | Element description (AI grounded) |
--x | 0 | X coordinate |
--y | 0 | Y coordinate |
--text | | Text to type (required) |
--clear-first | true | Clear field before typing |
-s | -1 | Session index |
--json | false | Output as JSON |
revyl device swipe
Swipe from an element in a direction.
revyl device swipe [flags]
| Flag | Default | Description |
|---|
--target | | Element description (AI grounded) |
--x | 0 | X coordinate |
--y | 0 | Y coordinate |
--direction | | up, down, left, right (required) |
--duration | 500 | Swipe duration in ms |
-s | -1 | Session index |
--json | false | Output as JSON |
revyl device drag
Drag from one point to another (raw coordinates only).
revyl device drag [flags]
| Flag | Default | Description |
|---|
--start-x | 0 | Starting X coordinate |
--start-y | 0 | Starting Y coordinate |
--end-x | 0 | Ending X coordinate |
--end-y | 0 | Ending Y coordinate |
-s | -1 | Session index |
--json | false | Output as JSON |
revyl device find
Find an element by description and return its coordinates without acting.
revyl device find <target> [flags]
| Flag | Default | Description |
|---|
-s | -1 | Session index |
--json | false | Output as JSON |
revyl device install
Install an app from a URL onto the device.
revyl device install [flags]
| Flag | Default | Description |
|---|
--app-url | | URL to .apk or .ipa file (required) |
--bundle-id | | Bundle ID (auto-detected if omitted) |
-s | -1 | Session index |
--json | false | Output as JSON |
revyl device launch
Launch an installed app by bundle ID.
revyl device launch [flags]
| Flag | Default | Description |
|---|
--bundle-id | | App bundle ID (required) |
-s | -1 | Session index |
--json | false | Output as JSON |
Advanced Commands
revyl skill
Manage the embedded agent skill for AI coding tools.
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]
| Flag | Description |
|---|
--cursor | Install for Cursor |
--claude | Install for Claude Code |
--codex | Install for Codex |
--global | Install to user-level directory instead of project-level |
--force | Overwrite 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.
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]
| Flag | Short | Description |
|---|
--output | -o | Output file path (default: SKILL.md) |
revyl schema
Output CLI schema for tooling integration.
| Flag | Description |
|---|
--format <json|markdown|llm> | Output format |
revyl mcp serve
Start MCP server for AI agent integration.
Exposes tools for AI agents:
| Category | Tools |
|---|
| Device Session | start_device_session, stop_device_session, get_session_info, list_device_sessions, switch_device_session |
| Device Actions | device_tap, device_double_tap, device_long_press, device_type, device_swipe, device_drag |
| Vision | screenshot |
| App Management | install_app, launch_app |
| Test Management | run_test, run_workflow, list_tests, list_remote_tests, list_workflows, create_test, create_workflow, update_test |
| Test Operations | get_test_status, cancel_test, cancel_workflow, delete_test, delete_workflow |
| Build & Apps | list_builds, upload_build, create_app, delete_app |
| Modules | list_modules, get_module, create_module, delete_module, insert_module_block |
| Tags | list_tags, create_tag, delete_tag, get_test_tags, set_test_tags, add_remove_test_tags |
| Test Variables | list_variables, set_variable, delete_variable, delete_all_variables |
| Env Vars | list_env_vars, set_env_var, delete_env_var, clear_env_vars |
| Workflow Config | get_workflow_settings, set_workflow_location, clear_workflow_location, set_workflow_app, clear_workflow_app, add_tests_to_workflow, remove_tests_from_workflow |
| Scripts | list_scripts, get_script, create_script, update_script, delete_script, insert_script_block |
| Editor / Hot Reload | open_test_editor, open_workflow_editor, stop_hot_reload, hot_reload_status |
| Schema / Validation | validate_yaml, get_schema |
| Diagnostics | device_doctor, auth_status |
Environment Variables
| Variable | Description |
|---|
REVYL_API_KEY | API key for authentication (overrides stored credentials) |
REVYL_DEBUG | Enable debug logging |
REVYL_VERSION | Specify version for npm install |
Exit Codes
| Code | Meaning |
|---|
0 | Success (test passed, command completed) |
1 | Failure (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