@runalabs/rill-cli 0.1.13 → 0.1.15

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:
 
@@ -53,7 +53,7 @@ The first response contains `authorizationId`, `verificationUri`, `userCode`, `e
 
 ### 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
 
@@ -124,7 +124,7 @@ 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.
+Capture follows the 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
 
@@ -135,12 +135,32 @@ Capture follows the first page selected at recording start. Keep the flow in tha
 | `--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. |
+| `--cdp-url <url>` | Attach to an existing Chromium CDP endpoint. Select a tab when several are open. |
+| `--tab-id <id>` | Record the stable target ID returned by `record tabs`; requires `--cdp-url`. |
 | `--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.
 
+### Record a tab you already use
+
+Your Chromium browser must already expose a CDP endpoint; Rill cannot attach to an ordinary unexposed tab. Keep the endpoint local or otherwise access-controlled. This does not launch a second browser, switch tabs automatically or provide Safari/Firefox support.
+
+```bash
+rill record tabs --cdp-url http://127.0.0.1:9222
+rill record start --cdp-url http://127.0.0.1:9222 --tab-id <tab-id> --title "Checkout review"
+# Continue your flow in that exact tab, then finalize/upload:
+rill record stop <recording-id>
+```
+
+Discovery requires no Rill sign-in and returns `tabId`, title and a sanitized URL. Query values, credentials and fragments are removed; embedded data/file URLs are omitted. Tab titles can still contain private content. Start returns the selected `tabId` at the top level and in `browserAttachment`. If only one page is open, `--tab-id` is optional. Several pages without a selection, or a closed/missing ID, fail instead of recording a different page. A tab ID remains tied to that tab across navigation; relist after closing it.
+
+Keep automation on the selected target. For Playwright, inspect each page with `context.newCDPSession(page)`, call `Target.getTargetInfo`, match `targetInfo.targetId` to the returned `tabId`, and detach that inspection session. Do not assume `context.pages()[0]` is the recorded tab. `--url` deliberately navigates the selected tab when supplied; omit it to record the page as it is. Capture stays on this tab; popups and other tabs are not fully covered.
+
+An older running recorder service cannot honor tab selection. Start detects this and fails before sending capture instructions. Finish active recordings first; the service exits after five idle minutes when it has no retained recoverable captures. For an immediate manual restart, inspect the local `/health` response over the configured Rill socket, verify its recorder PID, and terminate only that idle recorder process. Restarting it interrupts active captures; this release does not restart it automatically.
+
+The CDP connection and disconnect behavior follow the [Playwright browser API](https://playwright.dev/docs/api/class-browser#browser-close).
+
 ## 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):
@@ -187,6 +207,7 @@ Use `rill --help` or `<command> --help` for supported flags.
 | `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 tabs --cdp-url <url>` | List existing Chromium tabs without starting a recording. |
 | `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 remote state first, then local capture for unsubmitted recordings; local completion is `captured`. |
@@ -232,7 +253,7 @@ Lifecycle recovery also distinguishes `unsupported_platform`, `processing_pendin
 - **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. 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:** doctor reports `recorder_transport` failure, and local record start rejects before reserving a recording. Use macOS/Linux for browser recording. Windows can use `RILL_TOKEN` with video-only `upload`; setting `RILL_SOCKET` does not add named-pipe/TCP support.
+- **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 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.
@@ -259,7 +280,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.
 
@@ -330,10 +351,22 @@ 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.
+
+### Failed local capture recovery
+
+If the local recorder reports a terminal failure without a finalized artifact, `rill record stop <id>` attempts to release its unused server reservation and preserves the capture error. The JSON error uses `local_capture_failed` with `details.reservationReleased`; a failed cleanup includes the status command for the selected API origin.
+
+When `record start` is blocked by a recording concurrency slot, it checks the reported blocking recording in the local daemon. A confirmed failed capture with no artifact can release its own unused reservation, then retry creation once with the same request ID. Missing/active local state, retained artifacts, other credentials, Stream uploads, encoding jobs and quota-counted reservations are preserved. Older servers or unavailable networks leave the original quota error and manual recovery guidance intact. Daily upload/storage limits still apply. This change does not resume a failed capture, import missing diagnostics, or add Windows recording support.