Record the run.
Keep the evidence.

What you can do

Make a browser run inspectable.

Record a bug reproduction, verify a fix, or hand a browser test to another person with the evidence attached. Rill runs a local Chromium recorder and gives your browser automation a CDP endpoint to control.

Quick start

Install, authenticate, verify.

Browser recording runs on macOS and Linux. Install Node.js 22 or newer, Google Chrome or Chromium, and ffmpeg on your path. On macOS, install ffmpeg with brew install ffmpeg; on Debian or Ubuntu, use sudo apt install ffmpeg.

Authenticate

Authorize a browser agent.

Interactive login

Run rill login, open the verification URL printed in your terminal, and enter the device code. Sign in and approve the request in your browser. The CLI waits for approval, then stores the credential in macOS Keychain or Linux Secret Service using secret-tool.

On Linux, browser login needs secret-tool and an available Secret Service keyring. Use a token in headless environments without a keyring.

Unattended runs and CI

Create a scoped, expiring agent credential in Rill Settings and inject it as RILL_TOKEN through your environment’s secret manager. It takes precedence over the keychain credential. Run rill doctor in that environment to check API reachability, credential validity, CLI compatibility, Chrome, and ffmpeg.

Agent credentials carry their own scopes and network-body capture policy. Manage and revoke them in Settings. The CLI defaults to https://userill.dev; credentials stored by login are associated with the selected API URL.

Set up your agent

Teach it the recording loop.

Install and authenticate the CLI in the environment where your agent runs. No separate skill installation is required. For a reusable workflow, copy these instructions into your agent’s project instructions or save them as a skill using your host’s supported setup.

Use Rill to record the browser flow you are verifying.
1. Run rill doctor and resolve failed checks.
2. Start with rill record start --url <target-url> --title "<claim to verify>".
3. Save recordingId and connect your browser tool to the returned cdpUrl.
4. Perform the authorized flow in the existing recorded page.
5. Run rill record stop <recording-id> to upload and wait for readiness.
6. Confirm status is ready and shareUrl is non-null, then inspect the link.
7. Return the share URL with what passed, failed, or could not be verified.

The browser tool must support connecting to an existing Chromium browser over CDP. Keep the recorded page open until Rill stops. For a bug fix, record the reproduction and verification as separate runs with clear titles.

Record a run

Start, connect, work, stop.

The start response contains a recordingId and cdpUrl. Preserve both. After the agent finishes, stop the same recording; Rill uploads the video and diagnostics and waits for a playable share URL. Success means status: "ready" with a non-null shareUrl. A locally finalized video alone is not a ready share.

Browser automation example

Connect Playwright to the recorded page.

In a project with playwright-core installed, save this as rill-run.mjs. Start the recording above, then run node rill-run.mjs "<cdpUrl>" using the exact URL from its JSON response. Run rill record stop after the script finishes, including when verification fails.

import { chromium } from 'playwright-core';

const browser = await chromium.connectOverCDP(process.argv[2]);
try {
  const page = browser.contexts()[0].pages()[0];
  if (!page) throw new Error('The recorded page is unavailable.');
  await page.waitForLoadState('domcontentloaded');
  // Add your flow and assertions here, using this page.
  console.log(await page.title());
} finally {
  // Disconnect this client; let rill record stop finalize the recording.
  await browser.close();
}

Capture follows the first page selected when recording starts. Keep verification in that page; new tabs and popups do not receive complete video and diagnostic coverage. A page title alone is not a verification of your app’s behavior.

Rill closes browsers it launches when finalizing. An attached browser remains open.

Upload a video

Bring an existing test artifact.

Upload an existing WebM or MP4. The command waits for readiness and returns the recording ID and share URL. The result reports diagnosticsAvailable: false: upload does not import Playwright traces or reconstruct console and network events.

Both upload and record stop accept --no-wait. Upload still completes, but the command returns status: "processing" and shareUrl: null without waiting for playback. Check the recording in the dashboard before sharing.

Command reference

Find the command you need.

Run rill --help or add --help to a subcommand for its supported arguments and flags.

Output and errors

Use JSON in scripts and agents.

Data commands write JSON to stdout and human progress to stderr. Use the global --pretty flag for indented JSON. Successful recording receipts include schemaVersion: 1. Help and version commands print plain text.

{
  "schemaVersion": 1,
  "recordingId": "<recording-id>",
  "status": "ready",
  "shareUrl": "https://userill.dev/s/<share-secret>"
}

This example shows selected fields. Stop also returns duration, stop reason, diagnostic summary, and feedback instructions when applicable.

Success exits 0. Command failures exit 1; runtime failures return an error object on stdout with code, message, and optional recovery and details. Argument parsing errors may print plain text to stderr. Doctor exits 1 with its JSON check report when a check fails.

Check the exit status first, then inspect structured fields. Useful error codes include authentication_required, scope_denied, quota_exceeded, browser_unavailable, processing_failed, and internal_error.

Environment variables

Configure the CLI and recorder.

Set recorder variables before starting the background recorder. An already running recorder retains the environment it started with. Keep the same configuration when recording, stopping, and recovering drafts.

Recover a run

Interrupted does not mean lost.

Troubleshooting

Keep the recording ID when something fails.

When finalized artifacts survive, retain both recording.webm and diagnostics-v1.ndjson.gz in the recording’s draft directory. As a video-only fallback, use rill upload on the WebM; this creates a new recording and does not restore the original diagnostics.

record cancel changes remote state; it does not stop the local browser. Finish local capture before abandoning its remote reservation. Purging drafts deletes local files immediately, so recover needed evidence first.

60-second inspection

Give the next agent facts, not a retelling.

1. 1

   Copy the unlisted Rill share URL from the handoff.

2. 2

   Run rill inspect with the complete share URL.

3. 3

   Give the bounded JSON context to the next agent alongside the task.

A ready share combines the browser video with synchronized console messages, exceptions, network metadata, navigation, and interaction events. Existing video uploads remain video-only and do not claim diagnostic coverage.

Manage evidence

Share deliberately. Delete completely.

Every ready recording receives one unlisted share link that expires after seven days. From the recording page, copy it, replace it with a new seven-day link, or stop sharing immediately. Replaced, stopped, and expired links cannot be reopened.

Delete a finished recording from the same page. After a five-second undo window, the recording and diagnostics disappear from your workspace and active share links stop working.

Privacy boundary

Capture is constrained by the credential.

Diagnostic redaction targets cookies, credential headers, URL query values, fragments, embedded credentials, and secret-shaped values. Network-body capture is controlled by the human-issued credential and defaults off; an agent cannot enable it for itself.

Redaction is best-effort and does not mask the recorded video. Avoid displaying secrets or sensitive personal data in the browser, and review evidence before sharing.

Treat unlisted share URLs as sensitive. Share expiry, revocation, and deletion apply to both the video and its diagnostic evidence.

Optional feedback

Help improve Rill after the handoff.

When a workspace owner opts in, a stop result may include feedbackRequested: true and a structured suggestedAction. Compatible agents should submit a short Rill-specific review when practical; the workspace opt-in pre-authorizes it. Feedback is optional and must never block or delay returning the recording.

--outcome accepts succeeded, failed, or abandoned. Include at least one of --helped, --friction, or --improvement. Keep it about Rill and omit credentials, personal data, and copied page content.

Skip feedback when it is not requested. Use rill record stop <recording-id> --no-feedback to opt out for a run. Feedback is for Rill’s operators and does not appear on the public evidence page.

Update

Keep the Rill CLI current.

Install the latest published version, then verify the update: