Revyl

View saved version →

---
name: revyl-cloud-app
description: Create or edit a mobile app in ChatGPT Work's cloud coding workspace, build it with revyl build --remote, run cloud tests and device verification, and map it with revyl explore. Also use for other explicitly requested Revyl CLI operations through the bundled launcher.
---

# Revyl Cloud App

Use ChatGPT Work or another shell-capable coding host for source work. Revyl
provides remote builds, devices, tests, and exploration; installing this plugin
does not create a coding workspace or grant repository access. Confirm that
the host exposes a writable workspace, shell, outbound network access, and a
way to inspect images. If any required capability is missing, report it and
ask the user to enable the cloud coding workspace. Do not substitute an MCP
server's filesystem for the user's workspace or send arbitrary shell commands
to MCP. An unavailable embedded viewer does not block authorized CLI work.

For an existing development loop, use `revyl-codex-dev-loop`. For proof of an
existing CI artifact, use `revyl-codex-proof-ci`; do not rebuild it. For viewing
only, use `revyl-workspace`; do not start a build or exploration just to open
Atlas. This workflow owns standalone builds, verification sessions, tests, and
exploration runs, and must not duplicate another workflow's resources.

## Resolve the full CLI and authenticate

Resolve this skill's absolute directory before changing to the app directory:

```sh
SKILL_DIR="<absolute directory containing this SKILL.md>"
LAUNCHER="$(cd "$SKILL_DIR/../../scripts" && pwd)/launch-revyl"
"$LAUNCHER" --version
"$LAUNCHER" auth status
```

On Windows, use the absolute `../../scripts/launch-revyl.cmd` path instead.
Invoke this launcher for every Revyl command, never `revyl` from PATH or a
different installation. It exposes the complete pinned CLI, not a fixed
command subset. Discover other requested operations through
`"$LAUNCHER" <command> --help` and `"$LAUNCHER" schema --format llm`.
Use that runtime's contract, not flags from newer documentation. A missing
command requires a reviewed runtime update, not an unpinned download.

When unauthenticated, run `"$LAUNCHER" auth login`, share its normal approval
URL, and wait for the user to approve. Never ask for credentials in chat or
copy them from the MCP connection. Never invoke credential-provisioning,
secret-bridge, or auth-bypass commands. CLI and embedded-browser sign-in are
separate; both must authorize the same app and session before embedding.

## Establish source, target, and spending scope

Confirm the requested app, target environment, platform, and authorized work.
Authorization to edit source is not authorization to publish it, create remote
apps/tests, run paid builds/devices/explorers, or change organization settings.
Agree on build attempts, test runs, explorer count, and duration before paid
work; do not repeatedly retry a failed build or increase concurrency without
approval. One end-to-end approval can cover the explicitly named operations.

For a new app, create its source in the cloud workspace using the requested
framework and its supported scaffolding tools. For an existing app, use the
authorized checkout. Inspect repository instructions and run relevant local
checks. Preserve unrelated files. Establish a Git worktree when required by
the build contract, but do not commit or push without authorization.

Run from the app directory containing `.revyl/config.yaml`. If absent and
setup is authorized, run `"$LAUNCHER" init -y`, inspect the detected recipe,
and configure its exact profile, platform, build steps, and output for the
actual framework. Do not overwrite an existing config with `--force`.
Resolve the app using `"$LAUNCHER" app list --json`. Only when explicitly
authorized to create a new remote app, use
`"$LAUNCHER" app create --name <name> --platform <ios-or-android> --json`.
Use its returned app ID in the selected recipe, then run
`"$LAUNCHER" config validate`. Do not publish configuration with `config push`
unless separately requested. Keep secrets out of source, config, argv, and
evidence; use established encrypted build-secret and launch-variable references.

## Build remotely, then verify that exact artifact

Read `build --help` from the pinned runtime, then submit one authorized build:

```sh
"$LAUNCHER" build --remote --profile <profile> --platform <ios-or-android> \
  --timeout 1800 --detach --no-set-current --json
"$LAUNCHER" build status <returned-build-job-id> --json
```

Use the agreed timeout if different. `--remote` moves compilation to Revyl,
but the CLI still needs the source checkout and recipe to submit the build.
Retain the returned job ID and source revision/worktree state. Poll that job
at intervals of at least five seconds, with a total deadline matching the
build timeout plus a bounded completion allowance. A queued job is not a
successful build. Read its terminal result and artifact ID; never substitute
the app's latest build. Do not automatically retry an ambiguous submission.
On failure, inspect the reported logs before making an authorized correction.
On cancellation or deadline, cancel only the owned job with
`"$LAUNCHER" build cancel <job-id> --json` and check its final status.

Start verification on the successful build, without changing the app's current
version or opening a browser from the shell:

```sh
"$LAUNCHER" device start --build-version-id <returned-build-version-id> \
  --platform <ios-or-android> --timeout 900 --open=false --json
"$LAUNCHER" device screenshot -s <returned-session-id> --out <image-path>
"$LAUNCHER" device validation -s <returned-session-id> "<expected visible behavior>" --json
"$LAUNCHER" device report -s <returned-session-id> --json
```

Return the viewer URL promptly. If `open_revyl_workspace` is available, request
this same session with `view="device"` and its session ID; do not start another
session through MCP. Present its returned `chatgpt_url`, when available, as an
**Open in ChatGPT** link. The user clicks it to navigate the persistent panel;
a successful tool call is not proof that the viewer is visible or playing.
Discover `device instruction`, interaction, and extraction
commands through their help as needed. Pass the returned server-issued session
ID to every session-scoped command. Open screenshots before describing them;
missing or false validation results are not a pass.

Always stop the owned verification session with
`"$LAUNCHER" device stop -s <session-id> --json`, including after failure.
Confirm termination using `device list --json` and session status as needed.
Never use `--all`. Report pending cleanup rather than claiming release.

## Create and run reproducible tests when requested

Use the pinned `schema --format llm` to author supported YAML, not guessed
blocks. With permission to create a persisted test, use
`"$LAUNCHER" test create --from-file <yaml-path> --no-open --json`; inspect
`test create --help` for app/platform association. Do not use `--force` to
replace another test. Run an authorized existing or newly created test against
the same successful artifact:

```sh
"$LAUNCHER" test run <test-id> --build-id <build-version-id> --no-wait --no-open --json
"$LAUNCHER" test report <returned-task-id> --json
```

Poll the returned task's report, not `test status <test-id>`: that command
selects the latest execution, which can belong to somebody else. Use a bounded
deadline and cancel the owned task with `test cancel <task-id>` if needed.
Require terminal test results; a successful submission is not a passed test.
Do not use `--build` here: the artifact was already built remotely. Do not
delete persisted tests or publish/share reports as automatic cleanup.

## Explore and map the same build

Exploration launches its own cloud agents/devices and needs explicit spending
authorization. Release the standalone verification session before launching
explorers unless overlapping capacity was explicitly approved.

```sh
"$LAUNCHER" explore run <app-id> --build-id <build-version-id> \
  --explorers <approved-count> --max-duration <approved-duration> \
  --no-wait --json
"$LAUNCHER" explore status <returned-run-id> --json
```

Do not silently use the default three explorers. Supply authentication through
stored launch-variable references; do not put credentials in instructions or
`--auth-instructions`. Poll at least five seconds apart within an agreed total
deadline that includes Atlas processing. Inspect both execution and Atlas
status, actual explorer count, findings, and the returned report URL. Completed
device exploration is not proof that Atlas processing completed. If the user
cancels or the deadline expires, use
`"$LAUNCHER" explore cancel <run-id> --json` and confirm terminal status.

When mapping is complete, use `open_revyl_workspace(view="atlas", app_id=...)`
if available and present its `chatgpt_url` when returned. Otherwise return the authenticated report URL from the CLI;
never invent a tool, claim an iframe loaded, or publish a share to bypass
access controls. A failed exploration can still leave partial evidence; label
it accurately instead of claiming a complete map.

## Other CLI operations and handoff

The full CLI is available through the launcher in this workspace. Apply the
same authentication, environment, authorization, and bounded-operation rules
to every discovered command. Availability does not authorize destructive,
administrative, sharing, release, or secret-management operations. Do not
expose an unrestricted shared-server shell as an alternative.

Report source changes and where they are saved, build job/artifact IDs, actual
test and validation results, exploration/Atlas outcomes, and cleanup status.
Distinguish work not run from failures. Keep credentials, signed media URLs,
customer content, and private logs out of public artifacts. Only publish source
or evidence through an explicitly authorized destination.

View saved version →

---
name: revyl-codex-dev-loop
description: Run, preview, debug, and verify mobile app changes on Revyl cloud devices from Codex, with screenshots and semantic validation.
---

# Revyl Codex Dev Loop

Use this skill for an authorized CLI development loop in a shell-capable host.
This workflow does not start an MCP server or install hooks. Installation never
changes an app's source or `.revyl/config.yaml`; later source/configuration work
is allowed only when the task explicitly requires it and the user authorizes it.

For a request to browse Atlas or view an existing device, prefer the connected
Revyl workspace tools when available; do not start a development loop just to
open a view. Source builds and rebuilds stay on this pinned CLI workflow. If
the host has no shell, explain that limitation instead of running shell commands
through another tool or starting a replacement device.

## Launcher and setup

Resolve the launcher from this skill's own absolute directory before changing
to the app directory. On POSIX use `../../scripts/launch-revyl`; on Windows use
`../../scripts/launch-revyl.cmd`. Call that absolute launcher for **every**
Revyl command; do not use `revyl` from `PATH`, `PLUGIN_ROOT`, or another
installed CLI.

```sh
SKILL_DIR="<absolute directory containing this SKILL.md>"
LAUNCHER="$(cd "$SKILL_DIR/../../scripts" && pwd)/launch-revyl"
"$LAUNCHER" --version
"$LAUNCHER" auth status
```

```bat
REM Windows cmd.exe
set "SKILL_DIR=<absolute directory containing this SKILL.md>"
set "LAUNCHER=%SKILL_DIR%\..\..\scripts\launch-revyl.cmd"
"%LAUNCHER%" --version
"%LAUNCHER%" auth status
```

If authentication is needed, use `"$LAUNCHER" auth login`. An existing
environment-provided secret may authenticate the launcher without being copied
or named in an argument. Never run credential-provisioning or secret-bridge
commands, print credentials, or paste them into chat. Post the normal login
approval URL as a clickable link and wait for approval; do not claim that a
browser opened.

## Authorization and selection

Before any build, remote session, cloud device, or paid operation, require
authorization naming the app, environment, and paid operation. Resolve the
exact profile and platform from the repository, task, and user context without
changing them; ask only when they remain ambiguous. Run from the app directory
that owns `.revyl/config.yaml`, not the monorepo root. Let `dev` create its new
context, capture the returned context and session IDs, and clean up only those
resources when the work ends or fails.

For native or rebuild-first apps, use the detached remote loop with explicit
selection and no browser opening:

```sh
"$LAUNCHER" dev --profile <exact-profile> --platform <ios-or-android> \
  --remote --detach --json --no-open
```

Return the handshake's `viewer_url` immediately without opening it. A viewer or
`--wait-ready` only means the session is available, not that the current build
succeeded. Wait for the build to reach its terminal success state before
claiming a build result.

When `open_revyl_workspace` is available, it can display the same returned
session using `view="device"` and `session_id=<returned-session-id>`. Never call
MCP `start_device_session` for a session the CLI already created. Browser and
CLI authentication are separate; inaccessible sessions require the user to
connect the matching account, not a new session or credential copied into chat.

Use short-lived commands in separate calls. Target the returned context with
`--context` for status and rebuild, and pass it positionally to stop:

```sh
"$LAUNCHER" dev status --context <returned-context>
"$LAUNCHER" dev rebuild --context <returned-context> --wait --timeout 600 --json
"$LAUNCHER" dev stop <returned-context> --json
```

Target **every** device command with `-s <returned-session-id>`. Open each
captured screenshot before describing it. A false or missing semantic verdict
is a failed validation, but cleanup still runs for the returned context/session.
Bound status polling to the configured build timeout. If that limit expires,
report a timeout and stop the owned loop instead of polling indefinitely.

## Detailed CLI mechanics

Resolve this skill's `../../references/revyl-cli-dev-loop.md` to an absolute
path and read it for framework behavior, evidence, and troubleshooting. This
skill overrides that reference whenever they conflict:

- Do not use its browser-opening, URL-opening, foreground, persistent-shell,
  `PATH`, or installed-CLI examples. Use `--detach --json --no-open` and the
  absolute launcher above.
- Do not start a local app source/configuration change, a device, build, or
  paid action without the named authorization above.
- Do not install, enable, configure, or invoke `revyl-cli-auth-bypass`. That
  skill is not shipped with this plugin, and authentication bypass is never an
  automatic fallback.
- Use exact resolved profile and platform values, and clean up only the context
  and session created for the authorized request.

Report an unavailable authorization or ambiguous target instead of guessing.

View saved version →

---
name: revyl-codex-proof-ci
description: Verify a mobile pull request using an exact-SHA match among its app's recent CI-uploaded Revyl builds, collect device evidence, and prepare a proof summary without rebuilding.
---

# Revyl Codex Proof from CI Builds

Use this skill only for an authorized proof of a pull request whose artifact
was already uploaded by CI. It does not build, upload, or configure an app.
This proof workflow requires shell access and uses the pinned CLI below. Do not
silently switch to a different MCP build lookup: its search and pagination
contract may differ from the exact-SHA checks in this skill.

## Launcher and authorization

Resolve the launcher from this skill's own absolute directory before changing
to the app directory. On POSIX use `../../scripts/launch-revyl`; on Windows use
`../../scripts/launch-revyl.cmd`. Invoke that absolute launcher for **every**
Revyl command; never use `revyl` from `PATH`, `PLUGIN_ROOT`, or another
installed CLI.

```sh
SKILL_DIR="<absolute directory containing this SKILL.md>"
LAUNCHER="$(cd "$SKILL_DIR/../../scripts" && pwd)/launch-revyl"
"$LAUNCHER" --version
"$LAUNCHER" auth status
```

```bat
REM Windows cmd.exe
set "SKILL_DIR=<absolute directory containing this SKILL.md>"
set "LAUNCHER=%SKILL_DIR%\..\..\scripts\launch-revyl.cmd"
"%LAUNCHER%" --version
"%LAUNCHER%" auth status
```

Use normal `"$LAUNCHER" auth login` only when authentication is needed. An
existing environment secret may be used without placing its value in a command,
chat, or artifact. Do not run credential-provisioning or secret-bridge
commands. Post the normal login approval URL as a clickable link and wait for
approval; do not claim that a browser opened.

Before starting a device or another paid action, require authorization naming
the app, environment, and paid operation. Resolve the pull request's **full**
head SHA and platform from read-only PR, repository, and user context; ask only
when ambiguous. Do not treat a short SHA, branch name, or version label as a
match. Run from the app directory that owns `.revyl/config.yaml` so the
project's existing launch configuration applies.

## Proof loop

1. Find a CI-uploaded build whose `metadata.scm_head_sha` exactly equals the
   full PR SHA. For example:

   ```sh
   "$LAUNCHER" build list --app <app-id> --json
   ```

   This pinned CLI lists only the newest 20 versions and does not expose
   pagination. A match in this window is usable; no match does not establish
   that the artifact is absent. While the named CI upload is pending, make at
   most three retries, ten seconds apart. If no exact match arrives, stop and
   report **proof not run: recent-build lookup incomplete**. Explain the
   20-version limit, without claiming a full-history search. Do not invent
   pagination flags, bypass CLI authentication, rebuild, re-upload, or use an
   unrelated artifact as a fallback.
2. With explicit authorization, start a device on the matching build and save
   its exact session ID:

   ```sh
   "$LAUNCHER" device start --build-version-id <matching-build-id> --json
   ```

   Return the viewer URL immediately as a clickable link when one is present.
   If `open_revyl_workspace` is available, open the same session with
   `view="device"` and its returned `session_id`. Do not start a second device
   through MCP. If browser access fails, retain the CLI's existing session and
   report the account-linking problem instead of replacing it.
   Exercise only the changed behavior. Target every device command with
   `-s <session-id>`, save concise screenshots, and open each screenshot before
   describing it. A false or missing semantic verdict is a failed proof, but
   still stop that exact session with `"$LAUNCHER" device stop -s <session-id>`.
   Never use global cleanup.
3. Obtain a report with `"$LAUNCHER" device report -s <session-id> --json` and
   report success only when a matching device session produced the evidence. A
   missing device session is never a passed proof.

## Reporting and publication

When an authorized PR-comment surface is available, use that surface to add or
update the proof. Otherwise return a ready-to-post draft headed
`## Revyl device proof` with the full SHA, matching build ID, device result,
and only the evidence actually collected.

Session sharing and screenshot/report publication are separate external
actions. Run `session share` or `session publish` only after the user explicitly
approves publication and its audience; otherwise keep the evidence local and
return the draft without public links. Never include credentials, launch-var
values, or signed URLs.

View saved version →

---
name: revyl-workspace
description: Open Revyl Atlas maps and existing device viewers inside a compatible host, or manage an explicitly authorized device session through connected Revyl workspace tools. Use revyl-cloud-app for cloud builds and exploration, or the bundled CI-proof skill for existing artifacts.
---

# Revyl Workspace

Use the connected Revyl tools for workspace data and device sessions. This
workflow does not need a shell. Check the tools actually available in the host;
never invent a tool or silently fall back to a shell command. If the connection
is absent or expired, ask the user to connect Revyl through the host's normal
authentication flow. Never request API keys, passwords, or login codes in chat.

## Choose one execution path

- For Atlas or a viewer, use this workflow. Opening a view is not authorization
  to provision a device, build an app, or run a test.
- For an existing test, use the connected test tools when available; no shell
  is needed to run a saved test against a known build.
- For a new app, standalone remote build, new persisted test, exploration, or other
  CLI operation, use `revyl-cloud-app` in a shell-capable cloud workspace.
- For a continuous development loop in an existing repository, use the bundled
  `revyl-codex-dev-loop` skill in a shell-capable host.
- For exact-SHA proof of an existing CI artifact, use the bundled
  `revyl-codex-proof-ci` skill and its bounded artifact lookup.

The CLI and MCP can display the same server-issued session ID, but one workflow
must own its creation and cleanup. Never call `start_device_session` to recreate
a CLI-owned session just to embed its viewer. Account mismatches require the
correct account connection, not a replacement session or a copied credential.

## Open Atlas or an existing device

Call `open_revyl_workspace` with `view="atlas"` and a known authorized `app_id`.
When no app is selected, use empty arguments to open the Atlas app picker. Do
not guess an identifier or use a URL in an identifier field.

For a device, reuse a session ID from the current workflow or resolve an exact
session with `list_device_sessions`. Call `open_revyl_workspace` with
`view="device"` and `session_id`. With no session selected, the device view
opens the session list; it does not start a new device. If several sessions
match, ask which one instead of choosing arbitrarily.

The tool links a client-rendered UI resource. A returned URL is not proof that
the iframe loaded, and the absence of an image in the text response is not
proof that embedding failed. Report the confirmed tool outcome without
claiming to see the live UI. Use a normal viewer link as the fallback when the
host cannot render the component. Never publish or share the session merely
to make embedding work. In ChatGPT, present the returned `chatgpt_url` as an
**Open in ChatGPT** link. Clicking it navigates the persistent panel to the
selected view; another tool call alone need not update an already-open panel.
Do not invent this link when it is absent. Keep `workspace_url` as the ordinary
browser fallback. Say that the view is ready to open, not that it is already
visible or playing, unless separate evidence confirms that outcome.

## Start a device only when requested

Require an authorized app, environment, platform, and device operation. Resolve
the target from the user's request and available read-only tools; ask when it
is ambiguous. Supply one artifact selector to `start_device_session`: a known
`build_version_id` for a pinned artifact, or `app_id` for the expressly selected
app's latest build. Use `no_open=true` so the client owns viewer navigation and
set a bounded `idle_timeout`, normally 900 seconds.

Record the returned session ID and index. Open that same session's workspace
when needed; do not invoke startup again to retry UI rendering. If startup
times out, inspect `list_device_sessions` before considering another start.
Never automatically retry an ambiguous provisioning result.

When the request includes a later test against the same build, resolve the
latest compatible build once with the available build-list tool and retain its
build version ID before startup. Pin both the session and the test to that ID;
do not resolve "latest" again between operations.

Pass the server-issued `session_id` to every session-scoped tool that declares
it. For an older tool accepting only `session_index`, first confirm that the
index still maps to the intended ID. Use the tool's declared arguments for
screenshots, interactions, and validation. Inspect returned screenshots before
describing them, and treat missing or false validation results as unverified
or failed.

For a bounded app walkthrough, use screenshots and the declared interaction
tools on that same session. Respect the authorized action/time budget and
avoid destructive or externally visible actions unless separately authorized.
Separate observed failures, usability judgments, and measured timings.

To run an explicitly requested existing test, resolve its exact name or ID.
Use `manage_tests(action="run", params={test_name, build_version_id})` in the
core/full profiles, or `run_test` when that tool is exposed. Inspect the returned
status and poll the declared status tool within a bound when necessary; a
queued execution is not a passing test. A test execution owns its own device
lifecycle and does not reuse the manual session. Do not create or change a test
as a fallback when the named test is missing.

When the authorized work ends, stop only the owned session with
`stop_device_session(session_id=...)`; for an older index-only tool, recheck
the ID-to-index mapping first. Never set `all=true`. A successful
request to stop is not the same as a released device: check the terminal result
and the active-session list. Use bounded polling, and report pending cleanup
without claiming that it completed.

Do not create, modify, or publish tests, builds, workflows, shares, or reports
unless the user requested that particular action. Keep signed media URLs,
launch values, credentials, and customer content out of public artifacts.