Revyl CLI Dev Loop Skill
Use this skill when the user wants the generic Revyl CLI dev loop instead of MCP tool-by-tool orchestration. Start from the app's real stack, keep the session running, and use the device as the source of truth.
Native Agent Behavior
- Ask at most 1-3 concise clarification questions only when the target app, platform, session, URL, or sensitive action cannot be inferred from the repo or Revyl CLI.
- Prefer safe defaults and keep moving when
revyl init --detect,revyl dev list,revyl app list, screenshots, or reports can answer the question. - When Revyl prints a viewer or local app URL, open it in the native browser/tool surface when available: Codex Browser/in-app browser for local URLs, Revyl viewer URLs, screenshots, and page checks; Claude Code
.claude/skillscompatibility links plus WebFetch/WebSearch or configured MCP/browser tools; Cursor.cursor/skillswhen using--copy, otherwise shared.agents/skills, plus available MCP/browser tools. Codex also discovers shared.agents/skillsdirectly. - If no browser tool is exposed, report the URL and verify through
revyl device screenshotorrevyl device reportinstead of claiming browser access. - Confirm before entering sensitive data, submitting forms, uploading files, accepting browser permissions, changing sharing/access, or deleting data.
- When a
revylcommand prints that a newer Revyl CLI is available or that this version will soon stop working, run the upgrade command it names once before continuing, unless the CLI version is deliberately pinned (for example in CI); if the upgrade fails, report it and keep working on the current version.
Detect and Start
bash# Initialize or refresh project detection. revyl init --detect # Start one explicit named recipe when the repo makes it clear. revyl dev --profile development --platform ios
When the profile or platform differs, make both explicit:
bashrevyl dev --profile development --platform ios revyl dev --profile development --platform android
Do not invent an active/default profile or platform. Without explicit flags,
revyl dev prefers one unique development-like profile and then only a sole
eligible choice. If an interactive run prompts, use repository evidence to
choose. If a non-interactive run reports ambiguity, retry with the exact
profile/platform from its choices instead of guessing. The selected recipe is
fixed for the dev context and its rebuilds.
If detection is stale, rerun it from the actual app root before editing the generated profile:
bashrevyl init --detect
In monorepos, run Revyl from the actual app directory, not the workspace root. For example, use apps/mobile for an Expo app even if the repo root also has a .revyl/ directory.
Start or Attach
Use normal revyl dev for new work. Contexts are worktree-local; separate
worktrees can each use the default context. If another loop is already running
in the same worktree, Revyl auto-selects a safe branch/platform context name
and prints it. Pass --context <name> only when deliberately targeting a known
loop.
bash# New loop: let Revyl provision the device and choose any needed context name. revyl dev # Inspect or switch named contexts only when you need to target one explicitly. revyl dev list revyl dev use <name> revyl dev --context <name>
Attach only when you are intentionally reusing an already-running device session:
bash# Reuse the current active session only when it is unambiguous. revyl dev attach active --context <name> revyl dev # If multiple sessions exist, attach by explicit session id or index. revyl dev attach <session-id> --context <name> revyl dev attach <index> --context <name> revyl dev
active is a convenience shortcut for the current running device session. Do
not use it when multiple sessions exist or when the desired session is unclear.
After attaching a session to a context, run revyl dev from that worktree to
start the loop on that session, or pass --context <name> if you need to
target the attached context explicitly.
Framework Guidance
- Expo: use the Revyl-managed relay and Expo dev client for JS/TS hot
reload. Rebuild only when native config, native modules, SDK/native
dependencies, permissions, or URL scheme registration changes. Try an
external Expo tunnel only after screenshots or reports show the Revyl relay,
app load, or HMR path failed. If repeated web auth is slowing stable Expo
testing, install and use
revyl-cli-auth-bypass. Implement the test-only bypass in the detected stack first, then add anauth_bypasssection to.revyl/config.yaml(see Auth Bypass below) sorevyl devapplies the launch vars and fires therevyl-authdeep link automatically. - React Native bare: use the Metro relay. No
app_schemeis needed because the device loads the JS bundle over the Revyl relay. JS/TS changes hot reload; native dependency, Podfile, Gradle, or native source changes need a rebuild. Do not use Expo tunnel fallback unless the app is actually an Expo dev-client flow. - Flutter: use a rebuild-first loop. There is no Metro/Expo dev server for
cloud hot reload; the binary is the app.
revyl devinstalls and runs the current build, and Dart file saves may auto-trigger rebuilds. In agent shells, userevyl dev rebuild --waitwhen an explicit rebuild is needed, then verify on the device. - Native iOS/Swift and native Android/Kotlin: use a rebuild-first loop. Xcode, Gradle, Kotlin, Swift, resource, manifest, or native dependency changes must build, upload or delta-push, reinstall, and relaunch in the cloud session. Expo tunnels do not fix these stacks.
- KMP, Bazel, and other native artifact flows: treat the configured
build.profiles.<profile>.<platform>.output_pathartifact as the app. Iterate through that recipe's build commands,revyl dev rebuild --wait, and device verification. - Monorepos: if detection is confused by hoisted dependencies or nested native folders, run from the app directory containing
.revyl/config.yaml.
If repeated login slows exploration on any stack, use revyl-cli-auth-bypass
first. It detects the app stack and delegates to the matching platform leaf
before this dev-loop skill starts the session with bypass launch vars.
Observe, Act, Verify
Use screenshots and reports to decide what happened before changing strategy.
bashrevyl device screenshot --out before.png revyl device tap --target "Sign In button" revyl device type --target "Email field" --text "user@example.com" revyl device swipe --target "Product list" --direction down revyl device instruction "Open the checkout screen" revyl device validation "The checkout screen is visible" revyl device screenshot --out after.png revyl device report --session-id <session-id> --json
Validation is semantic: a false or missing verdict exits non-zero even when the
worker request completed successfully. In JSON mode, inspect success and
step_output.validation_result.
During exploration, capture the exact path that worked. Describe actions with visible target language and keep the path at intent level.
Targeting a session
Commands act on the active session by default. -s selects a specific one and
takes either form: a local index from revyl device list, or the server-issued
session_id from revyl device start --json. --session-id <uuid> is the
explicit spelling, and REVYL_SESSION_ID scopes a whole shell for the commands
that accept -s. revyl device stop --all ignores that scope and still stops
every session revyl device list would show. The revyl dev commands use
their dev context instead.
Prefer session IDs whenever more than one session is live. Indexes live in a per-project file shared by every CLI process in that directory, and only mean anything relative to it; ID-targeted commands resolve from the backend in one call and never touch that file.
bashSESSION=$(revyl device start --platform ios --json | jq -r '.session_id') revyl device instruction "Open the checkout screen" -s "$SESSION" --json revyl device stop -s "$SESSION"
Auth Bypass
Preferred: configure it once in .revyl/config.yaml and every session — cold
start, rebuild relaunch, reused session — launches authenticated with no flags:
yamlsession: auth_bypass: launch_vars: [REVYL_AUTH_BYPASS_ENABLED, REVYL_AUTH_BYPASS_TOKEN] deep_link: "myapp://revyl-auth?token=${REVYL_AUTH_BYPASS_TOKEN}&redirect=/home"
${VAR} placeholders resolve server-side from launch variables already
attached to the session; secret values never enter CLI or MCP output.
The deep link fires automatically after every app (re)launch. If the app ever
shows a logged-out state mid-session but the boot token is still valid,
re-fire that same deep link (refresh does not remint — launch env is fixed at
boot):
bashrevyl dev auth refresh --json
If the token itself expired, restart the session (revyl dev stop then
revyl dev) so a fresh mint is applied as launch environment.
Manual fallback (no config section yet):
bash# One-time setup if the launch vars do not already exist. export REVYL_AUTH_BYPASS_TOKEN="<test-only-token>" revyl global launch-var create REVYL_AUTH_BYPASS_ENABLED=true revyl global launch-var create REVYL_AUTH_BYPASS_TOKEN="$REVYL_AUTH_BYPASS_TOKEN" --secret revyl dev --no-build \ --launch-var REVYL_AUTH_BYPASS_ENABLED \ --launch-var REVYL_AUTH_BYPASS_TOKEN # After the app loads, open the auth-bypass link from a separate shell: revyl device navigate \ --url "myapp://revyl-auth?token=$REVYL_AUTH_BYPASS_TOKEN&role=buyer&redirect=%2Fcheckout" revyl device screenshot --out /tmp/revyl-auth-bypass.png
If the app has not implemented the handler yet, install/use
revyl-cli-auth-bypass first. Implement the handler in the detected stack,
then add the auth_bypass section to .revyl/config.yaml so future sessions
need no manual steps. Never paste launch-var values into code, logs, or PRs.
Guardrails
- Start from the detected app stack, then override only when detection is wrong.
- Keep the dev loop running while using separate short-lived
revyl devicecommands for interaction. - Prefer user-visible outcomes over implementation details.
- Stop local loop cleanly with
Ctrl+Correvyl dev stopwhen done.
Agent Execution
revyl dev is a persistent process. In agent shells, prefer --detach: the
loop daemonizes itself and the command returns a machine-readable handshake as
soon as the device session is live (the build may still be running behind it).
bash# Preferred agent start: returns JSON with viewer_url within seconds. On a # local machine the CLI also opens the viewer in the user's browser # (opened_browser in the handshake; --no-open disables). When opened_browser is # false (headless/CI/SSH), always post viewer_url as a clickable link; never # open a browser yourself. revyl dev --profile development --platform ios --remote --detach --json # native/rebuild-first revyl dev --profile development --platform ios --detach --json # hot reload # Optional: install the latest existing build immediately (seed) so the app is # interactive + authenticated within seconds while the fresh build compiles, # then it hot-swaps automatically. Best when time-to-first-build is slow. revyl dev --profile development --platform ios --remote --seed-latest --detach --json # Share viewer_url with the user immediately, then monitor the BUILD: revyl dev status # build_mode=remote; state: building -> idle revyl dev logs --build --follow # stream remote build output # Iterate and stop: revyl dev rebuild --wait --json # signals the running loop (SIGUSR1); no separate build cmd revyl dev stop --json
Do NOT combine --remote with --no-build or --tunnel (the CLI rejects both).
--build-version-id is allowed with --remote only as an explicit seed source.
revyl dev status --wait-ready blocks until the device SESSION is live, which
in --remote happens while the build is still running — it does NOT mean the
build finished. Track build completion via dev status (building -> idle)
or dev logs --build --follow. With --seed-latest, the handshake/status
report installed_seed + seeded_version for the build already on screen.
Cloud Agent Relay Note
In Cursor or similar cloud-agent environments, start with the Revyl-managed relay:
bashrevyl dev --no-build --app-id <app-id>
If you need to target a specific existing loop, inspect contexts first with
revyl dev list, then run revyl dev --context <name>. Do not predefine a
context for normal startup; Revyl will pick one when the worktree needs it.
For Expo and bare React Native, this lets Revyl own Metro/Expo startup, relay creation, dev-client install, and the deep link opened on the cloud device. If the app does not load or hot reload does not apply changes, gather device evidence before changing transport.
If startup fails with failed to create relay session: unauthorized after
Backend relay connectivity OK, do not assume the developer needs to log in
again. First run revyl auth status and revyl ping; if both pass, capture a
revyl dev --debug run and treat it as a Revyl relay/backend issue. For Expo
dev-client projects, use --force-hot-reload first when Revyl verifies relay
transport but cannot prove Expo manifest readiness.
After Dev loop ready, keep the process running. Treat Viewer: and the
relay/deep-link host printed by revyl dev as the active relay session; in
production this may be relay.revyl.ai, while local or branch environments may
use a generated relay/ngrok host. Do not stop the relay because of HMR
diagnostic warnings; normal runs hide advisory HMR diagnostics, and
revyl dev --debug is for relay/HMR troubleshooting.
If startup fails because the relay transport is not ready yet (slow Metro startup on large apps), extend the readiness wait instead of switching transports:
bashrevyl dev --profile development --platform ios --ready-timeout 120 # Seconds; alternatively set REVYL_READY_TIMEOUT.
If relay transport and manifest checks pass but a large Expo app times out on the first cold bundle transform, extend the separate prewarm budget (default 300 seconds, maximum 600):
bashrevyl dev --profile development --platform ios --prewarm-timeout 600 # Alternatively set REVYL_PREWARM_TIMEOUT.
Metro inherits your shell environment (for example EXPO_OFFLINE=1 speeds up
Expo startup); CI is intentionally stripped from the Metro environment
because CI=1 disables Fast Refresh.
For Expo manifest readiness timeouts, use diagnostic launch mode before switching transports:
bashrevyl dev --profile development --platform ios --force-hot-reload
This still requires Expo startup and Revyl relay transport to succeed. It skips only the manifest and bundle proof so the cloud 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 report.
Before switching to Expo tunnel fallback, gather device evidence:
bashrevyl device screenshot -s <session-index-or-id> revyl device report --session-id <session-id> --json
Continue using the relay if screenshots show the app downloading/loading or the
report/network evidence shows successful fetches from the relay host printed by
revyl dev. Only fall back for Expo/React Native dev-client projects if the
device remains on a dev-client error screen, the report shows no successful
relay fetches, or the app loads but hot reload is not applying changes.
For Flutter, Swift/iOS, native Android, KMP, Bazel, and other rebuild-first
stacks, do not switch to an Expo tunnel. These stacks do not use the
Metro/Expo transport path. If changes do not appear, inspect revyl dev status,
the last build output, and the device screenshot. Then trigger
revyl dev rebuild --wait from a separate shell, or stop and restart the loop
if the rebuild session is unhealthy.
If fallback is needed, start Expo in a long-running terminal and pass the full
dev-client link that Expo prints, not just the raw *.exp.direct URL:
bashCURSOR_AGENT=1 npx expo start --tunnel --dev-client revyl dev --no-build --app-id <app-id> --tunnel '<full Expo dev-client link>'
