tars-renderer 0.0.0-stage → 1.1.0

package/README.md

@@ -1,3 +1,179 @@
-# Temporary Holding Version
+# tars-renderer
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Render Remotion videos in the cloud from your terminal, or let your AI coding agent do it.**
+
+`tars-renderer` is the command-line client for **Tars Renderer**, the Tars team's Remotion render farm. Upload a built Remotion project, pick a composition, render it on AWS Lambda (hundreds of workers in parallel) and download the MP4, all without AWS keys. Everything you do here also shows up live in the web portal, and the other way round.
+
+- **One command, every OS.** No dependencies; needs Node.js 18 or newer.
+- **Sign in through your browser.** No passwords or keys in the terminal. The token goes into your OS keychain.
+- **Fast transfers.** Only changed files are uploaded, hashes are cached, big files go up in parallel parts, and downloads use 8 parallel connections.
+- **Safe by default.** It shows the cost before every render and asks first. A monthly team budget and per-person limits apply.
+- **Agent-ready.** `--json` output, clear exit codes and a built-in guide for Claude Code, Codex and Cursor.
+
+> **Portal: [tars-renderer.vercel.app](https://tars-renderer.vercel.app).** Access is invite-only. You need a Tars Renderer account (your work email on the allowlist).
+
+---
+
+## Install
+
+```sh
+npm i -g tars-renderer
+tars-renderer --version
+```
+
+Update any time with `npm i -g tars-renderer@latest`.
+
+<details>
+<summary>"tars-renderer" is not recognized / command not found</summary>
+
+- Close and reopen the terminal, so it picks up the new command.
+- Still missing? npm's global folder isn't on your `PATH`. Run `npm prefix -g`; the command lives in that folder (Windows) or its `bin` folder (macOS/Linux). Add it to `PATH`.
+- If npm is blocked on your network, install the copy your portal serves: `npm i -g https://<portal>/cli/tars-renderer.tgz`.
+</details>
+
+## Sign in
+
+```sh
+tars-renderer login
+```
+
+No address needed: the CLI signs in to [tars-renderer.vercel.app](https://tars-renderer.vercel.app).
+
+1. The CLI shows a code such as `KQ7M-4TZP` and opens the portal in your browser.
+2. Sign in if asked, **check that the code matches**, and click **Approve**.
+3. Back in the terminal you're signed in. Check with `tars-renderer doctor`.
+
+Your sign-in lasts 90 days. If an admin removes your access, the CLI stops working immediately.
+
+### Sign out
+
+```sh
+tars-renderer logout            # sign out this device: revoked on the server, removed from your keychain
+tars-renderer logout --all      # sign out every device and agent on your account (lost laptop?)
+tars-renderer logout --purge    # also delete ~/.tars-renderer (settings and upload cache)
+tars-renderer logout --local    # offline: forget the sign-in here only
+```
+
+You can also see your devices, and sign out one or all of them, on the portal's **CLI & Agents** page.
+
+## Quick start
+
+```sh
+# 1. Build your Remotion project (same Remotion version as the renderer, currently 4.0.535)
+npx remotion bundle src/index.ts --out-dir build
+
+# 2. Create a project (once) and upload the build. Only changed files are sent.
+tars-renderer create "Q4 launch film"
+tars-renderer upload build --project q4-launch-film-x7k2
+
+# 3. See the compositions, then render one: it shows the cost and asks first
+tars-renderer comps q4-launch-film-x7k2
+tars-renderer render q4-launch-film-x7k2 Main --res 1080p --watch --download
+```
+
+```
+Main in q4-launch-film-x7k2
+  Output     1920×1080 · 9,360 frames
+  Estimate   $0.94
+  Budget     $12.30 of $50.00 spent this month · 0 active renders of yours
+Start this render for $0.94? [y/N] y
+✔ Render started: k97abc123def456
+▮▮▮▮▮▮▮▮▮▮▮▮▯▯▯▯▯▯▯▯▯▯▯▯  52%  4,867 frames  ~$0.49  1m 12s  rendering
+```
+
+Testing something new? Start small: `--res 360p --seconds 0-10` costs cents.
+
+## Use it with an AI coding agent
+
+Open Claude Code, Codex or Cursor in your Remotion project folder and ask it to render. The agent can run everything itself, and it always shows you the cost and waits for your yes before rendering. Give it the full instructions with:
+
+```sh
+tars-renderer agent-guide
+```
+
+or click **Copy agent instructions** on the portal and paste them into the agent. The agent never needs keys: you approve its sign-in in your own browser, and the CLI only ever shows a masked token (`trp_ab12…`).
+
+## Commands
+
+Every command accepts `--help` and `--json`. `<project>` takes a project slug or id.
+
+| Command | What it does |
+|---|---|
+| `login` | Sign in through the browser (to tars-renderer.vercel.app) |
+| `logout [--all] [--local] [--purge]` | Sign out this device; `--all` signs out every device on your account |
+| `whoami` | Who you're signed in as |
+| `doctor` | Check Node, sign-in, the API connection and your access |
+| `projects [--mine]` | List projects |
+| `create <name> [--keep 7-days\|30-days\|90-days\|never]` | Create a project |
+| `upload <buildDir> --project <project> [--yes]` | Upload a build; only changed files are sent |
+| `comps <project>` | List compositions (size, fps, duration, frames) |
+| `estimate <project> <composition> [render options]` | Cost, output size and frames, without rendering |
+| `render <project> <composition> [render options] [--watch] [--download [path]] [--yes]` | Start a render |
+| `renders [--mine] [--project <p>] [--status <s>]` | List renders |
+| `status <renderId>` | A render's current state |
+| `watch <renderId>` | Follow a render live (exit 0 when done, 1 if it fails) |
+| `download <renderId> [--out <path>]` | Download a finished render |
+| `link <renderId>` | A share link, valid 24 hours |
+| `delete-render <renderId>` / `delete-project <project>` | Delete (asks first) |
+| `agent-guide` | Instructions for AI coding agents |
+
+### Render options
+
+Also accepted by `estimate`.
+
+| Option | Values | Default |
+|---|---|---|
+| `--res` | `360p`, `720p`, `1080p`, `4k` | `1080p` |
+| `--quality` | `draft`, `standard`, `high` | `standard` |
+| `--seconds a-b` | a time range, e.g. `0-10` | whole video |
+| `--frames a-b` | a frame range, inclusive, e.g. `0-299` | whole video |
+| `--muted` | no audio | off |
+| `--keep` | `1-day`, `3-days`, `7-days`, `30-days`, `forever` | `7-days` |
+
+Renders above **$5** always ask for an extra confirmation. Each person can have **2 renders running** at once, and the team has a **monthly budget**.
+
+## How uploads work
+
+- Pass the **build folder** (`index.html` and `bundle.js` at its top). If you pass the project root by mistake, the CLI tells you which folder to use.
+- The Remotion version is read from `bundle.js` and must match the renderer's (use `--version` to override detection).
+- Files are hashed (SHA-256) and only new or changed files are sent. Hashes are cached, so re-uploading an unchanged build takes seconds (`--rehash` ignores the cache).
+- Big files go up in 16 MB parts. Everything shares one parallel queue with retries, and expired upload links are renewed automatically.
+- Builds can have up to 8,000 files, 5 GB per file and 20 GB in total.
+- If an upload fails, run the same command again: anything already uploaded is skipped.
+
+## JSON mode (scripts and agents)
+
+With `--json`, a command prints **exactly one JSON document on stdout**. Progress and logs go to stderr, and errors are JSON too: `{ "ok": false, "error": "…", "exitCode": 1 }`.
+
+| Exit code | Meaning |
+|---|---|
+| `0` | Success |
+| `1` | Error (see `error`) |
+| `2` | Bad usage |
+| `3` | Confirmation needed. Show the user the details, then re-run with `--yes` |
+| `4` | Not signed in, or the sign-in expired. Run `tars-renderer login` |
+| `130` | Cancelled with Ctrl-C |
+
+Without `--yes`, any step that would ask (upload, render, delete) stops with exit code 3 and prints what it would do, including the cost estimate.
+
+## Security
+
+- Sign-in is a one-time code you approve in your browser, and only allowlisted accounts can approve it.
+- The token is stored in the **macOS Keychain**, **Windows DPAPI** or the **Linux Secret Service**. It's kept in `~/.tars-renderer/config.json` (owner-only) only if none of those is available. `tars-renderer doctor` shows where it is.
+- The CLI masks tokens in all output, only talks to `https://` servers (or localhost for development), and never handles AWS credentials.
+- For CI, set `TARS_RENDERER_API` and `TARS_RENDERER_TOKEN` as environment variables instead of signing in.
+
+## Troubleshooting
+
+| Problem | Fix |
+|---|---|
+| `Not signed in` / exit code 4 | `tars-renderer login` |
+| `This build uses Remotion X` | Pin `remotion` and every `@remotion/*` package to the renderer's version, rebuild, upload again |
+| `index.html and bundle.js not found` | Pass the `build` folder, not the project root |
+| `A render of this project is running` | Wait for it to finish, then re-upload |
+| `access denied` when approving | Ask an admin to add your work email |
+| Anything else | `tars-renderer doctor`, then `DEBUG=1 tars-renderer <command>` for details |
+
+---
+
+**Tars Renderer:** [tars-renderer.vercel.app](https://tars-renderer.vercel.app) (invite-only). Requires Node.js 18+.

package/package.json

@@ -1,6 +1,31 @@
 {
   "name": "tars-renderer",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.0",
+  "description": "Command line for the Tars Renderer: upload Remotion builds, render on AWS Lambda, download the MP4.",
+  "homepage": "https://tars-renderer.vercel.app",
+  "type": "module",
+  "bin": {
+    "tars-renderer": "tars-renderer.mjs"
+  },
+  "files": [
+    "tars-renderer.mjs",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "remotion",
+    "render",
+    "lambda",
+    "cli",
+    "tars",
+    "remotion-lambda",
+    "video",
+    "ai-agent"
+  ],
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  }
+}