@runalabs/rill-cli 0.1.9 → 0.1.11

package/README.md

@@ -25,14 +25,7 @@ The following local-recording instructions remain available through `record star
 
 ## Install and verify
 
-Browser recording runs on macOS and Linux. Install Node.js 22+, Google Chrome or Chromium, and ffmpeg on `PATH`.
-
-```sh
-# macOS
-brew install ffmpeg
-# Debian / Ubuntu
-sudo apt install ffmpeg
-```
+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.
 
 Then install the scoped package:
 
@@ -43,7 +36,7 @@ rill login
 rill doctor
 ```
 
-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.
+Do not use `npx rill`: the unscoped package belongs to a different product. Doctor checks Node, API reachability, CLI compatibility, authentication, Chrome, and remote encoding availability. Resolve failed checks before starting a run.
 
 ## Authenticate
 
@@ -67,7 +60,7 @@ 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.
+Start returns `recordingId`, `cdpUrl`, `status`, `bodyCaptureEnabled`, and `maxDurationSeconds`. Stop finalizes capture, uploads frames and diagnostics for remote encoding, 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.
 
 New browser recordings include a visible cursor and click pulses by default. In Rill Settings → Cursor appearance, workspace members can turn them off or choose an accent color. The CLI reads this preference when starting a recording; it is baked into the video and does not change existing recordings. Use an updated CLI and recorder daemon to capture the overlay.
 
@@ -100,6 +93,7 @@ Capture follows the first page selected at recording start. Keep the flow in tha
 | Option | Behavior |
 | --- | --- |
 | `--url <url>` | Open the target in a managed browser. |
+| `--encoding remote` / `--encoding local` | Remote is the default; local requires FFmpeg. |
 | `--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. |
@@ -142,7 +136,7 @@ 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.
+Both `upload` and `record stop` accept `--no-wait`. This waits for upload acceptance, then returns while processing continues. Remote recordings may report `queued` or `encoding` before `processing` and `ready`. Use `rill record status <recording-id>` to retrieve progress and the eventual share link.
 
 ## Command reference
 
@@ -154,7 +148,8 @@ Use `rill --help` or `<command> --help` for supported flags.
 | `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 status <recording-id>` | Read the remote encoding job first; otherwise check local capture state with a remote fallback. |
+| `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`. |
 | `rill inspect <share-url>` | Read bounded context without login. |
@@ -191,14 +186,15 @@ Check the exit status first, then structured fields. Known codes include `authen
 
 - **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.
+- **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.
-- **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.
+- **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.
 - **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.
+For `--encoding local`, 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.
 
@@ -209,7 +205,7 @@ When finalized artifacts survive, retain `recording.webm` and `diagnostics-v1.nd
 | `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_FFMPEG` | FFmpeg executable for `--encoding local`; 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. |
@@ -269,3 +265,26 @@ Substitute your API URL if you configured another environment. These commands cl
 Use `--json` for a machine-readable result (`--pretty` also enables JSON formatting).
 Provider token usage is retained internally and omitted from customer output.
 `rill run status <run-id>` and `rill run cancel <run-id>` support the same output options.
+
+## Remote encoding
+
+Since 0.1.10, `record start` uses remote encoding by default. Chrome stays local, including access to localhost; FFmpeg is required only for `record start --encoding local`. For local encoding, install FFmpeg with `brew install ffmpeg` on macOS or `sudo apt install ffmpeg` on Debian/Ubuntu, then run `doctor --encoding local`. Remote encoding adds no charge and consumes no cloud-run credits; existing recording allowances still apply. Captures are limited to ten minutes and 1 GiB of raw frames, with three pending jobs per workspace. Busy recordings can reach the byte limit sooner.
+
+`record stop` uploads frames and waits for playback. `record stop ID --no-wait` returns after upload acceptance; processing continues if the terminal closes. Use `record status ID` to retrieve progress and the share link, or `record retry ID` to resume an interrupted upload or retry encoding without repeating browser actions. Raw captures are removed after successful publication. Recoverable captures expire after 24 hours: local retention starts at capture start, server retention at upload initialization. Keep the original credential and local files until upload acceptance; `expiresAt` reports the server deadline once a job exists.
+
+```sh
+rill record stop <recording-id> --no-wait
+rill record status <recording-id>
+# If upload or encoding failed, retry the same recording:
+rill record retry <recording-id>
+```
+
+Progress runs through `uploading` → `queued` → `encoding` → `processing` → `ready`. Waiting for capacity is normal; do not repeat the browser journey merely because a job is queued. Long or busy recordings can take several minutes to upload and encode.
+
+### Anonymous local recordings and account connection
+
+`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.
+
+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.