@runalabs/rill-cli 0.1.3 → 0.1.5

package/README.md

@@ -1,32 +1,245 @@
 # @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>
+```
+
+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
+
+Feedback begins with `rill doctor` and `rill record start`. When the workspace enables it, their JSON includes `feedbackRequested: true` and a `feedbackBrief` asking the agent to observe what went well, confusion or friction, and possible improvements throughout setup and the run. Review only Rill and report observed experience, not invented praise or issues.
+
+At completion or abandonment, `record stop` still returns the recommended, pre-authorized `suggestedAction`. Submit a short review if practical:
+
+```sh
+rill feedback submit <recording-id> --outcome succeeded --helped "The CDP URL was easy to connect to" --friction "Upload progress was unclear" --improvement "Explain upload and processing stages"
+```
+
+Startup errors retain the brief under `error.details`, with the recording ID when one was reserved. If no recording exists, submit setup feedback without an ID using `--outcome failed` or `--outcome abandoned`. Successful submission returns `feedbackStatus: "submitted"` and the recording ID (null for setup-only feedback).
+
+Only use `--no-feedback` when the user explicitly requests it, including in demos and tests. Respect the workspace preference. Feedback is optional, pre-authorized, and must not delay or affect the recording result. Authentication or connectivity failures may prevent feedback; preserve the original task result.
+
+Setup-only feedback requires the API endpoint `POST /api/feedback` and migration `0012_setup_feedback.sql`. Deploy the migration and API before distributing this CLI change. Existing recording feedback remains compatible.
+
+## Update and uninstall
+
+```sh
+npm install --global @runalabs/rill-cli@latest
+rill --version
+rill doctor
 ```
 
-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.
+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

@@ -601,7 +601,7 @@ var ControlPlaneClient = class {
     return this.request("/api/health", {}, false);
   }
   agentSession() {
-    return this.request("/api/agent/session");
+    return this.request("/api/agent/session", { signal: AbortSignal.timeout(5e3) });
   }
   reportCliCommand(input) {
     return this.request("/api/analytics/cli-command", { method: "POST", body: JSON.stringify(input) });
@@ -622,7 +622,7 @@ var ControlPlaneClient = class {
     });
   }
   submitRecordingFeedback(recordingId, input) {
-    return this.request(`/api/recordings/${recordingId}/feedback`, {
+    return this.request(recordingId ? `/api/recordings/${recordingId}/feedback` : "/api/feedback", {
       method: "POST",
       body: JSON.stringify(input)
     });
@@ -794,6 +794,62 @@ function fail(error) {
   process.exitCode = 1;
 }
 
+// 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"
+  };
+}
+function runFeedbackFields(feedbackEnabled, recordingId = null) {
+  return feedbackEnabled ? {
+    feedbackRequested: true,
+    feedbackBrief: {
+      authorizedBy: "workspace_opt_in",
+      confirmationRequired: false,
+      failurePolicy: "non_blocking",
+      recordingId,
+      instruction: "Observe your Rill experience throughout setup and the run. At completion or abandonment, submit a short factual review if practical. Feedback is optional and must not delay or affect the recording result. Only use --no-feedback when the user explicitly requests it.",
+      prompts: {
+        whatHelped: "What went well? Which Rill commands, browser setup steps, outputs, or recovery guidance helped?",
+        friction: "Where did you get confused, get stuck, or need to guess? Consider prerequisites, starting or connecting to the browser, commands, diagnostics, uploads, and recovery.",
+        improvement: "What possible improvements would make Rill easier or more useful? Prioritize actionable ideas grounded in this run."
+      },
+      submitCommand: `rill feedback submit${recordingId ? ` ${recordingId}` : ""} --outcome <${recordingId ? "succeeded|failed|abandoned" : "failed|abandoned"}> --helped <text> --friction <text> --improvement <text>`,
+      scope: "Review Rill, not the target website. Report only observed experience; do not invent problems or praise. Exclude credentials, personal data, and copied page content."
+    }
+  } : { feedbackRequested: false };
+}
+async function withRunFeedback(session, start) {
+  const enabled = await session().then((value) => value.agentFeedbackEnabled).catch(() => false);
+  let recordingId = null;
+  try {
+    const result = await start((id) => {
+      recordingId = id;
+    });
+    return { ...result, ...runFeedbackFields(enabled, result.recordingId) };
+  } catch (cause) {
+    const error = cause instanceof Error ? cause : new Error(String(cause));
+    const structured = error;
+    structured.details = { ...structured.details, ...runFeedbackFields(enabled, recordingId) };
+    throw error;
+  }
+}
+
 // src/doctor.ts
 import { spawn as spawn5 } from "child_process";
 
@@ -816,6 +872,7 @@ var defaultDependencies = {
 async function runDoctor(apiUrl, overrides = {}) {
   const dependencies = { ...defaultDependencies, ...overrides };
   const checks = [];
+  let feedbackEnabled = false;
   if (compareVersions(normalizeVersion(dependencies.nodeVersion), "22.0.0") >= 0) {
     checks.push({ name: "node", status: "pass", message: `Node.js ${dependencies.nodeVersion} is supported.`, version: dependencies.nodeVersion });
   } else {
@@ -849,6 +906,7 @@ async function runDoctor(apiUrl, overrides = {}) {
     } else {
       try {
         const session = await dependencies.agentSession(apiUrl, token);
+        feedbackEnabled = session.agentFeedbackEnabled;
         checks.push({ name: "authentication", status: "pass", message: `Credential is valid with ${session.scopes.length} scope${session.scopes.length === 1 ? "" : "s"}.` });
       } catch (error) {
         checks.push({ name: "authentication", status: "fail", message: `Credential validation failed: ${errorMessage(error)}`, recovery: `Run \`rill --api-url ${apiUrl} login\` to authorize a fresh credential.` });
@@ -857,7 +915,7 @@ async function runDoctor(apiUrl, overrides = {}) {
   }
   checks.push(await executableCheck("chrome", dependencies.chromePath, ["--version"], dependencies.commandVersion, "Install Google Chrome or Chromium, or set RILL_CHROME_PATH to its executable."));
   checks.push(await executableCheck("ffmpeg", dependencies.ffmpegPath, ["-version"], dependencies.commandVersion, process.platform === "darwin" ? "Install ffmpeg with `brew install ffmpeg`, or set RILL_FFMPEG." : "Install ffmpeg using the system package manager, or set RILL_FFMPEG."));
-  return { schemaVersion: 1, status: checks.some((check) => check.status === "fail") ? "error" : "ok", apiUrl, checks };
+  return { schemaVersion: 1, status: checks.some((check) => check.status === "fail") ? "error" : "ok", apiUrl, checks, ...runFeedbackFields(feedbackEnabled) };
 }
 async function executableCheck(name, path, args, run2, recovery) {
   try {
@@ -979,26 +1037,30 @@ record.command("start").option("--url <url>").option("--title <title>").option("
   const options = program.opts();
   const token = await loadCredential(options.apiUrl);
   const client = new ControlPlaneClient(options.apiUrl, token);
-  const width = Number(commandOptions.width);
-  const height = Number(commandOptions.height);
-  const remote = await client.createRecording({ title: commandOptions.title ?? `Browser recording \xB7 ${(/* @__PURE__ */ new Date()).toISOString()}`, description: commandOptions.description, sourceUrl: commandOptions.url ?? null, width, height });
-  const local = await startRecordingWithCompensation(remote, {
-    startLocal: async () => {
-      await ensureDaemon(process.argv[1]);
-      return startRecording({ recordingId: remote.recordingId, url: commandOptions.url, cdpUrl: commandOptions.cdpUrl, headed: Boolean(commandOptions.headed), width, height, maxDurationSeconds: Number(commandOptions.maxDuration), captureNetworkBodies: remote.bodyCaptureEnabled });
-    },
-    cancelRemote: (recordingId, reason) => client.cancelRecording(recordingId, reason)
+  const result = await withRunFeedback(() => client.agentSession(), async (rememberRecording) => {
+    const width = Number(commandOptions.width);
+    const height = Number(commandOptions.height);
+    const remote = await client.createRecording({ title: commandOptions.title ?? `Browser recording \xB7 ${(/* @__PURE__ */ new Date()).toISOString()}`, description: commandOptions.description, sourceUrl: commandOptions.url ?? null, width, height });
+    rememberRecording(remote.recordingId);
+    const local = await startRecordingWithCompensation(remote, {
+      startLocal: async () => {
+        await ensureDaemon(process.argv[1]);
+        return startRecording({ recordingId: remote.recordingId, url: commandOptions.url, cdpUrl: commandOptions.cdpUrl, headed: Boolean(commandOptions.headed), width, height, maxDurationSeconds: Number(commandOptions.maxDuration), captureNetworkBodies: remote.bodyCaptureEnabled });
+      },
+      cancelRemote: (recordingId, reason) => client.cancelRecording(recordingId, reason)
+    });
+    await client.markRecordingStarted(remote.recordingId, {
+      cliVersion: CLI_VERSION,
+      os: process.platform,
+      arch: process.arch,
+      headed: Boolean(commandOptions.headed),
+      attached: Boolean(commandOptions.cdpUrl)
+    }).catch(() => void 0);
+    return { schemaVersion: 1, recordingId: remote.recordingId, status: local.status, cdpUrl: local.cdpUrl, bodyCaptureEnabled: remote.bodyCaptureEnabled, maxDurationSeconds: Number(commandOptions.maxDuration) };
   });
-  await client.markRecordingStarted(remote.recordingId, {
-    cliVersion: CLI_VERSION,
-    os: process.platform,
-    arch: process.arch,
-    headed: Boolean(commandOptions.headed),
-    attached: Boolean(commandOptions.cdpUrl)
-  }).catch(() => void 0);
-  emit({ schemaVersion: 1, recordingId: remote.recordingId, status: local.status, cdpUrl: local.cdpUrl, bodyCaptureEnabled: remote.bodyCaptureEnabled, maxDurationSeconds: Number(commandOptions.maxDuration) }, options.pretty);
+  emit(result, options.pretty);
 });
-record.command("stop").argument("<recording-id>").option("--no-wait").option("--no-feedback").action(async (recordingId, commandOptions) => {
+record.command("stop").argument("<recording-id>").option("--no-wait").option("--no-feedback", "Disable feedback only when the user explicitly requests it").action(async (recordingId, commandOptions) => {
   const options = program.opts();
   await ensureDaemon(process.argv[1]);
   const local = await stopRecording(recordingId);
@@ -1016,23 +1078,34 @@ 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 });
 });
 var feedback = program.command("feedback").description("Submit a short Rill product review for a recorded run.");
-feedback.command("submit").argument("<recording-id>").requiredOption("--outcome <outcome>", "succeeded, failed, or abandoned").option("--helped <text>", "What helped during the run", "").option("--friction <text>", "What created friction during the run", "").option("--improvement <text>", "The single most useful Rill improvement", "").action(async (recordingId, commandOptions) => {
+feedback.command("submit").argument("[recording-id]", "Omit only when setup failed before a recording was created").requiredOption("--outcome <outcome>", "succeeded, failed, or abandoned").option("--helped <text>", "What went well or helped during setup and the run", "").option("--friction <text>", "What created friction during the run", "").option("--improvement <text>", "Possible Rill improvements, prioritized by usefulness", "").action(async (recordingId, commandOptions) => {
+  if (!recordingId && commandOptions.outcome === "succeeded") throw new Error("validation_failed: Setup feedback without a recording must have a failed or abandoned outcome.");
   if (!["succeeded", "failed", "abandoned"].includes(commandOptions.outcome)) throw new Error("validation_failed: Feedback outcome must be succeeded, failed, or abandoned.");
   if (![commandOptions.helped, commandOptions.friction, commandOptions.improvement].some((value) => value.trim())) throw new Error("validation_failed: Include at least one short feedback answer.");
   const options = program.opts();
   const token = await loadCredential(options.apiUrl);
   const client = new ControlPlaneClient(options.apiUrl, token);
-  await client.submitRecordingFeedback(recordingId, {
+  await client.submitRecordingFeedback(recordingId ?? null, {
     outcome: commandOptions.outcome,
     whatHelped: commandOptions.helped,
     friction: commandOptions.friction,
     improvement: commandOptions.improvement
   });
+  emit(feedbackSubmissionReceipt(recordingId ?? null), 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.5",
   "description": "Record, inspect, and share agent-controlled browser runs with Rill.",
   "license": "Apache-2.0",
   "repository": {