Explore from the CLI

Use Explore to discover an app and build or refresh its Atlas map.

Start an explorationCopy Anchor Link

revyl explore run "My App"
revyl explore run --platform android
revyl explore status <run-id>
revyl explore cancel <run-id>

If you omit the app, Revyl uses the mapping in .revyl/config.yaml. Choose a platform when the project maps more than one app. Without a branch, it uses your Git branch if it has a usable build, else the app's default branch. Use --branch, --build-selection latest, --all-branches or --build-id to choose another build. See Build branches.

Shape the runCopy Anchor Link

revyl explore run "My App" --branch staging \
  --explorers 1 --strategy surface-sweep \
  --instructions "Cover checkout and account settings" \
  --max-duration 20m --timeout 35m --open

Strategies are balanced, surface-sweep, journey-focus, and hard-edges. Explorers beyond available device concurrency wait in the queue. Use --device-model, --os-version and --idle-timeout for runtime targeting. Queue time can require a longer local wait than the exploration duration.

CLI authentication and the app's own login are separate. Configure a seeded test account or auth bypass, then reference stored launch variables:

revyl explore run "My App" --branch staging \
  --auth-instructions "Use the seeded test account" \
  --launch-var REVYL_AUTH_BYPASS_ENABLED \
  --launch-var REVYL_AUTH_BYPASS_TOKEN

Store secret values in Revyl and use their keys or IDs with --launch-var. Keep values out of prompts, flags, logs and committed workflow files.

Web explorationCopy Anchor Link

Web sessions and the separate Web exploration feature flag must be enabled for your organization before you can launch a Web exploration.

revyl explore run "My Web App" --platform web --max-duration 20m
revyl explore run --platform web --idle-timeout 30m

Web exploration uses the Web app's selected build and automatically applies the app project's session.auth_bypass.sign_in configuration: its sign-in path, and stored secret name. The CLI does not send sign-in details. Without that configuration, exploration starts signed out. --auth-instructions provides guidance, not a replacement for configured sign-in; never put credentials in instructions.

--device-model, --os-version, --launch-var, --launch-env, and --no-inherited-launch-vars are not supported for Web. Inherited launch variables are ignored automatically. Web --max-duration defaults to 30 minutes and cannot exceed 30m; --idle-timeout defaults to 15 minutes and cannot exceed 60m. Both require whole seconds and a minimum of 1m. The requested explorer count must not exceed your organization's Web concurrency limit.

Each Web explorer defaults to 20 planner turns, with at most 8 browser actions per turn, in a 1280×800 browser viewport. The API supports up to 50 planner turns through max_turns; the CLI has no flag to change that limit.

Web exploration is scoped to the session's origin after startup and configured sign-in. Navigation accepts relative paths and absolute URLs on that origin, but refuses other origins. If an interaction leaves that origin, the explorer goes back and records the detour; it stops if it cannot return.

The submit guard lets explorers open and fill risky screens but blocks committing sign-up or registration; organization, workspace, or team creation; invitations; subscriptions, upgrades, purchases, checkout, or payment; deletion, removal, or deactivation; and sign-out. It also refuses navigating to a URL whose path or query names one of those actions, such as /logout. Instructions cannot override this guard.

Keep main or staging currentCopy Anchor Link

Merging a PR doesn't move its builds or Atlas evidence to main, and feature-branch builds don't contain the merged code. Build the intended source, upload it with --branch so the destination doesn't depend on the CI checkout, then explore the exact returned build. Uploading alone doesn't populate Atlas.

Prove one run firstCopy Anchor Link

1. Choose the source repository/branch, Revyl app ID, and destination (main or staging). Start with one platform. Use revyl app list --json to find the app and build a compatible artifact from a clean checkout of that source.
2. Install the CLI and jq. Store REVYL_API_KEY in your CI secret store; configure build secrets and app login separately. Set the variables below to your artifact, app and destination.
3. Upload and explore exactly that build. Add your stored login references to the Explore command if needed:

set -euo pipefail

ARTIFACT=./build/app.apk
APP_ID="<your-android-app-id>"
DESTINATION=main
SOURCE_SHA=$(git rev-parse HEAD)

revyl build upload --file "$ARTIFACT" --app "$APP_ID" \
  --branch "$DESTINATION" --yes --json > build.json
BUILD_ID=$(jq -er '
  select(.success == true and .count == 1)
  | .build.build_id | select(type == "string" and length > 0)
' build.json)

revyl explore run "$APP_ID" --build-id "$BUILD_ID" \
  --explorers 1 --max-duration 20m --timeout 35m --json > explore.json
jq -e --arg build_id "$BUILD_ID" \
  '.success == true and .build_id == $build_id' explore.json

4. Open .report_url from explore.json and select the destination in Atlas. Confirm the build ID, login and useful mapped screens. Keep the source SHA, build ID and report URL with the run. Uploads don't pin the branch; see Build branches. Making that branch the app's default branch is optional.

Optionally run an existing test for the same app/platform against that build:

revyl test run "$TEST_ID" --build-id "$BUILD_ID" --timeout 1800 --json > test.json
jq -e '.success == true' test.json

Turn it into CICopy Anchor Link

Copy the maintenance helper and workflow into your repository. Its README lists the variables, login setup, artifact or remote-build choices, and how to also run your tests on each build. Run it with workflow_dispatch and inspect one complete result before enabling the push or schedule trigger.

Build from the selected checkout, whether the helper builds remotely or uploads an existing artifact.

Keep one writer per app and destination, from source checkout through completed Explore. The examples share a stable concurrency group with cancel-in-progress: false and check out the current source branch after obtaining the slot. Reusing an earlier CI artifact requires checking its source SHA and skipping it if superseded. Latest means upload order, not Git ancestry. GitHub concurrency groups coordinate within one repository; pending work can be replaced, so this maintains the current branch rather than promising every intermediate commit is explored.

For scheduled GitHub runs, keep the workflow on the repository default branch and explicitly check out the source you want to build. Schedules can be delayed; the example uses an off-hour minute rather than promising an exact refresh time.

The helper saves known job/run IDs, uses bounded polling, waits for Atlas processing, and attempts cancellation plus terminal-state checks on failure. If the runner is lost or a launch/cancellation result is unknown, stop other writers and reconcile the recorded operation before restarting. A CI lock or shell cleanup handler cannot guarantee remote cleanup after runner loss.

Ask a cloud AI agent to set it upCopy Anchor Link

Use this prompt after filling in the placeholders:

In repository <owner/repo>, configure the Revyl branch-maintenance example for source branch <main-or-staging>, app <app-id>, and Revyl destination <main-or-staging>. Use <existing CI artifact or current-checkout build profile> and stored login reference <key-or-id>. To also run tests on each build, set REVYL_WORKFLOW_ID to <workflow-id>. Store API/build credentials as CI secrets. Keep one shared concurrency group for this app/destination and build the current source head after acquiring it. Run the workflow manually once; upload explicitly to the destination and explore only the returned build ID. Check login and mapped screens, then return the source SHA, build ID and report URL. Set up <push-after-merge or weekly> execution after the manual result is verified. Do not use an incidental feature checkout as the source.

Cloud AI agent automations, such as Cursor automations, can schedule an agent with a chosen repository and branch. Use the agent to dispatch the same CI workflow for recurring refreshes unless its host provides verified single-writer execution. A prompt saying “do not overlap” does not provide that guarantee.

JSON handoffsCopy Anchor Link

Require a successful command exit for every handoff. File uploads, URL uploads, remote builds and status commands have different JSON envelopes:

build --remote --detach --json returns .build_job_id, not an uploaded build. Save it and monitor that job. Always pass the eventual exact build ID downstream; do not look up Latest again between upload and Explore/tests.

Monitor, cancel and interpret resultsCopy Anchor Link

By default Explore waits and reports per-explorer progress. --no-wait returns after launch; save .run_id and poll explore status <run-id> --json. explore status is a single read, not a follow stream. A queued/running execution or unfinished Atlas processing is not a completed map.

--timeout limits the local wait and does not cancel remote work. Press Ctrl-C once while waiting to cancel the Explore run and again to stop waiting. For unattended cleanup, cancel the known run and check that it settles. Remote-build Ctrl-C detaches; use build cancel <job-id> to cancel explicitly.

With --json, progress stays on stderr and stdout contains one result object. Explore results include .run_id, .build_id, .report_url, .outcome and .success. A usable partial map or setup blocker can still succeed. Failed, cancelled, locally timed-out and no-map outcomes exit nonzero. Inspect the report: Explore proves execution and map generation; tests prove behavioral assertions.