@runalabs/rill-cli 0.1.3 → 0.1.4

package/README.md

@@ -1,32 +1,241 @@
 # @runalabs/rill-cli
 
-Record, inspect, and share agent-controlled browser runs with Rill.
+Record a browser flow, keep its video and runtime evidence together, and return an inspectable share link. Use Rill to reproduce a bug, verify a change, or hand a browser run to another developer or agent.
 
-After `rill record stop`, compatible agent hosts may receive `feedbackRequested: true`. They can submit a short Rill product review with `rill feedback submit <recording-id>`. Use `rill record stop <recording-id> --no-feedback` to opt out for one run.
+Rill starts a local Chromium recorder. Your browser tool drives the returned CDP endpoint; Rill captures the selected page and uploads the result when you stop.
 
-## Install
+[Getting started](https://userill.dev/docs) · [Website CLI reference](https://userill.dev/docs/cli) · [Agent instructions](https://userill.dev/docs/cli#agents)
+
+## Install and verify
+
+Browser recording runs on macOS and Linux. Install Node.js 22+, Google Chrome or Chromium, and ffmpeg on `PATH`.
 
 ```sh
-npm install --global @runalabs/rill-cli@0.1.3
-rill doctor
+# macOS
+brew install ffmpeg
+# Debian / Ubuntu
+sudo apt install ffmpeg
 ```
 
-Rill requires Node.js 22 or newer, Google Chrome or Chromium, and `ffmpeg`.
-
-## Record
+Then install the scoped package:
 
 ```sh
+npm install --global @runalabs/rill-cli
+rill --version
 rill login
 rill doctor
-rill record start --url https://example.com --title "Agent reproduction"
-# Connect browser automation to the returned cdpUrl.
+```
+
+Do not use `npx rill`: the unscoped package belongs to a different product. Doctor checks Node, API reachability, CLI compatibility, authentication, Chrome, and ffmpeg. Resolve failed checks before starting a run.
+
+## Authenticate
+
+### Interactive login
+
+`rill login` prints a verification URL and device code. Open the URL, sign in, and approve the request. The CLI waits for approval and stores the credential in macOS Keychain or Linux Secret Service using `secret-tool`. Linux needs an available Secret Service keyring; use token authentication on headless machines without one.
+
+### CI and unattended agents
+
+Create a scoped, expiring agent credential in Rill Settings. Inject it as `RILL_TOKEN` through your environment's secret manager, then run `rill doctor`. This token takes precedence over the OS keychain. Do not put real tokens in source files or command examples.
+
+The default API is `https://userill.dev`. `RILL_API_URL` changes it; the global `--api-url <url>` flag takes precedence. Login stores credentials per API URL. Manage and revoke credentials in Settings.
+
+## First recording
+
+```sh
+rill record start --url https://example.com --title "Checkout verification"
+# Save recordingId and connect your browser tool to the returned cdpUrl.
+# Perform the flow in the existing recorded page.
 rill record stop <recording-id>
+rill inspect https://userill.dev/s/<share-secret>
+```
+
+Start returns `recordingId`, `cdpUrl`, `status`, `bodyCaptureEnabled`, and `maxDurationSeconds`. Stop finalizes capture, uploads video and diagnostics, and waits for playback. Confirm `status: "ready"` and a non-null `shareUrl` before returning the evidence link. Local capture finishing does not establish remote readiness.
+
+### Connect Playwright
+
+In a project with `playwright-core` installed, save this as `rill-run.mjs`:
+
+```js
+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();
+}
+```
+
+Run `node rill-run.mjs "<cdpUrl>"` with the exact endpoint from start. Then run `rill record stop <recording-id>`, including when your verification fails. A page title alone does not verify your app's behavior.
+
+Capture follows the first page selected at recording start. Keep the flow in that page: new tabs and popups do not receive complete video and diagnostic coverage. Keep the recorded page open until Rill stops.
+
+### Recording options
+
+| Option | Behavior |
+| --- | --- |
+| `--url <url>` | Open the target in a managed browser. |
+| `--title <title>` | Name the run; defaults to a timestamped title. |
+| `--description <text>` | Describe what the run demonstrates. |
+| `--headed` | Show the managed browser; default is headless. |
+| `--cdp-url <url>` | Attach to an existing Chromium browser and record its first open page. Navigate that page with your browser tool. |
+| `--width <pixels>` / `--height <pixels>` | Managed viewport; defaults to 1280 × 720. |
+| `--max-duration <seconds>` | Automatically finalize local capture; defaults to 600. Still call `record stop` to upload. |
+
+Rill closes browsers it launches during finalization. Attached browsers remain open.
+
+## Set up a coding agent
+
+Install and authenticate the CLI where the agent runs. No separate skill installation is required. Optionally save the following workflow in your agent's project instructions or skill setup; it is also available in the [public agent instructions](https://userill.dev/docs/cli#agents):
+
+1. Run `rill doctor` and resolve failed checks.
+2. Start a run titled with the claim to verify.
+3. Preserve `recordingId`; connect to `cdpUrl` using a browser tool that supports CDP.
+4. Perform the authorized flow in the existing recorded page.
+5. Stop the same recording and wait for readiness.
+6. Inspect the returned share URL.
+7. Return the link with what passed, failed, or could not be verified.
+
+For a bug fix, record the reproduction and verification as separate runs. Attach the ready link to the handoff or pull request.
+
+## Inspect a shared run
+
+```sh
+rill inspect https://userill.dev/s/<share-secret>
+rill inspect https://userill.dev/s/<share-secret> > context.json
+```
+
+Inspect returns bounded JSON context for another agent without requiring login. Browser recordings carry video and synchronized console messages, exceptions, network metadata, navigation, and interaction events. Treat this as bounded evidence, not a guarantee of complete capture. Use the share page to watch the run and examine its diagnostics.
+
+An active share URL is required. Expired, replaced, revoked, or deleted shares cannot be inspected; ask the owner for a current link.
+
+## Upload an existing video
+
+```sh
+rill upload ./test-results/checkout.webm --title "Checkout test"
+```
+
+Upload WebM or MP4 evidence. The command waits for readiness and returns the recording ID and share URL. Existing uploads report `diagnosticsAvailable: false`; they do not import Playwright traces or reconstruct diagnostic events.
+
+Both `upload` and `record stop` accept `--no-wait`. This still waits for upload but skips playback processing: the result is `status: "processing"` with `shareUrl: null`. Check the recording in the dashboard before sharing.
+
+## Command reference
+
+Use `rill --help` or `<command> --help` for supported flags.
+
+| Command | Behavior |
+| --- | --- |
+| `rill login` | Authorize a device code and store a credential. |
+| `rill doctor` | Check prerequisites, API compatibility, and authentication. |
+| `rill record start [options]` | Start a managed or attached browser recording. |
+| `rill record stop <recording-id>` | Finalize and upload; supports `--no-wait` and `--no-feedback`. |
+| `rill record status <recording-id>` | Read local state, falling back to remote state if the local session is unavailable. |
+| `rill record cancel <recording-id>` | Abandon a run created by this credential and release its remote quota reservation. |
+| `rill upload <video-file>` | Upload video-only evidence; supports `--title` and `--no-wait`. |
+| `rill inspect <share-url>` | Read bounded context without login. |
+| `rill drafts list` | List directory names under the local draft root. |
+| `rill drafts purge` | Delete draft directories last modified more than 24 hours ago. |
+| `rill feedback submit <recording-id>` | Submit optional Rill-specific feedback. |
+
+## Output and errors
+
+Data commands emit JSON on stdout and human progress on stderr. Use global `--pretty` for indented JSON. Help and version commands print plain text.
+
+```sh
+rill --pretty record status <recording-id>
 ```
 
-If the local recorder is unavailable, `rill record status <recording-id>` falls
-back to the control plane. Use `rill record cancel <recording-id>` to abandon an
-active recording and release its quota reservation. A failed local startup
-automatically cancels the reservation it just created.
+Selected fields from a successful stop result:
+
+```json
+{
+  "schemaVersion": 1,
+  "recordingId": "<recording-id>",
+  "status": "ready",
+  "shareUrl": "https://userill.dev/s/<share-secret>"
+}
+```
+
+Stop also returns duration, stop reason, diagnostic summary, and feedback instructions when applicable.
+
+Success exits 0; command failures exit 1. Runtime failures emit an `error` object on stdout containing `code`, `message`, and optional `recovery` and `details`. Argument parsing failures may print plain text to stderr. Doctor exits 1 with its JSON check report when a check fails.
+
+Check the exit status first, then structured fields. Known codes include `authentication_required`, `scope_denied`, `quota_exceeded`, `browser_unavailable`, `recording_not_found`, `upload_interrupted`, `processing_failed`, `share_revoked`, `validation_failed`, and the fallback `internal_error`. Not every failure has a specific code; avoid branching on message text.
+
+## Recovery and troubleshooting
+
+- **Doctor fails:** read the failed check's recovery field. Correct the credential, API connectivity, or executable path before recording.
+- **Quota exceeded:** inspect `error.details.quota.type` and `blockingRecordingId` when present. Check the blocking recording; cancel only an abandoned run. Review storage and daily allowance in Billing.
+- **Upload interrupted or processing timed out:** keep the recording ID and local artifacts. Check the dashboard for remote readiness. `record status` prefers local state and can report local `ready` without a share URL; this does not prove remote playback readiness.
+- **Duration limit reached:** local capture finalizes automatically, but `record stop` is still needed to upload.
+- **Local session missing:** `record status` falls back to remote state. `drafts list` locates local directories, which may be incomplete. There is no `drafts resume` command.
+- **Share cannot be inspected:** open the complete URL in a browser; ask the owner for a current link if needed.
+
+A failed local startup automatically attempts to cancel the remote reservation it just created. `record cancel` changes remote state and does not stop the local browser; finish local capture before abandoning the remote reservation.
+
+When finalized artifacts survive, retain `recording.webm` and `diagnostics-v1.ndjson.gz` in the recording's draft directory. `rill upload <path-to-recording.webm>` is a video-only fallback: it creates a new recording and does not restore the original diagnostics. Successful stop with readiness removes that run's local artifact directory.
+
+`drafts purge` deletes local draft directories older than 24 hours by modification time, without a confirmation prompt. Recover needed evidence before purging.
+
+## Environment variables
+
+| Variable | Purpose |
+| --- | --- |
+| `RILL_TOKEN` | Agent credential; overrides the keychain. |
+| `RILL_API_URL` | API origin; defaults to `https://userill.dev`. Global `--api-url` takes precedence. |
+| `RILL_CHROME_PATH` | Chrome or Chromium executable path. |
+| `RILL_FFMPEG` | ffmpeg executable; defaults to `ffmpeg` on `PATH`. |
+| `RILL_HOME` | Recorder state directory; defaults to `~/.rill`. |
+| `RILL_SOCKET` | Recorder socket; defaults to `recorder.sock` inside `RILL_HOME`. |
+| `RILL_TEMP` | Artifact root; defaults to `rill-recordings` inside the system temporary directory. |
+
+Set recorder variables before starting the background recorder; an existing recorder retains its original environment. Use the same configuration for recording, stopping, and draft recovery.
+
+## Sharing and privacy
+
+Ready recordings get an unlisted share link that expires after seven days. In the recording page, copy it, replace it with a fresh link, or stop sharing. Finished recordings can be deleted after a five-second undo window.
+
+Diagnostic redaction targets cookies, credential headers, URL query values, fragments, embedded credentials, and secret-shaped values. Network-body capture defaults off and is controlled by the human-issued credential; the agent cannot enable it for itself. Redaction is best-effort and does not mask the video. Avoid displaying secrets, review evidence before sharing, and treat share URLs as sensitive.
+
+## Optional agent feedback
+
+After `record stop`, compatible hosts may receive `feedbackRequested: true` and a structured `suggestedAction`. When requested, agents should submit a short Rill-specific review if practical. Workspace opt-in pre-authorizes it; feedback is optional and must not delay or affect the recording result.
+
+```sh
+rill feedback submit <recording-id> --outcome succeeded --improvement "Make processing progress clearer"
+```
+
+`--outcome` must be `succeeded`, `failed`, or `abandoned`. Include at least one of `--helped`, `--friction`, or `--improvement`. Omit credentials, personal data, and copied page content. Feedback goes to Rill's operators and is not shown on public evidence pages.
+
+Skip feedback when it is not requested. Use `rill record stop <recording-id> --no-feedback` to opt out for one run. A feedback failure must not delay returning the share URL.
+
+## Update and uninstall
+
+```sh
+npm install --global @runalabs/rill-cli@latest
+rill --version
+rill doctor
+```
+
+Remove the package:
+
+```sh
+npm uninstall --global @runalabs/rill-cli
+```
+
+This leaves keychain credentials, recorder state, local drafts, and remote recordings in place. Revoke the credential in Settings if access should end, and remove `RILL_TOKEN` from the environment or secret manager. To remove a stored local credential for the default API:
+
+```sh
+# macOS
+security delete-generic-password -a https://userill.dev -s rill
+# Linux
+secret-tool clear service rill api-url https://userill.dev
+```
 
-Commands emit one schema-versioned JSON object to stdout. Human-readable
-progress is written to stderr.
+Substitute your API URL if you configured another environment. These commands clear the local credential; server-side revocation is managed in Settings.

package/dist/cli.js

@@ -945,6 +945,28 @@ function controlPlaneUrl(environmentUrl) {
   return environmentUrl ?? PRODUCTION_API_URL;
 }
 
+// src/feedback-protocol.ts
+function suggestedFeedbackAction(recordingId) {
+  return {
+    type: "rill.feedback.submit",
+    recommended: true,
+    authorizedBy: "workspace_opt_in",
+    confirmationRequired: false,
+    failurePolicy: "non_blocking",
+    recordingId
+  };
+}
+function recordingFeedbackFields(recordingId, feedbackRequested) {
+  return feedbackRequested ? { feedbackRequested: true, suggestedAction: suggestedFeedbackAction(recordingId) } : { feedbackRequested: false };
+}
+function feedbackSubmissionReceipt(recordingId) {
+  return {
+    schemaVersion: 1,
+    recordingId,
+    feedbackStatus: "submitted"
+  };
+}
+
 // src/cli.ts
 var program = new Command();
 program.name("rill").description("Record, inspect, and share agent browser runs.").version(CLI_VERSION).option("--api-url <url>", "Rill control plane", controlPlaneUrl(process.env.RILL_API_URL)).option("--pretty", "Pretty-print JSON output", false);
@@ -1016,7 +1038,16 @@ record.command("stop").argument("<recording-id>").option("--no-wait").option("--
   await Promise.all([client.uploadVideo(provisioned.uploadUrl, local.result.videoPath), client.uploadDiagnostics(recordingId, local.result.diagnosticsPath, local.result.diagnostics)]);
   const remote = commandOptions.wait === false ? null : await client.waitUntilPlayable(recordingId);
   if (remote) process.stderr.write("\n");
-  const result = { schemaVersion: 1, recordingId, status: remote ? "ready" : "processing", shareUrl: remote?.shareUrl ?? null, durationSeconds: local.result.durationSeconds, stoppedReason: local.result.stoppedReason, diagnostics: local.result.diagnostics, feedbackRequested: stopped?.feedbackRequested ?? false };
+  const result = {
+    schemaVersion: 1,
+    recordingId,
+    status: remote ? "ready" : "processing",
+    shareUrl: remote?.shareUrl ?? null,
+    durationSeconds: local.result.durationSeconds,
+    stoppedReason: local.result.stoppedReason,
+    diagnostics: local.result.diagnostics,
+    ...recordingFeedbackFields(recordingId, stopped?.feedbackRequested ?? false)
+  };
   emit(result, options.pretty);
   if (remote) await rm2(dirname2(local.result.videoPath), { recursive: true, force: true });
 });
@@ -1033,6 +1064,7 @@ feedback.command("submit").argument("<recording-id>").requiredOption("--outcome
     friction: commandOptions.friction,
     improvement: commandOptions.improvement
   });
+  emit(feedbackSubmissionReceipt(recordingId), options.pretty);
 });
 record.command("status").argument("<recording-id>").action(async (recordingId) => {
   const options = program.opts();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runalabs/rill-cli",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Record, inspect, and share agent-controlled browser runs with Rill.",
   "license": "Apache-2.0",
   "repository": {