Skip to main content
Connect Revyl over MCP so your coding agent can run the current app source, control cloud devices, and verify changes. Custom MCP is optional. The Cursor plugin installs the CLI and signs you in without starting an MCP server.

​
Install the Revyl CLI

The Cursor Marketplace plugin installs a pinned CLI through its hooks. For a manual install, or for Claude Code and Codex:

​
Authentication

Every setup below starts with revyl auth login. It prints an approval URL and a short code, opens the URL when this machine has a browser, and waits for you to approve. Approval happens through Revyl rather than a local port, so the same command works on your laptop, in a cloud agent, over SSH, and in a container — just open the printed URL wherever you are signed in. For a machine with nobody present to approve, use revyl auth login --api-key or set REVYL_API_KEY. That key is optional unattended authentication, not required. Hosted agents are covered under Cursor Cloud Agents below. See Authentication for the full reference. The MCP server reads whatever the CLI stored, so authenticating once in a terminal is enough — the next tool call picks it up without restarting the session.

​
Cursor

The Cursor plugin installs the CLI and signs you in. It does not start MCP. Optional custom MCP below uses a literal command only (revyl or /usr/local/bin/revyl), never ${...}.
From the app repository, authenticate and install the MCP dev-loop skill:
Create .cursor/mcp.json in the repository:
Restart Cursor if it was already open when you installed the CLI. Start a new Agent chat and ask:
The dev profile exposes 11 focused setup, dev-loop, and device tools, including setup_status. It is intentionally narrower than the core and full profiles. Use the CLI or a broader MCP profile for test, workflow, and other management operations. The command above installs the MCP-specific revyl-mcp-dev-loop skill. The default revyl skill install command installs the separate revyl-cli-* fallback family and is not required for this MCP setup. The Marketplace plugin does not start this server; install the skill only when you opt into custom MCP.

​
How the plugin installs the CLI

Plugin hooks use an explicitly configured REVYL_BINARY when present in the environment. Otherwise they:
  1. read the runtime version and per-platform SHA-256 values pinned in the plugin release;
  2. select the matching macOS, Linux, or Windows asset from the immutable Revyl CLI GitHub Release;
  3. reuse the versioned cached executable only when its SHA-256 still matches;
  4. otherwise adopt an already-installed Revyl CLI — the first of revyl on PATH, /usr/local/bin/revyl, ~/.revyl/bin/revyl, or ~/.local/bin/revyl whose SHA-256 equals the pinned value — by copying it into the versioned cache and verifying the copy;
  5. download a missing or corrupt executable to a temporary file with a bounded timeout and up to three attempts with backoff, verify it, install it atomically, and verify the cached file again;
  6. copy the verified executable onto a user PATH location without replacing a different existing CLI: ~/.revyl/bin/revyl or ~/.local/bin/revyl on macOS and Linux, and %USERPROFILE%\.revyl\bin\revyl.exe or %LOCALAPPDATA%\Revyl\bin\revyl.exe on Windows. An explicit REVYL_BINARY override is not published.
The default cache is under $XDG_CACHE_HOME or $HOME/.cache/revyl/cursor-plugin on macOS and Linux, and %LOCALAPPDATA%\Revyl\cursor-plugin on Windows. A new plugin runtime pin uses a new versioned directory. A corrupt cached executable is never run and is replaced on the next online start. Agent shells still need the published PATH directories prepended; the cache path is not a revyl command. sessionStart is a fast path: if the pin is already cached, it bridges a real REVYL_API_KEY or tells the agent to run revyl auth login. The first revyl command may download. When every download attempt fails, the launcher names the asset it could not fetch and points at REVYL_BINARY as the manual override.

​
Other CLI-based MCP clients

​
Claude Code

Open a new terminal, authenticate, and run from the app repository:

​
Codex

Open a new terminal, authenticate, and run from the app repository:

​
Launch Configuration Inputs

MCP launch tools expose the same startup inputs as the CLI. On start_dev_loop, start_device_session, run_test, and run_workflow, use:
  • profile on start_dev_loop for the named local build profile;
  • platform on start_dev_loop for its ios or android recipe and device;
  • launch_vars for stored environment-configuration names or IDs;
  • launch_arg_sets for stored ordered iOS argument-set names or IDs; and
  • launch_arguments for exact inline iOS argument tokens.
Arrays preserve their input order. Stored argument sets are flattened first, then inline tokens are appended. Inline tokens are non-secret. Android-only launches reject iOS arguments, while mixed workflows skip them for Android children.

​
Setup recovery

The agent calls start_dev_loop first. When setup is ready, Revyl returns the viewer immediately. Otherwise the result contains one structured remediation:
  • auth_required, auth_expired, or auth_invalid: run remediation.command to log in; invalid stored credentials are replaced by the successful login before the single retry. Revyl also registers an approval for you and returns it as outcome.authorization_url and outcome.authorization_code, so you can approve in a browser without touching a terminal — clients that render inline MCP apps show this as an authorize button. The accompanying message also names the Cloud secret bridge below, which is the recovery to prefer when no one is present to complete a login.
  • cloud_secret_required: run remediation.command to bridge the injected remediation.env_name secret into the credential store. restart_required is false, so retry in the same session. When no secret is present the command says so; run revyl auth login and post the printed approval URL, or add optional REVYL_API_KEY as a Runtime Secret and start a fresh Cloud Agent.
  • cloud_context_invalid: when remediation.action_kind is restart_session, start a fresh Cloud session and do not retry in the current session.
  • project_not_initialized: use remediation.command to pull an existing UI-created or server-managed project, or remediation.alternative_command to initialize a genuinely new project. Choose from repository and user context; ask when unclear, then run only that exact command in remediation.working_directory.
  • project_legacy_config: run remediation.check_command to review the proposal and complete migration report, then run remediation.apply_command to create the backup and apply it.
  • project_outside_git: select a project directory inside an active Git worktree and retry with it as project_dir.
  • project_ambiguous: choose one remediation.candidate_roots value and retry with that exact project_dir.
  • project_invalid: run remediation.check_command, repair remediation.config_path, and retry.
After one remediation, the agent retries start_dev_loop once. A second failure is reported instead of entering a setup loop. If start_dev_loop instead fails with a profile/platform selection error, use the valid choices in the error to retry once with exact profile and platform values. Do not guess or invent a default. The deprecated platform_key input returns dev_loop_platform_key_removed; retry with profile and platform. setup_status provides the same secret-free setup diagnostics when explicitly requested, but it is not required before a normal dev loop. Its signals object reports the markers behind the classification without exposing any secret: whether a Cloud context file was read, whether it failed to parse, and whether REVYL_API_KEY was absent, unresolved, or present. An unresolved value means the host passed its literal interpolation syntax rather than the secret itself.

​
Cursor Cloud Agents

Cloud Agents do not inherit the CLI installation or credentials from your local machine. Install the Cursor plugin; its hooks download the pinned CLI. Then:
  1. Ask the agent to run revyl auth login and post the approval URL as a clickable markdown link, or add optional REVYL_API_KEY as a Runtime Secret for unattended agents.
  2. Start a new Cloud Agent so hooks can see the environment.
  3. Ask the agent to run the app with a remote build.
If you install the CLI yourself in Cloud setup instead of using the plugin, use the GitHub raw installer above. Optional custom MCP must use a literal command (revyl or /usr/local/bin/revyl), never ${CURSOR_PLUGIN_ROOT} or ${env:...}. Cloud Agents do not start plugin MCP.

​
When the agent reports cloud_secret_required

A Cloud Agent injects Runtime Secrets into the shell, but the MCP server runs as a separate process that may not see them. Bridge the secret from a terminal in the agent:
The command copies REVYL_API_KEY from the current shell into the credential store. It reads an existing secret and cannot create one: if no key is present, run revyl auth login and post the printed approval URL, or add optional REVYL_API_KEY as a Runtime Secret and start a fresh Cloud Agent. Never paste the secret value into chat, a command argument, or a commit. The bridge reads it from the environment and never prints it.

​
Manual CLI fallback

Use the standalone CLI for CI, terminal workflows, unsupported MCP clients, offline environments, advanced operations, or recovery. Install it with the platform command above, then run the bounded loop from the app directory:
Run from the actual app root in a monorepo. If framework detection is wrong, rerun detection from that root:
If the detected recipe still needs adjustment, edit the named profile in .revyl/config.yaml directly and run revyl config validate. For Xcode, pass a scheme during detection with --xcode-scheme <platform-key>=<scheme> so Revyl embeds it in the generated build commands. Use revyl dev list, explicit contexts, or revyl dev attach only when intentionally reusing an existing session. See the full dev-loop guide for framework-specific behavior.

​
Verify

Start a new agent chat and ask:
The agent should share the viewer URL immediately, return device-backed evidence, and stop the device when finished. For proving CI-uploaded PR builds with a Cursor Automation (no Revyl GitHub App), see Cursor proof (BYO-CI).