@runalabs/rill-cli 0.1.15 → 0.1.17

package/README.md

@@ -25,6 +25,10 @@ The following local-recording instructions remain available through `record star
 
 ## Install and verify
 
+Check `node --version`, `node -p "process.platform"`, and `rill --version` before installing. Reuse an installed compatible CLI. Commands execute in the agent's environment, which may be a separate sandbox from the user's desktop. Chrome must be accessible there, and the agent must be able to attach over CDP; doctor does not verify browser-control capability.
+
+If the CLI is missing, check npm with `npm ping --fetch-timeout=5000 --fetch-retries=0` before installation. See the [canonical skill](https://userill.dev/skill.md) for the bounded Rill connectivity check and Windows Terminal fallback. Report blocked network access instead of repeating installation attempts.
+
 Browser recording runs on macOS, Linux, and Windows. Install Node.js 22+ and Google Chrome or Chromium. Rill encodes recordings remotely by default; local FFmpeg is optional. Chrome stays on your machine and can access localhost. Raw frames upload after recording stops.
 
 Then install the scoped package:
@@ -42,7 +46,7 @@ Do not use `npx rill`: the unscoped package belongs to a different product. Doct
 
 ### Connect with pollable approval
 
-`rill whoami` verifies the current account without starting sign-in. `rill connect --email you@example.com` waits for human approval by default. For agents that cannot hold a foreground command open:
+`rill whoami` shows a short account summary without starting sign-in. Agents should use `rill whoami --json` for verified identity fields. `rill connect --email you@example.com` waits for human approval by default. For agents that cannot hold a foreground command open:
 
 ```sh
 rill connect --email you@example.com --no-wait
@@ -221,7 +225,20 @@ Use `rill --help` or `<command> --help` for supported flags.
 
 ## 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.
+`whoami` shows a concise human summary by default. Use `rill whoami --json` for the existing schema-versioned identity response, including email, workspace, scopes and expiry. Its exit codes are unchanged: missing credentials exit 1; connected and anonymous access exit 0.
+
+Doctor and local recording commands retain JSON on stdout by default. Use `--human` for readable doctor, login, recording start/stop/status/retry summaries and errors. Doctor shows the command execution OS, named prerequisite checks, recovery guidance, and a pass/fail/warning count. Recording summaries show the ID, status, duration when available, share URL when returned, and the exact next command. Pending processing is distinct from a ready recording; a private recording may have no share URL.
+
+Explicit `--json` or `--pretty` takes precedence over `--human`. Use `--pretty` for indented JSON. Human output uses restrained terminal color only on a TTY, respects `NO_COLOR` and `TERM=dumb`, and retains status symbols and text without color. Human errors go to stderr; JSON errors remain on stdout. Help and version commands print plain text. Feedback and attachment metadata remain available in JSON; selecting a human view does not disable workspace feedback.
+
+```sh
+rill whoami
+rill whoami --json
+rill --human doctor
+rill --human record start --url https://example.com --title "Smoke test" --headed
+rill --human record stop <recording-id>
+rill --human record status <recording-id>
+```
 
 ```sh
 rill --pretty record status <recording-id>
@@ -353,11 +370,13 @@ Progress runs through `uploading` → `queued` → `encoding` → `processing`
 
 Run `rill connect --email you@example.com` to authorize account access or keep your anonymous recordings. Open the displayed link, sign in, and enter the code yourself. Approval allows creation and reading of your existing and new recordings for 90 days, with automatic renewal of one-hour access tokens. Revoke the connection in Settings → Agent access to stop access and renewal. Deletion and changes to existing sharing settings are not included.
 
+Browser approval does not finish the handshake: the CLI must collect and save credentials. With `--no-wait`, keep polling the returned `connect status <authorizationId>` command until `authenticated`. Starting with 0.1.17, the CLI checks the server even after its local approval deadline. Approval codes expire after ten minutes; successful approval starts a separate 30-minute collection window, with a 60-second lost-response retry window after first collection. If collection expires, run `connect --email` again with the same account to request fresh human approval while preserving the registration and recordings. Do not delete saved credentials to recover. Auth requests include the CLI version for consent-aware diagnostics.
+
 Use `rill record list` to list accessible recordings and `rill inspect <recording-id>` for private recording details. `rill inspect <share-url>` continues to work without account access. The existing `rill login` and `RILL_TOKEN` flows remain supported. Local credential storage requires macOS Keychain, Linux Secret Service, or Windows current-user DPAPI.
 
 ### Check the connected account
 
-Run `rill whoami` (or `rill --pretty whoami`) to verify your current identity. JSON output includes status, account email when available, workspace, scopes, and access expiry. It uses RILL_TOKEN when set, otherwise the saved OS credential. Existing access can renew automatically; it never creates an identity or opens an approval flow. Missing credentials return `not_connected` and exit 1. Invalid or revoked credentials return an error.
+Run `rill whoami` for a short human account summary, or `rill whoami --json` (also `rill --pretty whoami`) for structured identity fields. JSON includes status, account email when available, workspace, scopes, and access expiry. It uses RILL_TOKEN when set, otherwise the saved OS credential. Existing access can renew automatically; it never creates an identity or opens an approval flow. Missing credentials return `not_connected` in JSON and exit 1. Invalid or revoked credentials return an error.
 
 ### Capture time and upload progress (0.1.14)
 

package/dist/cli.js

@@ -127,6 +127,11 @@ function browserAttachment(cdpUrl, tabId) {
   };
 }
 
+// src/version.ts
+import { createRequire } from "module";
+var packageJson = createRequire(import.meta.url)("../package.json");
+var CLI_VERSION = packageJson.version;
+
 // src/agent-session.ts
 var JWT_GRANT = "urn:ietf:params:oauth:grant-type:jwt-bearer";
 var CLAIM_GRANT = "urn:workos:agent-auth:grant-type:claim";
@@ -150,7 +155,7 @@ async function request(apiUrl, path, body, form = false) {
     method: "POST",
     redirect: "error",
     signal: AbortSignal.timeout(15e3),
-    headers: { "Content-Type": form ? "application/x-www-form-urlencoded" : "application/json" },
+    headers: { "Content-Type": form ? "application/x-www-form-urlencoded" : "application/json", "X-Rill-CLI-Version": CLI_VERSION },
     body: form ? new URLSearchParams(Object.entries(body).map(([key2, value2]) => [key2, String(value2)])) : JSON.stringify(body)
   });
   const value = await response.json();
@@ -246,6 +251,12 @@ async function connectAgent(apiUrl, email3, options = {}) {
 async function beginConnection(apiUrl, email3) {
   if (process.env.RILL_TOKEN) throw new Error("Unset RILL_TOKEN before connecting a local identity.");
   let saved = parseAuthorization(await loadStoredCredential(apiUrl));
+  if (saved?.connection?.status === "pending" && saved.connection.expiresAt <= Date.now()) {
+    if (saved.connection.email !== email3) throw new Error("Use the original account to finish or recover this connection.");
+    const result = await pollSavedConnection(apiUrl, saved.connection.id);
+    if (result.status !== "expired") return result;
+    saved = parseAuthorization(await loadStoredCredential(apiUrl));
+  }
   if (saved?.connection?.status === "pending" && saved.connection.expiresAt > Date.now()) {
     if (saved.connection.email !== email3) throw new Error("A connection for another email is pending. Let it expire before starting a different connection.");
     process.stderr.write(`Open ${saved.connection.verificationUri}
@@ -259,6 +270,22 @@ Sign in as ${email3} and enter ${saved.connection.userCode}. Approve only the re
       const result = await request(apiUrl, "/agent/identity/claim", { claim_token: saved.claimToken, email: email3 });
       claim = result.claim_attempt;
     } catch (error51) {
+      if (error51 instanceof AgentAuthError && error51.code === "claim_already_approved") {
+        saved.connection ??= {
+          id: randomBytes(16).toString("hex"),
+          email: email3,
+          verificationUri: "",
+          userCode: "",
+          expiresAt: Date.now(),
+          interval: 5,
+          nextPollAt: 0,
+          status: "pending"
+        };
+        saved.connection.status = "pending";
+        saved.connection.nextPollAt = 0;
+        await save(apiUrl, saved);
+        return pollSavedConnection(apiUrl, saved.connection.id);
+      }
       if (!(error51 instanceof AgentAuthError) || error51.code !== "claim_expired") throw error51;
     }
   }
@@ -309,11 +336,6 @@ async function pollSavedConnection(apiUrl, authorizationId) {
   if (!saved?.connection || saved.connection.id !== authorizationId) throw new AgentAuthError("authorization_not_found", "No matching saved connection for this API URL. Use the latest connect response.");
   const connection = saved.connection;
   if (connection.status !== "pending") return connectionView(apiUrl, saved);
-  if (Date.now() >= connection.expiresAt) {
-    connection.status = "expired";
-    await save(apiUrl, saved);
-    return connectionView(apiUrl, saved);
-  }
   if (Date.now() < connection.nextPollAt) return connectionView(apiUrl, saved);
   connection.nextPollAt = Date.now() + connection.interval * 1e3;
   await save(apiUrl, saved);
@@ -322,7 +344,7 @@ async function pollSavedConnection(apiUrl, authorizationId) {
     saved = withTokens({ version: 1, anonymous: false, connection: { ...connection, status: "authenticated", userCode: "" } }, tokens);
   } catch (error51) {
     if (!(error51 instanceof AgentAuthError)) throw error51;
-    if (error51.code === "expired_token" || error51.code === "claim_expired") connection.status = "expired";
+    if (error51.code === "expired_token" || error51.code === "claim_expired" || error51.code === "claim_delivery_expired" || error51.code === "claimed_or_in_flight" && Date.now() >= connection.expiresAt) connection.status = "expired";
     else if (error51.code === "access_denied" || error51.code === "claim_revoked") connection.status = "denied";
     else if (error51.code === "slow_down") {
       connection.interval += 5;
@@ -442,7 +464,7 @@ var ControlPlaneClient = class {
     return this.request(`/api/cloud/runs/${encodeURIComponent(id)}/cancel`, { method: "POST" });
   }
   health() {
-    return this.request("/api/health", {}, false);
+    return this.request("/api/health", { signal: AbortSignal.timeout(5e3) }, false);
   }
   agentSession() {
     return this.request("/api/agent/session", { signal: AbortSignal.timeout(5e3) });
@@ -15244,7 +15266,7 @@ async function waitForEncoding(client, id, timeoutMs = 30 * 6e4) {
 // src/cli.ts
 import { spawn as spawn8 } from "child_process";
 import { hostname as hostname4, tmpdir as tmpdir3 } from "os";
-import { Command } from "commander";
+import { Command, CommanderError } from "commander";
 import { basename, dirname as dirname2, join as join11 } from "path";
 import { readdir as readdir2, rm as rm7, stat as stat5 } from "fs/promises";
 
@@ -16647,6 +16669,72 @@ function fail(error51) {
   process.exitCode = 1;
 }
 
+// src/human-output.ts
+function terminalColor(enabled = Boolean(process.stdout.isTTY) && !("NO_COLOR" in process.env) && process.env.TERM !== "dumb") {
+  return (text, code) => enabled ? `\x1B[${code}m${text}\x1B[0m` : text;
+}
+function formatIdentity(identity, color = terminalColor()) {
+  if (identity.status === "not_connected") return `${color("! Not connected to Rill", 33)}
+
+Sign in: ${cliCommand(identity.apiUrl, "login")}
+`;
+  if (identity.status === "anonymous") return `${color("\u2713 Using Rill anonymously", 32)}
+
+Connect your account: ${cliCommand(identity.apiUrl, "connect", "--email", "<your-email>")}
+`;
+  return `${color("\u2713 Connected to Rill", 32)}
+Account: ${identity.email ?? "Email unavailable"}
+`;
+}
+function formatDoctor(result, color = terminalColor()) {
+  const labels = { node: "Node.js", api: "API connectivity", cli_version: "CLI version", authentication: "Authentication", chrome: "Browser", ffmpeg: "FFmpeg", encoding: "Encoding", recorder_transport: "Recorder transport" };
+  const symbols = { pass: "\u2713", fail: "\xD7", warn: "!", skip: "\u2013" };
+  const colors = { pass: 32, fail: 31, warn: 33, skip: 90 };
+  const lines = [color("Rill CLI Doctor", 34), `Execution environment: ${result.environment.platform}`, ""];
+  for (const check2 of result.checks) {
+    lines.push(color(`${symbols[check2.status]} ${labels[check2.name]}: ${check2.message}`, colors[check2.status]));
+    if (check2.recovery) lines.push(`  \u2192 ${check2.recovery}`);
+  }
+  const warnings = result.checks.filter((c) => c.status === "warn").length;
+  lines.push(
+    "",
+    "Browser control: not verified. Your agent must attach to the returned CDP endpoint.",
+    "",
+    `${result.checks.filter((c) => c.status === "pass").length} passed \xB7 ${result.checks.filter((c) => c.status === "fail").length} failed \xB7 ${warnings} ${warnings === 1 ? "warning" : "warnings"}`
+  );
+  return lines.join("\n") + "\n";
+}
+function formatRecording(value, apiUrl, color = terminalColor()) {
+  const artifact = value.result && typeof value.result === "object" ? value.result : {};
+  const id = String(value.recordingId ?? value.id ?? "");
+  const status = String(value.status ?? "unknown");
+  const titles = { recording: "Recording started", ready: "Recording ready", captured: "Captured locally \xB7 upload required", uploading: "Uploading recording", queued: "Recording queued for encoding", encoding: "Encoding recording", processing: "Processing recording", finalizing: "Finalizing recording", failed: "Recording failed", cancelled: "Recording cancelled", expired: "Recording expired" };
+  const lines = [color(`${["recording", "ready"].includes(status) ? "\u2713" : ["failed", "expired"].includes(status) ? "\xD7" : "\u2013"} ${titles[status] ?? `Recording status: ${status}`}`, ["failed", "expired"].includes(status) ? 31 : status === "ready" || status === "recording" ? 32 : 33)];
+  if (id) lines.push(`ID: ${id}`);
+  const duration3 = value.durationSeconds ?? value.duration_seconds ?? artifact.durationSeconds;
+  if (typeof duration3 === "number" && Number.isFinite(duration3)) lines.push(`Duration: ${Math.floor(duration3 / 60)}m ${Math.floor(duration3 % 60)}s`);
+  if (typeof value.remainingSeconds === "number") lines.push(`Time remaining: ${Math.max(0, Math.ceil(value.remainingSeconds))}s`);
+  if (typeof value.cdpUrl === "string") lines.push(`Browser connection: ${value.cdpUrl}`);
+  if (typeof value.tabId === "string") lines.push(`Recorded tab: ${value.tabId}`);
+  if (typeof value.shareUrl === "string" && value.shareUrl) lines.push("", `Share: ${value.shareUrl}`);
+  else if (status === "ready") lines.push("", "Ready. No share link returned; open this recording in your Rill account.");
+  const message = value.message ?? value.error;
+  if (typeof message === "string" && message) lines.push("", message);
+  const next = typeof value.nextCommand === "string" ? value.nextCommand : status === "recording" && id ? cliCommand(apiUrl, "record", "stop", id) : void 0;
+  if (next) lines.push("", status === "recording" ? "Perform your test, then stop and upload:" : "Next:", `  ${next}`);
+  return lines.join("\n") + "\n";
+}
+function formatFailure(error51, color = terminalColor()) {
+  const { error: failure } = failureValue(error51);
+  let message = failure.message.startsWith(`${failure.code}: `) ? failure.message.slice(failure.code.length + 2) : failure.message;
+  if (failure.recovery && message.endsWith(`: ${failure.recovery}`)) message = message.slice(0, -failure.recovery.length - 2);
+  const lines = [color(`\xD7 ${message}`, 31)];
+  if (typeof failure.details?.recordingId === "string") lines.push(`ID: ${failure.details.recordingId}`);
+  if (failure.recovery) lines.push("", `Next: ${failure.recovery}`);
+  else if (typeof failure.details?.nextCommand === "string") lines.push("", `Next: ${failure.details.nextCommand}`);
+  return lines.join("\n") + "\n";
+}
+
 // src/feedback-protocol.ts
 function suggestedFeedbackAction(recordingId) {
   return {
@@ -16705,13 +16793,6 @@ async function withRunFeedback(session, start) {
 
 // src/doctor.ts
 import { spawn as spawn7 } from "child_process";
-
-// src/version.ts
-import { createRequire } from "module";
-var packageJson = createRequire(import.meta.url)("../package.json");
-var CLI_VERSION = packageJson.version;
-
-// src/doctor.ts
 var defaultDependencies = {
   platform: process.platform,
   encoding: "remote",
@@ -16741,9 +16822,11 @@ async function runDoctor(apiUrl, overrides = {}) {
     if (!health.ok || health.service !== "rill") throw new Error("The endpoint did not identify itself as Rill.");
     checks.push({ name: "api", status: "pass", message: `Rill API is reachable at ${apiUrl}.` });
   } catch (error51) {
-    checks.push({ name: "api", status: "fail", message: `Rill API is unreachable: ${errorMessage(error51)}`, recovery: `Check the network and API URL, then rerun \`rill --api-url ${apiUrl} doctor\`.` });
+    checks.push({ name: "api", status: "fail", message: `Rill API is unreachable: ${errorMessage(error51)}`, recovery: `Check network access in this ${dependencies.platform} execution environment and the API URL, then rerun \`rill --api-url ${apiUrl} doctor\`. An agent sandbox may have different network access from your desktop.` });
   }
-  if (!health?.minimumCliVersion || !health.recommendedCliVersion) {
+  if (!health) {
+    checks.push({ name: "cli_version", status: "skip", message: `CLI ${dependencies.cliVersion} compatibility was not checked because the API is unreachable.`, version: dependencies.cliVersion });
+  } else if (!health.minimumCliVersion || !health.recommendedCliVersion) {
     checks.push({ name: "cli_version", status: "fail", message: `CLI ${dependencies.cliVersion} could not be checked against the API compatibility policy.`, version: dependencies.cliVersion, recovery: "Deploy a Rill API that advertises minimumCliVersion and recommendedCliVersion." });
   } else if (compareVersions(dependencies.cliVersion, health.minimumCliVersion) < 0) {
     checks.push({ name: "cli_version", status: "fail", message: `CLI ${dependencies.cliVersion} is older than the minimum supported version ${health.minimumCliVersion}.`, version: dependencies.cliVersion, recovery: `Run \`npm install --global @runalabs/rill-cli@${health.recommendedCliVersion}\`.` });
@@ -16778,20 +16861,23 @@ 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("chrome", dependencies.chromePath, ["--version"], dependencies.commandVersion, `Chrome must be available in this ${dependencies.platform} execution environment. Install Chrome/Chromium here or set RILL_CHROME_PATH. A browser on a separate desktop is not automatically accessible; use that desktop's terminal to record locally.`));
   if (dependencies.encoding === "local") {
     checks.push(await executableCheck("ffmpeg", dependencies.ffmpegPath, ["-version"], dependencies.commandVersion, dependencies.platform === "darwin" ? "Install ffmpeg with `brew install ffmpeg`, or set RILL_FFMPEG." : "Install ffmpeg using the system package manager, or set RILL_FFMPEG."));
   } else {
     checks.push({ name: "ffmpeg", status: "skip", message: "Remote encoding does not require local FFmpeg." });
-    try {
-      const token = await dependencies.loadCredential(apiUrl);
-      if (!(token ? (await dependencies.encodingCapabilities(apiUrl, token)).enabled : health?.anonymousAccess && health.anonymousRemoteEncoding)) throw new Error("Remote encoding is not enabled for this workspace.");
-      checks.push({ name: "encoding", status: "pass", message: token ? "Remote encoding is enabled." : "Remote encoding is available for the first anonymous recording." });
-    } catch (error51) {
-      checks.push({ name: "encoding", status: "fail", message: errorMessage(error51), recovery: "Run doctor --encoding local to check local FFmpeg, then record start --encoding local, or ask the workspace owner to enable remote encoding." });
+    if (!health) checks.push({ name: "encoding", status: "skip", message: "Remote encoding was not checked because the API is unreachable." });
+    else {
+      try {
+        const token = await dependencies.loadCredential(apiUrl);
+        if (!(token ? (await dependencies.encodingCapabilities(apiUrl, token)).enabled : health?.anonymousAccess && health.anonymousRemoteEncoding)) throw new Error("Remote encoding is not enabled for this workspace.");
+        checks.push({ name: "encoding", status: "pass", message: token ? "Remote encoding is enabled." : "Remote encoding is available for the first anonymous recording." });
+      } catch (error51) {
+        checks.push({ name: "encoding", status: "fail", message: errorMessage(error51), recovery: "Run doctor --encoding local to check local FFmpeg, then record start --encoding local, or ask the workspace owner to enable remote encoding." });
+      }
     }
   }
-  return { schemaVersion: 1, status: checks.some((check2) => check2.status === "fail") ? "error" : "ok", apiUrl, checks, ...runFeedbackFields(feedbackEnabled) };
+  return { schemaVersion: 1, status: checks.some((check2) => check2.status === "fail") ? "error" : "ok", apiUrl, environment: { platform: dependencies.platform }, checks, ...runFeedbackFields(feedbackEnabled) };
 }
 async function executableCheck(name, path, args, run2, recovery) {
   try {
@@ -16974,13 +17060,23 @@ function watchEncoding(apiUrl, id) {
   child.unref();
 }
 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).option("--json", "Output cloud run results as JSON", false);
+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).option("--json", "Output machine-readable JSON (including whoami)", false).option("--human", "Readable doctor, login, whoami and recording start/stop/status/retry output", false);
+program.configureOutput({ outputError: () => void 0 }).exitOverride();
+function humanOutput(identity = false) {
+  const options = program.opts();
+  return !options.json && !options.pretty && (identity || options.human);
+}
+function emitRecording(value, pretty) {
+  if (humanOutput()) process.stdout.write(formatRecording(value, program.opts().apiUrl));
+  else emit(value, pretty);
+}
 var activeTelemetry = null;
 program.command("daemon", { hidden: true }).action(() => runDaemon());
 program.command("doctor").description("Validate Rill prerequisites before recording.").option("--encoding <mode>", "remote or local", "remote").action(async (commandOptions) => {
   const options = program.opts();
   const result = await runDoctor(options.apiUrl, { encoding: commandOptions.encoding });
-  emit(result, options.pretty);
+  if (humanOutput()) process.stdout.write(formatDoctor(result));
+  else emit(result, options.pretty);
   if (result.status === "error") process.exitCode = 1;
 });
 async function authorize(quiet = false) {
@@ -17001,15 +17097,19 @@ async function authorize(quiet = false) {
     if (result.status === "pending") continue;
     if (result.status !== "approved" || !result.token) throw new Error(`Device authorization ${result.status}.`);
     await saveCredential(options.apiUrl, result.token);
-    if (!quiet) emit({ schemaVersion: 1, status: "authenticated", expiresAt: result.expiresAt, apiUrl: options.apiUrl }, options.pretty);
+    if (!quiet) {
+      if (humanOutput()) process.stdout.write("\u2713 Signed in to Rill\nCheck your account: rill whoami\n");
+      else emit({ schemaVersion: 1, status: "authenticated", expiresAt: result.expiresAt, apiUrl: options.apiUrl }, options.pretty);
+    }
     return result.token;
   }
   throw new Error("Device authorization expired.");
 }
-program.command("whoami").description("Show the current verified agent identity without starting sign-in.").action(async () => {
+program.command("whoami").description("Show the current verified identity without starting sign-in.").addHelpText("after", "\nShows a short account summary by default. Use rill whoami --json for agents, or rill --pretty whoami for indented JSON.").action(async () => {
   const options = program.opts();
   const identity = await whoami(options.apiUrl);
-  emit(identity, options.pretty);
+  if (humanOutput(true)) process.stdout.write(formatIdentity(identity));
+  else emit(identity, options.pretty);
   if (!identity.authenticated) process.exitCode = 1;
 });
 var connect = program.command("connect").description("Connect this agent once, with renewable account access.").option("--email <email>", "Email of the Rill account approving access").option("--no-wait", "Return approval instructions immediately; poll with connect status").action(async (input) => {
@@ -17101,7 +17201,7 @@ record2.command("start").option("--encoding <mode>", "remote or local", "remote"
     }).catch(() => void 0);
     return { schemaVersion: 1, recordingId: remote.recordingId, status: local.status, cdpUrl: local.cdpUrl, ...local.tabId ? { tabId: local.tabId } : {}, browserAttachment: browserAttachment(local.cdpUrl, local.tabId), startedAt: local.startedAt, stopsAt: local.stopsAt, elapsedSeconds: local.elapsedSeconds, remainingSeconds: local.remainingSeconds, bodyCaptureEnabled: remote.bodyCaptureEnabled, anonymous: remote.anonymous ?? false, expiresAt: remote.expiresAt ?? null, maxDurationSeconds: Math.min(Number(commandOptions.maxDuration), remote.maxDurationSeconds ?? 600) };
   });
-  emit(result, options.pretty);
+  emitRecording(result, options.pretty);
 });
 record2.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();
@@ -17123,7 +17223,7 @@ record2.command("stop").argument("<recording-id>").option("--no-wait").option("-
     await client.uploadDiagnostics(recordingId, local.result.diagnosticsPath, local.result.diagnostics);
     const accepted = await submitFrameCapture(client, recordingId, local.result.frameDirectory);
     const result2 = commandOptions.wait && record2.opts().wait !== false ? await waitForEncoding(client, recordingId) : accepted;
-    emit({ schemaVersion: 1, ...result2, ...recordingNextStep(options.apiUrl, recordingId, result2.status, { resumableFrames: true }), ...recordingFeedbackFields(recordingId, stopped?.feedbackRequested ?? false) }, options.pretty);
+    emitRecording({ schemaVersion: 1, ...result2, recordingId, ...recordingNextStep(options.apiUrl, recordingId, result2.status, { resumableFrames: true }), ...recordingFeedbackFields(recordingId, stopped?.feedbackRequested ?? false) }, options.pretty);
     if (result2.status === "ready") await rm7(dirname2(local.result.videoPath), { recursive: true, force: true });
     else watchEncoding(options.apiUrl, recordingId);
     return;
@@ -17145,7 +17245,7 @@ record2.command("stop").argument("<recording-id>").option("--no-wait").option("-
     ...recordingNextStep(options.apiUrl, recordingId, remote ? "ready" : "processing"),
     ...recordingFeedbackFields(recordingId, stopped?.feedbackRequested ?? false)
   };
-  emit(result, options.pretty);
+  emitRecording(result, options.pretty);
   if (remote) await rm7(dirname2(local.result.videoPath), { recursive: true, force: true });
 });
 record2.command("retry").argument("<recording-id>").option("--no-wait").action(async (recordingId, commandOptions) => {
@@ -17166,7 +17266,7 @@ record2.command("retry").argument("<recording-id>").option("--no-wait").action(a
   if (!accepted) throw new Error("Encoding job is unavailable.");
   if (["expired", "cancelled"].includes(accepted.status)) throw new Error(`Recording ${accepted.status}.`);
   const result = commandOptions.wait && record2.opts().wait !== false ? await waitForEncoding(client, recordingId) : accepted;
-  emit({ schemaVersion: 1, ...result, ...recordingNextStep(options.apiUrl, recordingId, result.status, { resumableFrames: true }) }, options.pretty);
+  emitRecording({ schemaVersion: 1, ...result, recordingId, ...recordingNextStep(options.apiUrl, recordingId, result.status, { resumableFrames: true }) }, options.pretty);
   if (result.status === "ready") await removeLocalCapture(recordingId);
   else watchEncoding(options.apiUrl, recordingId);
 });
@@ -17208,7 +17308,7 @@ record2.command("status").argument("<recording-id>").action(async (recordingId)
   try {
     const encoding = await client.encodingStatus(recordingId);
     const remote = encoding.status === "ready" ? await client.recordingStatus(recordingId) : {};
-    emit({ schemaVersion: 1, ...encoding, ...remote, recordingId, source: "remote", ...recordingNextStep(options.apiUrl, recordingId, encoding.status, { resumableFrames: true }) }, options.pretty);
+    emitRecording({ schemaVersion: 1, ...encoding, ...remote, recordingId, source: "remote", ...recordingNextStep(options.apiUrl, recordingId, encoding.status, { resumableFrames: true }) }, options.pretty);
     if (encoding.status === "ready") await removeLocalCapture(recordingId);
     return;
   } catch (error51) {
@@ -17221,7 +17321,7 @@ record2.command("status").argument("<recording-id>").action(async (recordingId)
     },
     remoteStatus: (id) => client.recordingStatus(id)
   }, options.apiUrl);
-  emit({ schemaVersion: 1, ...status }, options.pretty);
+  emitRecording({ schemaVersion: 1, ...status, recordingId }, options.pretty);
 });
 record2.command("cancel").argument("<recording-id>").description("Cancel an active recording and release its remote quota slot.").action(async (recordingId) => {
   const options = program.opts();
@@ -17301,8 +17401,20 @@ program.hook("postAction", async () => {
   await finishCliTelemetry(process.exitCode ? new Error("command_reported_failure: Command returned a failure status.") : null);
 });
 program.parseAsync().catch(async (error51) => {
+  if (error51 instanceof CommanderError && error51.exitCode === 0) return;
+  if (error51 instanceof CommanderError) {
+    const action = program.args[0] === "record" ? program.args[1] : void 0;
+    const missingRecording = error51.code === "commander.missingArgument" && ["stop", "status", "retry", "cancel"].includes(action ?? "");
+    error51 = Object.assign(new Error(`validation_failed: ${missingRecording ? "A recording ID is required." : error51.message.replace(/^error: /, "")}`), {
+      code: "validation_failed",
+      recovery: missingRecording ? `Run rill record ${action} <recording-id>. Use rill record list to find the ID.` : "Run rill --help for available commands and options."
+    });
+  }
   await finishCliTelemetry(error51);
-  fail(error51);
+  if (humanOutput(program.args[0] === "whoami")) {
+    process.stderr.write(formatFailure(error51));
+    process.exitCode = 1;
+  } else fail(error51);
 });
 function commandPath(actionCommand) {
   const path = [];

package/package.json

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