@runalabs/rill-cli 0.1.11 → 0.1.13

package/README.md

@@ -40,6 +40,17 @@ 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.
@@ -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:** 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.
 - **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.
@@ -288,3 +333,7 @@ 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 Rill's Credentials page 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.
+
+### 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.