@runalabs/rill-cli 0.1.10 → 0.1.12

package/README.md

@@ -148,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. |
@@ -185,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.
 
@@ -203,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. |
@@ -264,8 +266,29 @@ Use `--json` for a machine-readable result (`--pretty` also enables JSON formatt
 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
+## 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. Failed raw captures expire after 24 hours. Remote encoding uses no cloud-run credits and adds no charge.
+`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.
+
+### 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.