@runalabs/rill-cli 0.1.12 → 0.1.14

package/README.md

@@ -19,13 +19,13 @@ rill run cancel <run-id>
 
 The first run opens Rill authorization if needed. Save optional website test accounts in Rill Settings using an account name, exact HTTPS origin, username, password, and optional login URL. Login appears in the private video, with masked password inputs; login diagnostics are omitted. MFA, CAPTCHA, external SSO, and unsupported login forms return a blocker.
 
-Cloud recordings are private by default. Closing the terminal disconnects without cancelling. Use `--no-wait` to return after submission, and `--id <same-run-id>` with identical arguments to retry an uncertain submission. Cloud runs use run credits: Free includes 3 per calendar month and Pro includes 20. Buy additional credits from Billing.
+Cloud recordings are private by default. Closing the terminal disconnects without cancelling. Use `--no-wait` to return after submission, and `--id <same-run-id>` with identical arguments to retry an uncertain submission. Cloud runs use run credits: Check your current monthly allowance and balance in Billing; allowances depend on the account entitlement and service configuration. Buy additional credits there.
 
 The following local-recording instructions remain available through `record start` and `record stop`.
 
 ## Install and verify
 
-Browser recording runs on macOS and Linux. 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.
+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:
 
@@ -40,9 +40,20 @@ Do not use `npx rill`: the unscoped package belongs to a different product. Doct
 
 ## Authenticate
 
+### 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:
+
+```sh
+rill connect --email you@example.com --no-wait
+rill connect status <authorization-id>
+```
+
+The first response contains `authorizationId`, `verificationUri`, `userCode`, `expiresAt`, `retryAfterSeconds`, and the exact `nextCommand`. The human opens the URL and approves their own request. Poll no faster than `retryAfterSeconds`; each status command returns once. States are `pending`, `authenticated` (approved and credentials saved), `expired`, or `denied` (including revoked claims). Expired and denied status commands exit 1. Pending state and polling backoff survive process exit in the OS credential store; claim/access tokens are never returned. Repeating connect with the same email resumes an unexpired pending request. Only the latest authorization ID for that API URL can be polled.
+
 ### 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.
+`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, Linux Secret Service, or Windows current-user DPAPI using `secret-tool`. Linux needs an available Secret Service keyring; use token authentication on headless machines without one.
 
 ### CI and unattended agents
 
@@ -66,6 +77,8 @@ New browser recordings include a visible cursor and click pulses by default. In
 
 ### Connect Playwright
 
+Start also returns `browserAttachment` with the CDP endpoint, protocol, Playwright method, and attachment instructions. Browser tools must explicitly support attaching to that endpoint; Rill does not automatically expose its browser to every tool.
+
 In a project with `playwright-core` installed, save this as `rill-run.mjs`:
 
 ```js
@@ -86,6 +99,31 @@ try {
 
 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.
 
+For a shell-only macOS/Linux agent with no project Playwright dependency, use a temporary directory. This installs the automation client without changing the project's manifest or launching another browser:
+
+```sh
+rill_automation_dir=$(mktemp -d)
+npm install --prefix "$rill_automation_dir" --no-save --package-lock=false playwright-core
+cat > "$rill_automation_dir/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 the agreed interactions and assertions on this page.
+  console.log(await page.title());
+} finally {
+  await browser.close(); // Disconnect this CDP client; preserve the recorded browser.
+}
+JS
+node "$rill_automation_dir/run.mjs" "<cdpUrl>"
+rill record stop <recording-id> --no-wait
+rill record status <recording-id>
+```
+
+Replace the placeholders with start's actual values. This snippet verifies attachment only until you add your flow assertions. Keep the directory for retries and remove it when finished. Playwright documents the [connected-browser disconnect behavior](https://playwright.dev/docs/api/class-browser#browser-close).
+
 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
@@ -145,10 +183,13 @@ Use `rill --help` or `<command> --help` for supported flags.
 | Command | Behavior |
 | --- | --- |
 | `rill login` | Authorize a device code and store a credential. |
+| `rill whoami` | Verify the saved identity and account email. |
+| `rill connect --email <email> [--no-wait]` | Start or resume account approval. |
+| `rill connect status <authorization-id>` | Poll a saved approval once; obey `retryAfterSeconds`. |
 | `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 the remote encoding job first; otherwise check local capture state with a remote fallback. |
+| `rill record status <recording-id>` | Read remote state first, then local capture for unsubmitted recordings; local completion is `captured`. |
 | `rill record retry <recording-id>` | Resume a retained remote capture or retry a failed encode; supports `--no-wait`. |
 | `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`. |
@@ -182,14 +223,18 @@ Success exits 0; command failures exit 1. Runtime failures emit an `error` objec
 
 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.
 
+Lifecycle recovery also distinguishes `unsupported_platform`, `processing_pending`, `authorization_not_found`, `expired_token`, and `access_denied`. An elapsed playback wait is pending, while a confirmed remote failure remains `processing_failed`.
+
 ## 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.
+- **Quota exceeded:** inspect `error.details.quota.type` and `blockingRecordingId` when present. Uploading and processing recordings still hold the concurrency slot. Run the returned status command and wait for `ready`; if it reports `captured`, run its stop command to upload. Cancel only an abandoned run. Review storage and daily allowance in Billing.
 - **Remote upload interrupted or encoding failed:** keep the recording ID and local capture files. Run `rill record status <recording-id>`, then `rill record retry <recording-id>` with the original credential before capture expiry. Retry resumes accepted chunks or requeues the encode without repeating browser actions. A `ready` result needs a share URL before you return it as evidence.
-- **Duration limit reached:** local capture finalizes automatically, but `record stop` is still needed to upload.
+- **Duration limit reached:** local capture finalizes automatically. Status reports `captured`, `source: "local"`, and the exact `nextCommand` to upload. It is not a playable share. Run `record stop <recording-id> --no-wait`, then poll status.
+- **Upload reached 100%:** transfer has finished; encoding/playback processing may continue. `--no-wait` returns after submission with a status command. A polling timeout reports `processing_pending`, not a confirmed processing failure.
+- **Windows:** Chrome discovery, current-user DPAPI credential storage, and authenticated named-pipe recording are available in CLI 0.1.14. Use remote encoding by default; local encoding requires FFmpeg on PATH. Unset `RILL_SOCKET`; use `RILL_HOME` to isolate recorder identity and credentials. Returned commands use Windows PowerShell quoting.
 - **Terminal closed:** after upload acceptance, the server finishes independently; retrieve the result with `record status`. Before acceptance, retry from the original machine while its captured frames remain available.
-- **Local session missing:** `record status` checks for a remote encoding job before falling back to local or remote recording state. `drafts list` locates local directories, which may be incomplete. There is no `drafts resume` command.
+- **Local session missing:** `record status` checks remote encoding and recording state. Remote processing/completion takes precedence over retained local artifacts. For captures not submitted, it checks the local recorder. Remote authorization/network errors are surfaced rather than being masked by local readiness. `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.
@@ -214,7 +259,7 @@ Set recorder variables before starting the background recorder; an existing reco
 
 ## 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.
+Anonymous and connected-local CLI recordings receive an unlisted link when ready. Anonymous recordings and their links expire seven days after creation; connected-local share links normally expire after seven days. Connecting an account does not make these links private. Signed-in cloud runs and saved screen recordings start private to the workspace; create a share link separately. Guest cloud results are available in the originating browser and through a secure emailed link for seven days. Existing private recordings retain their visibility. In the recording page, create or copy a share link, 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.
 
@@ -285,10 +330,16 @@ Progress runs through `uploading` → `queued` → `encoding` → `processing`
 
 `rill record start` can begin without sign-in when the server supports anonymous access. The CLI stores the identity in the OS credential store and uses local encoding. Anonymous access includes three successful recordings, at most five minutes and 250 MB each; each recording and its unlisted share link expires seven days after creation. Failed uploads do not consume the successful-recording allowance. Source and service rate limits also apply.
 
-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 Rill's Credentials page to stop access and renewal. Deletion and changes to existing sharing settings are not included.
+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.
 
-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 or Linux Secret Service.
+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.
+
+### Capture time and upload progress (0.1.14)
+
+`record start` and active local `record status` return `startedAt`, `stopsAt`, `maxDurationSeconds`, `elapsedSeconds`, and `remainingSeconds`. Use the remaining time to budget retries. After automatic capture stop, status reports `captured` with the stop/upload command; zero remaining time does not mean playback is ready. Fields may be absent for recovered drafts or an older daemon.
+
+Remote frame uploads write accepted/total MiB, transfer speed and an approximate remaining transfer time to stderr. Estimates use this attempt's observed transfers, including retry delays, and exclude previously uploaded bytes. They do not estimate queue or encoding time. JSON stdout stays machine readable. Failed local captures offer an explicit cancellation command for their remote slot; local drafts are retained.