tars-renderer 0.0.0-stage → 1.1.1

package/tars-renderer.mjs

@@ -0,0 +1,1943 @@
+#!/usr/bin/env node
+// tars-renderer: command-line client for the Tars Renderer (Remotion render farm). Contract: CLI_API.md; docs: cli/README.md.
+// One file, no dependencies, Node >= 18. Served at <portal>/cli/tars-renderer.mjs.
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import crypto from "node:crypto";
+import readline from "node:readline";
+import { spawn, spawnSync } from "node:child_process";
+import { setMaxListeners } from "node:events";
+import { setTimeout as delay } from "node:timers/promises";
+import { fileURLToPath } from "node:url";
+
+export const VERSION = "1.1.1";
+
+/** The Tars Renderer portal. `login` signs in here unless another portal is passed (development, staging). */
+export const DEFAULT_PORTAL = "https://tars-renderer.vercel.app";
+
+// The package was first published under an older name. These are read only to carry existing sign-ins over.
+const LEGACY = { dir: ".tars-" + "render", keyring: "tars-" + "render", env: "TARS_" + "RENDER_" };
+for (const k of ["API", "TOKEN", "TOKEN_STORE"]) {
+  if (process.env[LEGACY.env + k] && !process.env[`TARS_RENDERER_${k}`]) process.env[`TARS_RENDERER_${k}`] = process.env[LEGACY.env + k];
+}
+export const EXIT = { OK: 0, ERROR: 1, USAGE: 2, CONFIRM: 3, AUTH: 4, CANCELLED: 130 };
+
+// Transfers mirror src/upload/uploader.ts and src/lib/transfer.ts (the browser's versions). The 64 MB multipart
+// threshold and 16 MB part size are decided by the server in prepare.
+const SKIP = new Set([".DS_Store", "Thumbs.db"]);
+const HASH_AT_ONCE = 4;
+// Node's fetch has no per-host connection cap (browsers stop at 6), so the CLI keeps more requests in flight: that is
+// what fills a long, high-latency link. SMALL_SLOTS of them keep sending small files alongside the big parts.
+const UPLOAD_AT_ONCE = 16;
+const SMALL_SLOTS = 4;
+const SMALL_BYTES = 1 << 20;
+const DOWNLOAD_AT_ONCE = 8;
+const RANGE_BYTES = 16 << 20;
+const TRIES = 5;
+const STALL_MS = 60_000; // a request that moves no bytes this long is dropped and retried
+const HASH_CACHE_MAX = 50_000;
+const POLL_MS = 2000;
+
+// Mirrors convex/lib/presets.ts.
+const RESOLUTIONS = ["360p", "720p", "1080p", "4k"];
+const QUALITIES = ["draft", "standard", "high"];
+const RETENTIONS = ["1-day", "3-days", "7-days", "30-days", "forever"];
+const SITE_RETENTIONS = ["7-days", "30-days", "90-days", "never"];
+const ACTIVE = new Set(["queued", "rendering"]);
+
+// ---------------------------------------------------------------- errors
+
+export class CliError extends Error {
+  constructor(message, exitCode = EXIT.ERROR, extra = undefined) {
+    super(message);
+    this.exitCode = exitCode;
+    this.extra = extra;
+  }
+}
+class ApiError extends CliError {
+  constructor(status, body, fallback) {
+    const msg = body?.error || fallback || `The API answered HTTP ${status}`;
+    const hint = status === 401 && !/login/i.test(msg) ? ` (${msg.replace(/\.$/, "")}). Your login expired or was revoked; run: tars-renderer login` : "";
+    super(hint ? `Not authorized${hint}` : msg, status === 401 ? EXIT.AUTH : EXIT.ERROR);
+    this.status = status;
+    this.code = body?.code;
+    this.body = body;
+  }
+}
+const usage = (msg) => new CliError(msg, EXIT.USAGE);
+const notLoggedIn = () =>
+  new CliError("Not logged in. Run: tars-renderer login", EXIT.AUTH);
+
+// ---------------------------------------------------------------- pure helpers (exported for tests)
+
+const BOOLEAN = new Set(["json", "yes", "help", "watch", "mine", "muted", "rehash", "all", "local", "purge", "repo"]);
+const ALIASES = { h: "help", y: "yes" };
+
+/** `--x value`, `--x=value`, boolean `--x`, `-h`/`-y`, `--` ends options. A non-boolean flag without a value is `true`. */
+export function parseArgs(argv) {
+  const out = { _: [], flags: {} };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--") {
+      out._.push(...argv.slice(i + 1));
+      break;
+    }
+    if (a.startsWith("--") && a.length > 2) {
+      const eq = a.indexOf("=");
+      const name = eq > 0 ? a.slice(2, eq) : a.slice(2);
+      if (eq > 0) {
+        const v = a.slice(eq + 1);
+        out.flags[name] = BOOLEAN.has(name) ? !/^(false|no|0)$/i.test(v) : v;
+      } else if (BOOLEAN.has(name)) out.flags[name] = true;
+      else if (i + 1 < argv.length && !argv[i + 1].startsWith("-")) out.flags[name] = argv[++i];
+      else out.flags[name] = true;
+    } else if (/^-[a-z]$/i.test(a) && ALIASES[a[1]]) out.flags[ALIASES[a[1]]] = true;
+    else out._.push(a);
+  }
+  return out;
+}
+
+/** Same rule as src/upload/detectVersion.ts: the most frequent `4.0.N` within `window` chars of "remotion" in bundle.js. */
+export function detectRemotionVersion(bundleJs, window = 200) {
+  const lower = bundleJs.toLowerCase();
+  const counts = new Map();
+  for (const m of bundleJs.matchAll(/(?<![\d.])4\.0\.\d+(?![\d.])/g)) {
+    const at = m.index;
+    const near = lower.slice(Math.max(0, at - window), at + m[0].length + window);
+    if (near.includes("remotion")) counts.set(m[0], (counts.get(m[0]) ?? 0) + 1);
+  }
+  let best = null;
+  for (const [v, n] of counts) if (best === null || n > counts.get(best)) best = v;
+  return best;
+}
+
+/** Same messages as src/pages/upload/folderProblem.ts, worded for a path argument. Null when index.html and bundle.js are at the root. */
+// Same limit as the server (convex/lib/uploadUtils.ts UPLOAD_LIMITS.files), checked before hashing.
+const MAX_FILES = 8000;
+
+export function folderProblem(paths) {
+  if (!paths.length) return "That folder is empty. Pass the build folder that `npx remotion bundle` created.";
+  if (paths.length > MAX_FILES) {
+    return `This build has ${paths.length.toLocaleString("en-US")} files; the limit is ${MAX_FILES.toLocaleString("en-US")}. Move unused assets out of public/ (or turn image sequences into a video) and rebuild, then upload it again.`;
+  }
+  const has = new Set(paths);
+  if (has.has("index.html") && has.has("bundle.js")) return null;
+  const inner = paths
+    .filter((p) => p.endsWith("/index.html") && has.has(p.slice(0, -"index.html".length) + "bundle.js"))
+    .sort((a, b) => a.length - b.length)[0];
+  if (inner) {
+    const dir = inner.slice(0, -"/index.html".length);
+    const root = has.has("package.json") ? "the project root" : "the folder around the build";
+    return `You passed ${root}. Pass the "${dir}" folder inside it.`;
+  }
+  if (has.has("package.json")) {
+    return "You passed the project root, and it has no build yet. Run `npx remotion bundle src/index.ts --out-dir build`, then pass the build folder.";
+  }
+  const missing = ["index.html", "bundle.js"].filter((p) => !has.has(p));
+  return `${missing.join(" and ")} not found at the top of this folder. Pass the build folder that \`npx remotion bundle\` created (the one containing index.html and bundle.js).`;
+}
+
+/** A path relative to the build root, with `/` separators (Windows `\` becomes `/`). */
+export const toPosixPath = (rel, sep = path.sep) => rel.split(sep).join("/");
+
+/** Byte ranges (inclusive `end`) for the server's part URLs. */
+export function partRanges(size, partSize, count) {
+  const n = Math.ceil(size / partSize);
+  if (n !== count) throw new Error(`The server sent ${count} part URLs for a file that needs ${n}`);
+  return Array.from({ length: n }, (_, i) => ({ start: i * partSize, end: Math.min(size, (i + 1) * partSize) - 1 }));
+}
+
+/** "a-b" → [a, b]; whole numbers only when `integers`. */
+export function parseRange(s, flag, integers) {
+  const m = /^\s*(\d+(?:\.\d+)?)\s*-\s*(\d+(?:\.\d+)?)\s*$/.exec(String(s));
+  if (!m) throw usage(`${flag} must look like ${integers ? "0-299" : "0-10 or 2.5-8"}`);
+  const [a, b] = [Number(m[1]), Number(m[2])];
+  if (integers && (!Number.isInteger(a) || !Number.isInteger(b))) throw usage(`${flag} takes whole frame numbers`);
+  if (b < a) throw usage(`${flag}: the end must not be before the start`);
+  return [a, b];
+}
+
+/** Seconds [a, b) → inclusive frame range at `fps`: 0-10 at 30 fps is frames 0-299. */
+export function secondsToFrames([a, b], fps, durationInFrames) {
+  const start = Math.round(a * fps);
+  const end = Math.round(b * fps) - 1;
+  const total = +(durationInFrames / fps).toFixed(2);
+  if (end < start) throw usage(`--seconds ${a}-${b} is shorter than one frame at ${fps} fps`);
+  if (end > durationInFrames - 1) throw usage(`--seconds must be within 0-${total} (the composition is ${total} s long)`);
+  return [start, end];
+}
+
+/** Frames → hh:mm:ss:ff. */
+export function timecode(frames, fps) {
+  const s = Math.floor(frames / fps);
+  const ff = Math.floor(frames - s * fps);
+  const p = (n) => String(n).padStart(2, "0");
+  return `${p(Math.floor(s / 3600))}:${p(Math.floor((s % 3600) / 60))}:${p(s % 60)}:${p(ff)}`;
+}
+
+export const fmtInt = (n) => Math.round(n ?? 0).toLocaleString("en-US");
+export const fmtUsd = (n) => `$${(n ?? 0).toFixed(2)}`;
+export function fmtBytes(n) {
+  if (n == null) return "—";
+  const units = ["B", "KB", "MB", "GB", "TB"];
+  let i = 0;
+  while (n >= 1024 && i < units.length - 1) (n /= 1024), i++;
+  return i ? `${n.toFixed(1)} ${units[i]}` : `${n} B`;
+}
+export function fmtDuration(ms) {
+  const s = Math.max(0, Math.round(ms / 1000));
+  const h = Math.floor(s / 3600);
+  const m = Math.floor((s % 3600) / 60);
+  return h ? `${h}h ${m}m` : m ? `${m}m ${s % 60}s` : `${s}s`;
+}
+const when = (t) => (!t ? "—" : Date.now() - t < 86_400_000 ? `${fmtDuration(Date.now() - t)} ago` : new Date(t).toISOString().slice(0, 10));
+
+/** ▮▮▮▮▮▮▯▯▯▯▯▯ for progress 0..1. */
+export function chunkStrip(progress, cells = 24) {
+  const filled = Math.max(0, Math.min(cells, Math.round((progress ?? 0) * cells)));
+  return "▮".repeat(filled) + "▯".repeat(cells - filled);
+}
+
+/** One status line for a render row: strip, percent, frames, cost, elapsed, status. */
+export function progressLine(r, now = Date.now()) {
+  const progress = r.status === "done" ? 1 : r.progress ?? 0;
+  const pct = `${Math.floor(progress * 100)}%`.padStart(4);
+  const cost = r.costUsd ? fmtUsd(r.costUsd) : `~${fmtUsd(r.estimatedCostUsd)}`;
+  const elapsed = fmtDuration((r.finishedAt ?? now) - r.startedAt);
+  return `${chunkStrip(progress)} ${pct}  ${fmtInt(r.framesRendered)} frames  ${cost}  ${elapsed}  ${r.status}`;
+}
+
+export const maskToken = (t) => (t ? `${t.slice(0, 8)}…` : "(none)");
+export const normalizeApi = (u) => (u ? String(u).trim().replace(/\/+$/, "").replace(/\/api\/v1$/, "") : u);
+
+/** RenderParams from flags; only the fields given (the server fills DEFAULT_PARAMS). `comp` is needed for --seconds. */
+export function buildParams(f, comp) {
+  const pick = (flag, v, allowed) => {
+    const x = String(v).toLowerCase();
+    if (!allowed.includes(x)) throw usage(`--${flag} must be one of ${allowed.join(", ")}`);
+    return x;
+  };
+  const p = {};
+  if (f.res !== undefined) p.resolution = pick("res", f.res, RESOLUTIONS);
+  if (f.quality !== undefined) p.quality = pick("quality", f.quality, QUALITIES);
+  if (f.keep !== undefined) p.retention = pick("keep", f.keep, RETENTIONS);
+  if (f.muted) p.muted = true;
+  if (f.frames !== undefined && f.seconds !== undefined) throw usage("Use --frames or --seconds, not both");
+  if (f.frames !== undefined) p.frameRange = parseRange(f.frames, "--frames", true);
+  if (f.seconds !== undefined) p.frameRange = secondsToFrames(parseRange(f.seconds, "--seconds", false), comp.fps, comp.durationInFrames);
+  return p;
+}
+
+// ---------------------------------------------------------------- transfer helpers (same as src/lib/transfer.ts)
+
+/** An HTTP failure. `status` 0 means no answer arrived (network error, stall). */
+class TransferError extends Error {
+  constructor(message, status, retryable = isRetryableStatus(status)) {
+    super(message);
+    this.status = status;
+    this.retryable = retryable;
+  }
+}
+
+/** 5xx, 408, 429 and no answer are worth retrying. 403 (expired or bad signature) and other 4xx are not. */
+export const isRetryableStatus = (status) => status === 0 || status === 408 || status === 429 || status >= 500;
+
+/** Runs `fn` until it succeeds, fails with a non-retryable TransferError, runs out of tries, or `signal` aborts. */
+async function withRetry(fn, signal, tries = TRIES) {
+  for (let attempt = 1; ; attempt++) {
+    try {
+      return await fn();
+    } catch (e) {
+      if (signal.aborted || attempt >= tries || (e instanceof TransferError && !e.retryable)) throw e;
+      // Exponential backoff with full jitter, so retrying connections don't stampede together.
+      await delay(Math.random() * Math.min(15_000, 500 * 2 ** attempt), undefined, { signal });
+    }
+  }
+}
+
+/**
+ * Keeps up to `limit` jobs running; each free slot asks `next()` for its next job. The first failure aborts `ctrl`
+ * (stopping the jobs in flight) and is thrown once every slot has settled.
+ */
+export async function runPool(limit, next, ctrl) {
+  const first = {};
+  const slot = async () => {
+    while (!ctrl.signal.aborted) {
+      const job = next();
+      if (!job) return;
+      try {
+        await job();
+      } catch (error) {
+        if (!first.failed) Object.assign(first, { failed: true, error });
+        ctrl.abort();
+      }
+    }
+  };
+  await Promise.all(Array.from({ length: Math.max(1, limit) }, slot));
+  if (first.failed) throw first.error;
+  ctrl.signal.throwIfAborted();
+}
+
+/**
+ * Picks the largest job first (the longest transfer never starts last) while up to `smallSlots` slots take the
+ * smallest jobs: small files are bound by round trips, not bandwidth, so they ride along with the big parts.
+ */
+export function largestFirst(items, smallSlots, smallBytes = SMALL_BYTES) {
+  const order = [...items].sort((a, b) => b.size - a.size);
+  let head = 0;
+  let tail = order.length - 1;
+  let small = 0;
+  return () => {
+    if (head > tail) return undefined;
+    if (small >= smallSlots || order[tail].size >= smallBytes) return order[head++].run;
+    const job = order[tail--].run;
+    small++;
+    return () => job().finally(() => small--);
+  };
+}
+
+/** Inclusive byte ranges of about `rangeBytes`, a multiple of `connections` of them so the last round has no straggler. */
+export function splitRanges(total, rangeBytes, connections) {
+  const count = Math.max(1, Math.round(total / rangeBytes / connections)) * connections;
+  const size = Math.ceil(total / count);
+  const out = [];
+  for (let pos = 0; pos < total; pos += size) out.push({ pos, end: Math.min(total, pos + size) - 1 });
+  return out;
+}
+
+/** Throughput over the last `windowMs` (bytes/s) and the time left at that rate; null until there's a second of data. */
+export function rateMeter(windowMs = 10_000) {
+  const samples = [];
+  let latest = [0, 0];
+  const rate = () => (samples.length && latest[0] - samples[0][0] >= 1000 ? ((latest[1] - samples[0][1]) / (latest[0] - samples[0][0])) * 1000 : null);
+  return {
+    update(total, now = Date.now()) {
+      latest = [now, total];
+      if (!samples.length || now - samples[samples.length - 1][0] >= 200) samples.push(latest);
+      while (samples.length > 1 && now - samples[0][0] > windowMs) samples.shift();
+    },
+    rate,
+    etaMs: (remaining) => (rate() > 0 ? (remaining / rate()) * 1000 : null),
+  };
+}
+
+/** Aborts `ctrl` with a retryable error when `alive()` isn't called for STALL_MS: a connection that silently stalled. */
+function stallTimer(ctrl, what) {
+  let t;
+  const alive = () => {
+    clearTimeout(t);
+    t = setTimeout(() => ctrl.abort(new TransferError(`No ${what} for ${STALL_MS / 1000} s`, 0)), STALL_MS);
+  };
+  alive();
+  return { alive, stop: () => clearTimeout(t) };
+}
+
+/** A controller for one request that also aborts when `signal` does. Call `unlink()` when the request is over. */
+function linked(signal) {
+  const ctrl = new AbortController();
+  const onAbort = () => ctrl.abort(signal.reason);
+  setMaxListeners(0, signal); // one listener per request in flight; not a leak, so no warning
+  if (signal.aborted) onAbort();
+  else signal.addEventListener("abort", onAbort, { once: true });
+  return { ctrl, unlink: () => signal.removeEventListener("abort", onAbort) };
+}
+
+// ---------------------------------------------------------------- output
+
+const ctx = { json: false };
+const COLOR = !!process.stdout.isTTY && !process.env.NO_COLOR;
+const paint = (code) => (s) => (COLOR ? `\x1b[${code}m${s}\x1b[0m` : String(s));
+const bold = paint(1);
+const dim = paint(2);
+const red = paint(31);
+const green = paint(32);
+const yellow = paint(33);
+const cyan = paint(36);
+const visible = (s) => s.replace(/\x1b\[[0-9;]*m/g, "").length;
+
+/** Human output on stdout; silent in --json mode. */
+const say = (s = "") => !ctx.json && process.stdout.write(s + "\n");
+/** Logs and progress, always on stderr. */
+const info = (s = "") => {
+  live.clear();
+  process.stderr.write(s + "\n");
+};
+const warn = (s) => info(yellow("! ") + s);
+/** The command's result: one JSON document in --json mode, otherwise the human rendering. */
+const done = (data, human) => (ctx.json ? process.stdout.write(JSON.stringify(data, null, 2) + "\n") : human?.(data));
+
+/** One redrawn status line on a TTY stderr, throttled; line logs otherwise. */
+const live = {
+  last: 0,
+  shown: false,
+  update(text, force = false) {
+    const now = Date.now();
+    const tty = process.stderr.isTTY;
+    if (!force && now - this.last < (tty ? 1000 : 5000)) return;
+    this.last = now;
+    if (!tty) return void process.stderr.write(text + "\n");
+    process.stderr.write(`\r\x1b[2K${text.slice(0, (process.stderr.columns || 100) - 1)}`);
+    this.shown = true;
+  },
+  clear() {
+    if (this.shown) process.stderr.write("\r\x1b[2K");
+    this.shown = false;
+    this.last = 0;
+  },
+};
+
+function spinner(text) {
+  if (!process.stderr.isTTY) {
+    info(text + "…");
+    return { stop() {} };
+  }
+  const frames = "⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏";
+  let i = 0;
+  const t = setInterval(() => live.update(`${cyan(frames[i++ % frames.length])} ${text}`, true), 100);
+  return {
+    stop() {
+      clearInterval(t);
+      live.clear();
+    },
+  };
+}
+
+/** Aligned table on stdout. `cols`: [header, cell(row), "right"?]. */
+function table(rows, cols) {
+  const cells = rows.map((r) => cols.map(([, f]) => String(f(r) ?? "")));
+  const head = cols.map(([h]) => h);
+  const w = head.map((h, i) => Math.max(h.length, ...cells.map((c) => visible(c[i]))));
+  const pad = (s, i) => {
+    const gap = " ".repeat(w[i] - visible(s));
+    return cols[i][2] === "right" ? gap + s : i === cols.length - 1 ? s : s + gap;
+  };
+  say(dim(head.map(pad).join("  ")));
+  for (const c of cells) say(c.map(pad).join("  "));
+}
+
+const statusColor = (s) => ({ done: green, ready: green, failed: red, rendering: cyan, uploading: cyan, queued: yellow }[s] ?? ((x) => x))(s);
+
+// ---------------------------------------------------------------- config + API
+
+const configDir = () => path.join(os.homedir(), ".tars-renderer");
+const configFile = () => path.join(configDir(), "config.json");
+
+/** Moves the settings folder from the old package name, once, so an existing sign-in keeps working. */
+export function migrateLegacyConfigDir() {
+  const old = path.join(os.homedir(), LEGACY.dir);
+  try {
+    if (!fs.existsSync(old) || fs.existsSync(configDir())) return;
+    fs.renameSync(old, configDir());
+    const cfg = readConfigFile();
+    // Keychain / Secret Service entries were saved under the old service name; remember that for reads and deletes.
+    if (cfg && (cfg.tokenStore === "keychain" || cfg.tokenStore === "secret-tool") && !cfg.tokenService) saveConfig({ ...cfg, tokenService: LEGACY.keyring });
+  } catch {}
+}
+
+function readConfigFile() {
+  try {
+    return JSON.parse(fs.readFileSync(configFile(), "utf8"));
+  } catch (e) {
+    if (e.code === "ENOENT") return null;
+    throw new CliError(`Can't read ${configFile()}: ${e.message}. Delete it and run tars-renderer login.`);
+  }
+}
+
+/** Config file overridden by TARS_RENDERER_API / TARS_RENDERER_TOKEN. */
+function loadConfig() {
+  const f = readConfigFile() ?? {};
+  return {
+    ...f,
+    api: normalizeApi(process.env.TARS_RENDERER_API || f.api),
+    token: process.env.TARS_RENDERER_TOKEN || readToken(f),
+    tokenFromEnv: !!process.env.TARS_RENDERER_TOKEN,
+  };
+}
+
+function saveConfig(c) {
+  fs.mkdirSync(configDir(), { recursive: true, mode: 0o700 });
+  fs.writeFileSync(configFile(), JSON.stringify(c, null, 2) + "\n", { mode: 0o600 });
+  try {
+    fs.chmodSync(configFile(), 0o600); // writeFile's mode only applies when creating; best effort on Windows
+  } catch {}
+}
+
+// ---------------------------------------------------------------- token storage
+//
+// The token goes to the OS credential store when there is one, so config.json (which agents may read) holds no secret:
+// the macOS Keychain, Windows DPAPI (encrypted for this user; the blob is kept in config.json as `tokenProtected`) or
+// the Secret Service through secret-tool on Linux. Otherwise it stays in config.json (mode 0600). The token is always
+// written to the helper's stdin, never put on a command line where `ps` would show it.
+// TARS_RENDERER_TOKEN_STORE=file forces the file (CI, or a keyring that misbehaves).
+
+const KEYRING_SERVICE = "tars-renderer";
+const PS_ENCRYPT = "$t=[Console]::In.ReadLine(); ConvertTo-SecureString -String $t -AsPlainText -Force | ConvertFrom-SecureString";
+const PS_DECRYPT =
+  "$b=[Console]::In.ReadLine(); $s=ConvertTo-SecureString -String $b; [Runtime.InteropServices.Marshal]::PtrToStringBSTR([Runtime.InteropServices.Marshal]::SecureStringToBSTR($s))";
+
+/** The OS helpers, replaceable in tests. `run(cmd, args, stdin)` resolves to `{ status, stdout }` (status null: couldn't run). */
+export const credentialStore = {
+  platform: process.platform,
+  run(cmd, args, input) {
+    const r = spawnSync(cmd, args, { input, encoding: "utf8", windowsHide: true, timeout: 20_000 });
+    return { status: r.error ? null : r.status, stdout: r.stdout ?? "" };
+  },
+};
+const powershell = (script, input) => credentialStore.run("powershell", ["-NoProfile", "-NonInteractive", "-Command", script], input);
+
+/** The token config `f` points at, or undefined. */
+export function readToken(f) {
+  const { run } = credentialStore;
+  const out = (r) => (r.status === 0 && r.stdout.trim()) || undefined;
+  if (typeof f.tokenProtected === "string" && f.tokenProtected.startsWith("dpapi:")) return out(powershell(PS_DECRYPT, f.tokenProtected.slice(6) + "\n"));
+  if (f.tokenStore === "keychain") return out(run("security", ["find-generic-password", "-s", f.tokenService ?? KEYRING_SERVICE, "-a", f.api, "-w"], ""));
+  if (f.tokenStore === "secret-tool") return out(run("secret-tool", ["lookup", "service", f.tokenService ?? KEYRING_SERVICE, "api", f.api], ""));
+  return f.token;
+}
+
+/** Stores the token for `api` in the best store that works (it's read back to check); returns the config fields to save. */
+export function storeToken(api, token) {
+  const { platform, run } = credentialStore;
+  // Both go into a `security -i` command line, so only plain characters (tokens are base64url, the API a URL).
+  if (process.env.TARS_RENDERER_TOKEN_STORE !== "file" && /^[\w-]+$/.test(token) && /^[\w.:/-]+$/.test(api)) {
+    const works = (fields) => (readToken({ api, ...fields }) === token ? fields : null);
+    let fields = null;
+    if (platform === "win32") {
+      const r = powershell(PS_ENCRYPT, token + "\n");
+      if (r.status === 0 && /^[0-9a-f]+$/i.test(r.stdout.trim())) fields = works({ tokenProtected: `dpapi:${r.stdout.trim()}` });
+    } else if (platform === "darwin") {
+      // `security add-generic-password -w <token>` would put the token in argv; `security -i` reads the command from stdin.
+      const r = run("security", ["-i"], `add-generic-password -U -s ${KEYRING_SERVICE} -a ${api} -w ${token}\n`);
+      if (r.status === 0) fields = works({ tokenStore: "keychain" });
+    } else if (run("secret-tool", ["store", "--label=tars-renderer", "service", KEYRING_SERVICE, "api", api], token).status === 0) {
+      fields = works({ tokenStore: "secret-tool" });
+    }
+    if (fields) return fields;
+  }
+  return { token, tokenStore: "file" }; // "file" also stops the next commands from retrying the migration
+}
+
+/** Removes the stored token; returns `f` without its token fields. */
+export function forgetToken(f) {
+  const { token, tokenProtected, tokenStore, tokenService, ...rest } = f;
+  const service = tokenService ?? KEYRING_SERVICE;
+  if (tokenStore === "keychain") credentialStore.run("security", ["delete-generic-password", "-s", service, "-a", f.api], "");
+  if (tokenStore === "secret-tool") credentialStore.run("secret-tool", ["clear", "service", service, "api", f.api], "");
+  return rest;
+}
+
+export const tokenLocation = (f) =>
+  f.tokenProtected
+    ? "Windows DPAPI (encrypted for your user account, in config.json)"
+    : f.tokenStore === "keychain"
+      ? "macOS Keychain"
+      : f.tokenStore === "secret-tool"
+        ? "Secret Service keyring (secret-tool)"
+        : f.token
+          ? `${configFile()} (plain text, mode 0600)`
+          : "none";
+
+/** A config from before token storage keeps its token in plain text: move it to the credential store. */
+function migrateToken() {
+  try {
+    const f = readConfigFile();
+    if (!f?.token || !f.api || f.tokenStore || process.env.TARS_RENDERER_TOKEN_STORE === "file") return;
+    const { token, ...rest } = f;
+    saveConfig({ ...rest, ...storeToken(f.api, token) });
+  } catch {}
+}
+
+/** JSON request to `<api>/api/v1<p>`. Throws ApiError with the server's `{ error }` as the message. */
+async function request(cfg, method, p, body, { auth = true } = {}) {
+  if (!cfg.api || (auth && !cfg.token)) throw notLoggedIn();
+  // Checked on every call (config and TARS_RENDERER_API can change after login): tokens only over https or localhost.
+  if (!isSafeUrl(cfg.api)) throw new CliError(`Refusing to contact ${cfg.api}: the API address must use https://. Run tars-renderer login again.`);
+  let res;
+  try {
+    res = await fetch(`${cfg.api}/api/v1${p}`, {
+      method,
+      headers: {
+        ...(body !== undefined ? { "Content-Type": "application/json" } : {}),
+        ...(auth ? { Authorization: `Bearer ${cfg.token}` } : {}),
+      },
+      body: body === undefined ? undefined : JSON.stringify(body),
+    });
+  } catch (e) {
+    throw new CliError(`Can't reach the API at ${cfg.api} (${e.cause?.code || e.cause?.message || e.message}). Check your connection and the API URL.`);
+  }
+  const text = await res.text();
+  let data = null;
+  try {
+    data = text ? JSON.parse(text) : null;
+  } catch {}
+  if (!res.ok) throw new ApiError(res.status, data, text && !data ? `The API answered HTTP ${res.status}: ${text.slice(0, 200)}` : undefined);
+  return data;
+}
+
+function needLogin() {
+  const cfg = loadConfig();
+  if (!cfg.api || !cfg.token) throw notLoggedIn();
+  return cfg;
+}
+
+const enc = encodeURIComponent;
+const idOf = (row) => row.id ?? row._id;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+// ---------------------------------------------------------------- confirm + Ctrl-C
+
+let onCancel = null;
+let cancelling = false;
+async function interrupt() {
+  if (cancelling) process.exit(EXIT.CANCELLED); // second Ctrl-C: leave now
+  cancelling = true;
+  live.clear();
+  process.stderr.write("\nCancelled.\n");
+  try {
+    await onCancel?.();
+  } catch {}
+  process.exit(EXIT.CANCELLED);
+}
+
+/** Asks y/N on stderr. --yes skips; --json or no TTY without --yes exits 3 with `payload` on stdout. */
+async function confirm(question, flags, payload) {
+  if (flags.yes) return true;
+  if (ctx.json || !process.stdin.isTTY) {
+    throw new CliError("Confirmation needed. Re-run with --yes to go ahead.", EXIT.CONFIRM, { needsConfirm: true, ...payload });
+  }
+  live.clear();
+  const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+  rl.on("SIGINT", () => {
+    rl.close();
+    interrupt();
+  });
+  const answer = await new Promise((r) => rl.question(`${question} ${dim("[y/N]")} `, r));
+  rl.close();
+  return /^y(es)?$/i.test(answer.trim());
+}
+
+/** Only plain http(s) URLs made of URL-safe characters are ever handed to the OS; anything else is just printed. */
+export const isOpenableUrl = (href) =>
+  /^https?:\/\//.test(href) && /^[A-Za-z0-9\-._~:/?#[\]@!$&'()*+,;=%]+$/.test(href);
+
+function openBrowser(url) {
+  let href;
+  try {
+    href = new URL(url).href;
+  } catch {
+    return;
+  }
+  // Only plain web URLs with URL-safe characters; anything else is printed, never opened.
+  if (!isOpenableUrl(href)) return;
+  // No shell anywhere: cmd.exe would expand %VAR% and & inside the URL (command injection).
+  const [cmd, args] =
+    process.platform === "win32"
+      ? ["rundll32", ["url.dll,FileProtocolHandler", href]]
+      : [process.platform === "darwin" ? "open" : "xdg-open", [href]];
+  try {
+    const child = spawn(cmd, args, { stdio: "ignore", detached: true, shell: false });
+    child.on("error", () => {});
+    child.unref();
+  } catch {}
+}
+
+// ---------------------------------------------------------------- commands: auth
+
+// Tokens travel in headers, so only talk to https (or a local dev server over http).
+export const isSafeUrl = (u) => /^https:\/\/[^\s/]+/.test(u) || /^http:\/\/(localhost|127\.0\.0\.1)(:\d+)?(\/|$)/.test(u);
+
+/** The portal publishes its API address at /cli/config.json, so users only ever need the portal URL. */
+async function apiFromPortal(portal) {
+  let res;
+  try {
+    res = await fetch(`${portal}/cli/config.json`, { headers: { accept: "application/json" } });
+  } catch (e) {
+    throw new CliError(`Can't reach ${portal}: ${e.message}`);
+  }
+  const body = res.ok && /json/.test(res.headers.get("content-type") ?? "") ? await res.json().catch(() => null) : null;
+  if (!body?.api) throw new CliError(`${portal} doesn't look like a Tars Renderer (no /cli/config.json). Check the address.`);
+  return normalizeApi(body.api);
+}
+
+async function cmdLogin(_, f) {
+  const prev = readConfigFile() ?? {};
+  // An address is only needed for another deployment (development, staging); normally the built-in portal is used.
+  let portal = (typeof _[0] === "string" ? _[0] : typeof f.portal === "string" ? f.portal : undefined)?.replace(/\/+$/, "");
+  let api = normalizeApi(typeof f.api === "string" ? f.api : process.env.TARS_RENDERER_API || "");
+  if (!portal && !api) portal = prev.portal || DEFAULT_PORTAL;
+  if (portal && !isSafeUrl(portal)) throw usage(`The portal address must start with https://, got "${portal}"`);
+  if (!api && portal) api = await apiFromPortal(portal);
+  api ||= normalizeApi(prev.api || "");
+  if (!api) throw usage(`Couldn't find the Tars Renderer API. Check your connection to ${DEFAULT_PORTAL}.`);
+  if (!isSafeUrl(api)) throw usage(`The API address must use https://, got "${api}"`);
+  const cfg = { api };
+
+  const start = await request(cfg, "POST", "/device/start", { clientName: `tars-renderer on ${os.hostname()}` }, { auth: false });
+  if (!/^[A-Z0-9]{4}-[A-Z0-9]{4}$/.test(String(start.userCode))) throw new CliError("The API returned an invalid login code.");
+  // The approval link is built from the portal the user typed (or saved), not taken from the API response,
+  // so a wrong or hostile API can't send the browser somewhere else. A server link is only shown, never opened.
+  const knownPortal = portal ?? (prev.api === api ? prev.portal : undefined);
+  if (!portal && knownPortal) portal = knownPortal;
+  const trusted = portal && isSafeUrl(portal) ? `${portal}/cli/authorize?code=${encodeURIComponent(start.userCode)}` : null;
+  const shown = trusted ?? (typeof start.verifyUrl === "string" && isSafeUrl(start.verifyUrl) ? start.verifyUrl : null);
+  const url = shown;
+
+  info("");
+  info(`  Your login code:  ${bold(cyan(start.userCode))}`);
+  info("");
+  if (url) {
+    info(`  Opening ${url}`);
+    info("  Check that the code matches, then click Approve.");
+    if (trusted) openBrowser(trusted);
+  } else {
+    info(`  Open ${bold(start.verifyPath)} on Tars Renderer (https://<portal>${start.verifyPath}),`);
+    info("  sign in, check that the code matches and click Approve.");
+    info(dim("  (The server has no PORTAL_URL set. Pass --portal https://<portal> for a clickable link.)"));
+  }
+  info("");
+
+  const deadline = Date.now() + (start.expiresIn ?? 600) * 1000;
+  let interval = (start.interval ?? 3) * 1000;
+  const spin = spinner("Waiting for approval in the browser (Ctrl-C to cancel)");
+  let got;
+  try {
+    while (!got) {
+      await sleep(interval);
+      if (Date.now() > deadline) throw new CliError("The code expired before it was approved. Run tars-renderer login again.");
+      try {
+        got = await request(cfg, "POST", "/device/poll", { deviceCode: start.deviceCode }, { auth: false });
+      } catch (e) {
+        if (!(e instanceof ApiError)) throw e;
+        if (e.status === 428 || e.code === "authorization_pending") continue;
+        if (e.status === 429 || e.code === "slow_down") {
+          interval = Number.isFinite(e.body?.interval) ? e.body.interval * 1000 : interval + 5000;
+          continue;
+        }
+        if (e.code === "expired_token") throw new CliError("The code expired before it was approved. Run tars-renderer login again.");
+        if (e.code === "access_denied") throw new CliError("The login was denied in the browser.");
+        throw e;
+      }
+    }
+  } finally {
+    spin.stop();
+  }
+
+  forgetToken(prev); // an older login's keyring entry
+  const stored = storeToken(api, got.token);
+  saveConfig({ api, portal, email: got.email, ...stored });
+  const where = tokenLocation(stored);
+  const out = { email: got.email, name: got.name, api, portal: portal ?? null, token: maskToken(got.token), tokenExpiresAt: got.expiresAt, config: configFile(), tokenStorage: where };
+  done(out, () => {
+    say(`${green("✔")} Logged in as ${bold(got.email)}${got.name ? ` (${got.name})` : ""}`);
+    say(dim(`  Token ${maskToken(got.token)} saved in ${where}${got.expiresAt ? `, valid until ${new Date(got.expiresAt).toISOString().slice(0, 10)}` : ""}`));
+    say(dim("  Next: tars-renderer projects"));
+  });
+}
+
+/**
+ * Signs this device out: revokes the token on the server (all of the user's devices with --all), then removes it from
+ * the OS credential store and the config. --local skips the server (offline); --purge also deletes ~/.tars-renderer.
+ */
+async function cmdLogout(_, f) {
+  if (f.all && f.local) throw usage("--all needs the server, so it can't be combined with --local");
+  let cfg = null;
+  try {
+    cfg = loadConfig();
+  } catch {} // an unreadable config can still be purged
+  const signedIn = !!cfg?.token;
+  if (f.all && !signedIn) throw notLoggedIn();
+
+  let revoked = 0;
+  let serverError = null;
+  if (signedIn && !f.local) {
+    try {
+      revoked = (await request(cfg, "POST", "/logout", f.all ? { all: true } : {}))?.revoked ?? 1;
+    } catch (e) {
+      // A token that is already expired or revoked is fine: there's nothing left to revoke.
+      if (e.status !== 401) serverError = e.message;
+    }
+  }
+  if (f.all && serverError) throw new CliError(`Couldn't sign out your other devices: ${serverError}. Nothing was changed; try again, or use "Sign out all devices" on the portal.`);
+
+  const file = readConfigFile();
+  if (file && (file.token || file.tokenProtected || file.tokenStore)) {
+    const { email, ...rest } = forgetToken(file);
+    saveConfig(rest);
+  }
+  if (f.purge) fs.rmSync(path.dirname(configFile()), { recursive: true, force: true });
+
+  const out = { ok: true, wasSignedIn: signedIn, revokedOnServer: revoked, localOnly: !!f.local, purged: !!f.purge, serverError };
+  done(out, () => {
+    if (!signedIn && !f.purge) return say("You're already signed out.");
+    if (f.all) say(`${green("✔")} Signed out ${plural(revoked, "device")} (all of yours, this one included).`);
+    else if (signedIn) say(`${green("✔")} Signed out.`);
+    if (f.purge) say(`${green("✔")} Removed ${path.dirname(configFile())} (settings and upload cache).`);
+    if (serverError) say(yellow(`  Couldn't reach the server (${serverError}), so the sign-in is only removed here. Sign this device out on the portal's CLI & Agents page.`));
+    if (f.local && signedIn) say(dim("  The sign-in still works on the server until it expires; sign this device out on the portal to revoke it."));
+    if (cfg?.tokenFromEnv) say(yellow("  TARS_RENDERER_TOKEN is still set in your environment; unset it too."));
+  });
+}
+
+async function cmdWhoami() {
+  const cfg = needLogin();
+  const me = await request(cfg, "GET", "/me");
+  const out = { ...me, api: cfg.api, portal: cfg.portal ?? null, token: maskToken(cfg.token), tokenFromEnv: cfg.tokenFromEnv };
+  done(out, () => {
+    say(`${bold(me.email)}${me.name ? ` (${me.name})` : ""}${me.isAdmin ? cyan(" · admin") : ""}`);
+    say(`${dim("API    ")} ${cfg.api}`);
+    if (cfg.portal) say(`${dim("Portal ")} ${cfg.portal}`);
+    const exp = me.tokenExpiresAt ? `, valid until ${new Date(me.tokenExpiresAt).toISOString().slice(0, 10)}` : "";
+    say(`${dim("Token  ")} ${maskToken(cfg.token)}${exp}${cfg.tokenFromEnv ? " (from TARS_RENDERER_TOKEN)" : ""}`);
+  });
+}
+
+async function cmdDoctor() {
+  const checks = [];
+  const add = (name, ok, detail) => checks.push({ name, ok, detail });
+  const major = Number(process.versions.node.split(".")[0]);
+  add("node", major >= 18, `Node ${process.versions.node}${major >= 18 ? "" : " (needs 18 or newer)"}`);
+
+  let file = null;
+  try {
+    file = readConfigFile();
+    const fromEnv = process.env.TARS_RENDERER_TOKEN ? "using TARS_RENDERER_TOKEN from the environment" : "";
+    add("config", !!file || !!fromEnv, file ? configFile() + (fromEnv ? ` (${fromEnv})` : "") : fromEnv || `No ${configFile()} (run tars-renderer login)`);
+  } catch (e) {
+    add("config", false, e.message);
+  }
+  const cfg = { ...(file ?? {}), api: normalizeApi(process.env.TARS_RENDERER_API || file?.api), token: process.env.TARS_RENDERER_TOKEN || (file ? readToken(file) : undefined) };
+  if (process.env.TARS_RENDERER_TOKEN) add("token store", true, "TARS_RENDERER_TOKEN environment variable");
+  else if (file && tokenLocation(file) !== "none") {
+    add("token store", !!cfg.token, cfg.token ? tokenLocation(file) : `${tokenLocation(file)}, but the token couldn't be read from it (run tars-renderer login)`);
+  }
+
+  let exit = EXIT.OK;
+  if (!cfg.api) {
+    add("api", false, "Not logged in (run: tars-renderer login)");
+    exit = EXIT.AUTH;
+  } else {
+    try {
+      const r = await fetch(`${cfg.api}/api/v1/me`);
+      await r.text();
+      // Any answer but 404 means the routes exist (401 without a token is expected).
+      add("api", r.status !== 404, r.status === 404 ? `${cfg.api} has no /api/v1 routes (wrong URL, or the backend isn't deployed)` : `${cfg.api} answered`);
+    } catch (e) {
+      add("api", false, `Can't reach ${cfg.api} (${e.cause?.code || e.message})`);
+    }
+    if (!cfg.token) {
+      add("token", false, "Not logged in (run tars-renderer login)");
+      exit = EXIT.AUTH;
+    } else {
+      try {
+        const me = await request(cfg, "GET", "/me");
+        add("token", true, `${maskToken(cfg.token)} is valid${me.tokenExpiresAt ? ` until ${new Date(me.tokenExpiresAt).toISOString().slice(0, 10)}` : ""}`);
+        add("allowlist", true, `${me.email} is allowed${me.isAdmin ? " (admin)" : ""}`);
+      } catch (e) {
+        if (e.status === 403) {
+          add("token", true, `${maskToken(cfg.token)} is valid`);
+          add("allowlist", false, e.message);
+        } else {
+          add("token", false, e.message);
+          if (e.status === 401) exit = EXIT.AUTH;
+        }
+      }
+    }
+  }
+  const ok = checks.every((c) => c.ok);
+  done({ ok, checks }, () => {
+    const w = Math.max(...checks.map((c) => c.name.length));
+    for (const c of checks) say(`${c.ok ? green("✔") : red("✖")} ${c.name.padEnd(w)}  ${c.detail}`);
+  });
+  if (!ok) info(red("Some checks failed."));
+  return ok ? EXIT.OK : exit || EXIT.ERROR;
+}
+
+// ---------------------------------------------------------------- commands: projects
+
+async function cmdProjects(_, f) {
+  const cfg = needLogin();
+  const rows = await request(cfg, "GET", `/projects${f.mine ? "?mine=1" : ""}`);
+  done(rows, () => {
+    if (!rows.length) return say("No projects yet. Create one: tars-renderer create <name>");
+    table(rows, [
+      ["SLUG", (p) => bold(p.slug)],
+      ["NAME", (p) => p.name],
+      ["OWNER", (p) => p.ownerName],
+      ["STATUS", (p) => statusColor(p.status) + (p.locked ? yellow(" (locked)") : "")],
+      ["REMOTION", (p) => p.remotionVersion || "—"],
+      ["FILES", (p) => fmtInt(p.fileCount), "right"],
+      ["SIZE", (p) => fmtBytes(p.totalBytes), "right"],
+      ["UPLOADED", (p) => when(p.lastUploadedAt)],
+    ]);
+  });
+}
+
+async function cmdCreate([name], f) {
+  const cfg = needLogin();
+  if (f.keep !== undefined && !SITE_RETENTIONS.includes(f.keep)) throw usage(`--keep must be one of ${SITE_RETENTIONS.join(", ")}`);
+  const r = await request(cfg, "POST", "/projects", { name, ...(f.keep ? { siteRetention: f.keep } : {}) });
+  done(r, () => {
+    say(`${green("✔")} Created project ${bold(r.slug)} ${dim(`(${r.id})`)}`);
+    say(dim(`  Next: npx remotion bundle src/index.ts --out-dir build && tars-renderer upload build --project ${r.slug}`));
+  });
+}
+
+async function getProject(cfg, ref) {
+  return request(cfg, "GET", `/projects/${enc(ref)}`);
+}
+
+function printComps(comps) {
+  if (!comps.length) return say("No compositions found.");
+  table(comps, [
+    ["COMPOSITION", (c) => bold(c.compId)],
+    ["SIZE", (c) => `${c.width}×${c.height}`, "right"],
+    ["FPS", (c) => c.fps, "right"],
+    ["DURATION", (c) => timecode(c.durationInFrames, c.fps), "right"],
+    ["FRAMES", (c) => fmtInt(c.durationInFrames), "right"],
+  ]);
+}
+
+async function cmdComps([ref]) {
+  const cfg = needLogin();
+  const { project, compositions } = await getProject(cfg, ref);
+  done({ project, compositions }, () => {
+    say(dim(`${project.name} (${project.slug}) · Remotion ${project.remotionVersion || "?"}`));
+    printComps(compositions);
+  });
+}
+
+async function cmdDeleteProject([ref], f) {
+  const cfg = needLogin();
+  if (!(await confirm(`Delete project ${bold(ref)} and all its uploaded files?`, f, { project: ref }))) throw new CliError("Cancelled; nothing was deleted.");
+  await request(cfg, "DELETE", `/projects/${enc(ref)}`);
+  done({ ok: true }, () => say(`${green("✔")} Deleted project ${ref}`));
+}
+
+// ---------------------------------------------------------------- upload
+
+/** Every regular file under `root` (symlinks and .DS_Store/Thumbs.db skipped), with POSIX relative paths and the stat fields the hash cache checks. */
+async function walk(root) {
+  const out = [];
+  async function go(dir) {
+    const entries = await fsp.readdir(dir, { withFileTypes: true });
+    await Promise.all(
+      entries.map(async (d) => {
+        if (d.isSymbolicLink() || SKIP.has(d.name)) return;
+        const abs = path.join(dir, d.name);
+        if (d.isDirectory()) return go(abs);
+        if (!d.isFile()) return;
+        const st = await fsp.stat(abs);
+        out.push({ path: toPosixPath(path.relative(root, abs)), abs, size: st.size, mtimeMs: st.mtimeMs, ctimeMs: st.ctimeMs });
+      }),
+    );
+  }
+  await go(root);
+  return out.sort((a, b) => (a.path < b.path ? -1 : 1));
+}
+
+function hashFile(abs, onBytes) {
+  return new Promise((resolve, reject) => {
+    const h = crypto.createHash("sha256");
+    fs.createReadStream(abs, { highWaterMark: 1 << 20 })
+      .on("data", (c) => {
+        h.update(c);
+        onBytes(c.length);
+      })
+      .on("end", () => resolve(h.digest("hex")))
+      .on("error", reject);
+  });
+}
+
+// SHA-256 cache in ~/.tars-renderer/hash-cache.json, so re-uploading an unchanged build skips hashing. Keyed by absolute
+// path; an entry counts only when size, mtime and ctime all match. That is rsync's quick check plus ctime, which tools
+// that restore mtimes can't set back. `upload --rehash` ignores it.
+const hashCacheFile = () => path.join(configDir(), "hash-cache.json");
+export const cacheHit = (entry, st) => !!entry && entry.size === st.size && entry.mtimeMs === st.mtimeMs && entry.ctimeMs === st.ctimeMs;
+
+function readHashCache() {
+  try {
+    const c = JSON.parse(fs.readFileSync(hashCacheFile(), "utf8"));
+    return c?.v === 1 && c.entries && typeof c.entries === "object" ? c.entries : {};
+  } catch {
+    return {};
+  }
+}
+
+/** Keeps the HASH_CACHE_MAX most recently used entries (about 10 MB) and replaces the file atomically. */
+function writeHashCache(entries) {
+  const keys = Object.keys(entries);
+  if (keys.length > HASH_CACHE_MAX) {
+    keys.sort((a, b) => entries[a].used - entries[b].used);
+    for (const k of keys.slice(0, keys.length - HASH_CACHE_MAX)) delete entries[k];
+  }
+  const tmp = `${hashCacheFile()}.${process.pid}.tmp`;
+  try {
+    fs.mkdirSync(configDir(), { recursive: true, mode: 0o700 });
+    fs.writeFileSync(tmp, JSON.stringify({ v: 1, entries }), { mode: 0o600 });
+    fs.renameSync(tmp, hashCacheFile()); // a second CLI or a crash never leaves half a file
+  } catch {
+    fs.rmSync(tmp, { force: true }); // a cache that can't be saved only costs a re-hash next time
+  }
+}
+
+/** PUTs bytes [start, start+length) of a file with an exact Content-Length (S3 rejects chunked bodies). Resolves with the ETag. */
+async function putRange(url, abs, start, length, headers, signal, onBytes) {
+  const { ctrl, unlink } = linked(signal);
+  const stall = stallTimer(ctrl, "upload progress");
+  async function* body() {
+    for await (const chunk of fs.createReadStream(abs, { start, end: start + length - 1, highWaterMark: 1 << 20 })) {
+      onBytes(chunk.length);
+      stall.alive();
+      yield chunk;
+    }
+  }
+  try {
+    const res = await fetch(url, {
+      method: "PUT",
+      body: length ? body() : "",
+      duplex: "half",
+      headers: { ...headers, "Content-Length": String(length) },
+      signal: ctrl.signal,
+    });
+    const text = await res.text();
+    // S3 answers a socket that went quiet with 400 RequestTimeout, which is safe to retry.
+    if (!res.ok) throw new TransferError(`S3 returned ${res.status}: ${text.slice(0, 300)}`, res.status, isRetryableStatus(res.status) || /RequestTimeout/.test(text));
+    return res.headers.get("etag");
+  } finally {
+    stall.stop();
+    unlink();
+  }
+}
+
+/**
+ * Port of uploadAll in src/upload/uploader.ts: one queue for whole files and multipart parts, the largest requests
+ * first while SMALL_SLOTS slots send small files, each request retried on its own with backoff. The first fatal
+ * failure (or `deps.signal`) stops everything in flight, and multipart uploads that didn't complete are aborted.
+ */
+async function uploadAll(items, localByPath, deps) {
+  const ctrl = new AbortController();
+  const cancel = () => ctrl.abort(deps.signal.reason);
+  if (deps.signal.aborted) cancel();
+  deps.signal.addEventListener("abort", cancel);
+  const bytesTotal = sum(items);
+  const meter = rateMeter();
+  let bytesDone = 0;
+  let filesDone = 0;
+  let lastReport = 0;
+  let current = "";
+  const tick = (delta) => {
+    bytesDone += delta;
+    meter.update(bytesDone);
+    deps.onProgress({ filesDone, bytesDone, bytesTotal, speed: meter.rate(), etaMs: meter.etaMs(bytesTotal - bytesDone), current });
+    const now = Date.now();
+    if (now - lastReport >= 1000) {
+      lastReport = now;
+      deps.report({ filesDone, bytesDone });
+    }
+  };
+  // The current link of every request: "<path>" for a whole file, "<path>#<part index>" for a multipart part.
+  const urls = new Map();
+  for (const i of items) {
+    if ("url" in i) urls.set(i.path, i.url);
+    else i.multipart.partUrls.forEach((u, n) => urls.set(`${i.path}#${n}`, u));
+  }
+  const finished = new Set();
+  // Links last 1 h. The first "expired" 403 renews the links of every unfinished file at once; requests that fail on
+  // the old links meanwhile wait for that same renewal (generation tells them it already happened).
+  let generation = 0;
+  let renewing = null;
+  const renew = (seen) =>
+    seen !== generation
+      ? Promise.resolve()
+      : (renewing ??= (async () => {
+          const paths = items.map((i) => i.path).filter((p) => !finished.has(p));
+          for (let i = 0; i < paths.length; i += 500) {
+            for (const r of await deps.refreshUrls(paths.slice(i, i + 500))) {
+              if ("url" in r) urls.set(r.path, r.url);
+              else r.partUrls.forEach((u, n) => urls.set(`${r.path}#${n}`, u));
+            }
+          }
+          generation++;
+        })().finally(() => (renewing = null)));
+  // One request with retries. A failed try takes its bytes back off the bar, since the retry sends them again.
+  const put = (key, local, start, length, headers) =>
+    withRetry(async () => {
+      const seen = generation;
+      let sent = 0;
+      try {
+        const etag = await putRange(urls.get(key), local.abs, start, length, headers, ctrl.signal, (d) => {
+          sent += d;
+          tick(d);
+        });
+        tick(length - sent);
+        return etag;
+      } catch (e) {
+        tick(-sent);
+        if (!deps.refreshUrls || !(e instanceof TransferError && e.status === 403 && /expired/i.test(e.message))) throw e;
+        await renew(seen);
+        throw new TransferError("The upload link expired; retrying with a new one", 0);
+      }
+    }, ctrl.signal);
+  const headers = (contentType) => (deps.acl ? { "Content-Type": contentType, "x-amz-acl": deps.acl } : { "Content-Type": contentType });
+  // The hash describes the file as it was hashed: never send other bytes under it (e.g. a rebuild mid-upload).
+  const unchanged = async (path, local) => {
+    const st = await fsp.stat(local.abs);
+    if (st.size !== local.size || st.mtimeMs !== local.mtimeMs) throw new TransferError(`${path} changed since it was hashed`, 0, false);
+    current = path;
+  };
+
+  // prepare already created these multipart uploads; any that don't complete must be aborted.
+  const open = new Map(items.filter((i) => i.multipart).map((i) => [i.path, i.multipart.s3UploadId]));
+  try {
+    const jobs = [];
+    for (const item of items) {
+      const local = localByPath.get(item.path);
+      if (!local) throw new Error(`File missing locally: ${item.path}`);
+      if ("url" in item) {
+        jobs.push({
+          size: item.size,
+          run: async () => {
+            await unchanged(item.path, local);
+            await put(item.path, local, 0, item.size, headers(item.contentType));
+            finished.add(item.path);
+            filesDone++;
+            tick(0);
+          },
+        });
+        continue;
+      }
+      const { s3UploadId, partSize, partUrls } = item.multipart;
+      const ranges = partRanges(item.size, partSize, partUrls.length);
+      const parts = new Array(ranges.length);
+      let left = ranges.length;
+      ranges.forEach((r, i) =>
+        jobs.push({
+          size: r.end - r.start + 1,
+          run: async () => {
+            await unchanged(item.path, local);
+            // Parts carry no Content-Type/ACL: those were set when the multipart upload was created.
+            const etag = await put(`${item.path}#${i}`, local, r.start, r.end - r.start + 1, {});
+            if (!etag) throw new TransferError(`S3 returned no ETag for part ${i + 1} of ${item.path}`, 0, false);
+            parts[i] = { PartNumber: i + 1, ETag: etag };
+            if (--left) return;
+            await deps.completeMultipart({ path: item.path, s3UploadId, parts });
+            open.delete(item.path);
+            finished.add(item.path);
+            filesDone++;
+            tick(0);
+          },
+        }),
+      );
+    }
+    await runPool(UPLOAD_AT_ONCE, largestFirst(jobs, SMALL_SLOTS), ctrl);
+  } catch (e) {
+    ctrl.abort();
+    await Promise.all([...open].map(([path, s3UploadId]) => deps.abortMultipart({ path, s3UploadId }).catch(() => {})));
+    throw e;
+  } finally {
+    deps.signal.removeEventListener("abort", cancel);
+  }
+  deps.report({ filesDone, bytesDone });
+}
+
+const sum = (xs) => xs.reduce((n, x) => n + x.size, 0);
+const plural = (n, word) => `${fmtInt(n)} ${word}${n === 1 ? "" : "s"}`;
+
+async function cmdUpload([dir], f) {
+  if (typeof f.project !== "string") throw usage("Pass the project: tars-renderer upload <buildDir> --project <slug or id>");
+  const cfg = needLogin();
+  const root = path.resolve(dir);
+  const st = await fsp.stat(root).catch(() => null);
+  if (!st?.isDirectory()) throw new CliError(`${root} is not a folder. Pass the build folder that \`npx remotion bundle\` created.`);
+
+  const files = await walk(root);
+  const problem = folderProblem(files.map((x) => x.path));
+  if (problem) throw new CliError(problem);
+
+  const version =
+    typeof f.version === "string" ? f.version.trim() : detectRemotionVersion(await fsp.readFile(path.join(root, "bundle.js"), "utf8"));
+  if (!version) throw new CliError("Couldn't find the Remotion version in bundle.js. Pass --version 4.0.x (it's next to remotion in your package.json).");
+  const total = sum(files);
+  info(`${bold(path.basename(root))}: ${plural(files.length, "file")}, ${fmtBytes(total)} · Remotion ${version}${f.version ? " (from --version)" : ""}`);
+
+  // Hash: streaming SHA-256, files the cache already knows are skipped, the rest biggest first so a 1 GB file never
+  // starts last. Hashing finishes before prepare on purpose: the server diffs the whole manifest (that's how it finds
+  // removed files) and the plan is confirmed before anything is sent; at ~1 GB/s it costs seconds, not minutes.
+  const cache = readHashCache();
+  const now = Date.now();
+  const manifest = new Array(files.length);
+  const todo = [];
+  files.forEach((x, i) => {
+    const hit = !f.rehash && cacheHit(cache[x.abs], x);
+    if (hit) cache[x.abs].used = now;
+    if (hit) manifest[i] = { path: x.path, size: x.size, sha256: cache[x.abs].sha256 };
+    else todo.push(i);
+  });
+  todo.sort((a, b) => files[b].size - files[a].size);
+  const toHash = todo.reduce((n, i) => n + files[i].size, 0);
+  let hashedBytes = 0;
+  let hashedFiles = 0;
+  let next = 0;
+  const hashStarted = Date.now();
+  await runPool(
+    HASH_AT_ONCE,
+    () => {
+      if (next >= todo.length) return undefined;
+      const i = todo[next++];
+      const x = files[i];
+      return async () => {
+        const sha256 = await hashFile(x.abs, (n) => {
+          hashedBytes += n;
+          live.update(`Hashing  ${fmtInt(hashedFiles)}/${fmtInt(todo.length)} files  ${fmtBytes(hashedBytes)} / ${fmtBytes(toHash)}`);
+        });
+        manifest[i] = { path: x.path, size: x.size, sha256 };
+        cache[x.abs] = { size: x.size, mtimeMs: x.mtimeMs, ctimeMs: x.ctimeMs, sha256, used: now };
+        hashedFiles++;
+      };
+    },
+    new AbortController(),
+  );
+  live.clear();
+  writeHashCache(cache);
+  info(dim(`  Hashed ${plural(todo.length, "file")} (${fmtBytes(toHash)}) in ${fmtDuration(Date.now() - hashStarted)}; ${fmtInt(files.length - todo.length)} unchanged since the last hash`));
+
+  const prep = await request(cfg, "POST", `/projects/${enc(f.project)}/upload/prepare`, {
+    remotionVersion: version,
+    ...(typeof f.entry === "string" ? { entryHint: f.entry } : {}),
+    files: manifest,
+  });
+  // prepare locks the project; release it if we stop before finishing.
+  let failed = false;
+  const fail = (error) => (failed ? Promise.resolve() : ((failed = true), request(cfg, "POST", `/uploads/${enc(prep.uploadId)}/fail`, { error }).catch(() => {})));
+  onCancel = () => fail("Cancelled before upload");
+
+  const up = { files: prep.toUpload.length, bytes: sum(prep.toUpload) };
+  const same = { files: prep.unchanged.length, bytes: sum(prep.unchanged) };
+  const plan = { project: f.project, remotionVersion: version, toUpload: up, unchanged: same, removed: prep.removed.length };
+  const changed = up.files > 0 || prep.removed.length > 0;
+  info(`  New or changed  ${plural(up.files, "file").padEnd(12)} ${fmtBytes(up.bytes)}`);
+  info(`  Unchanged       ${plural(same.files, "file").padEnd(12)} skipped`);
+  info(`  Removed         ${plural(prep.removed.length, "file")}`);
+
+  if (!changed) info(green("Everything is already uploaded — 0 bytes to send"));
+  else {
+    let ok;
+    try {
+      ok = await confirm(up.files ? `Upload ${plural(up.files, "file")} (${fmtBytes(up.bytes)}) to ${f.project}?` : `Remove ${plural(prep.removed.length, "old file")} from ${f.project}?`, f, { plan });
+    } catch (e) {
+      await fail("Cancelled before upload");
+      throw e;
+    }
+    if (!ok) {
+      await fail("Cancelled before upload");
+      throw new CliError("Cancelled; nothing was uploaded.");
+    }
+  }
+
+  const ctrl = new AbortController();
+  const started = Date.now();
+  const flow = (async () => {
+    try {
+      await uploadAll(prep.toUpload, new Map(files.map((x) => [x.path, x])), {
+        acl: prep.acl,
+        signal: ctrl.signal,
+        completeMultipart: (a) => request(cfg, "POST", `/projects/${enc(f.project)}/upload/complete-multipart`, a),
+        abortMultipart: (a) => request(cfg, "POST", `/projects/${enc(f.project)}/upload/abort-multipart`, a),
+        refreshUrls: async (paths) => (await request(cfg, "POST", `/uploads/${enc(prep.uploadId)}/refresh-urls`, { paths })).items,
+        report: (x) => void request(cfg, "POST", `/uploads/${enc(prep.uploadId)}/progress`, x).catch(() => {}),
+        onProgress: ({ filesDone, bytesDone, speed, etaMs, current }) => {
+          const pct = up.bytes ? Math.floor((bytesDone / up.bytes) * 100) : 100;
+          const rate = speed ? `  ${fmtBytes(speed)}/s` : "";
+          const left = etaMs != null ? `  ${fmtDuration(etaMs)} left` : "";
+          live.update(`Uploading  ${filesDone}/${up.files} files  ${fmtBytes(bytesDone)} / ${fmtBytes(up.bytes)}  ${pct}%${rate}${left}  ${current}`);
+        },
+      });
+      live.clear();
+      if (changed) info("Finishing (reading compositions)…");
+      return await request(cfg, "POST", `/uploads/${enc(prep.uploadId)}/finish`, { files: manifest });
+    } catch (e) {
+      live.clear();
+      const msg = ctrl.signal.aborted ? "Upload cancelled" : e.message;
+      await fail(msg);
+      throw e instanceof CliError ? e : new CliError(`${msg}. Run the same command again to retry: unchanged files, and big files that finished, are skipped.`);
+    }
+  })();
+  onCancel = async () => {
+    ctrl.abort();
+    await flow.catch(() => {});
+  };
+  const fin = await flow;
+  onCancel = null;
+
+  let compositions = [];
+  try {
+    compositions = (await getProject(cfg, f.project)).compositions ?? [];
+  } catch (e) {
+    warn(`Uploaded, but couldn't list the compositions: ${e.message}`);
+  }
+  done({ ...plan, uploadId: prep.uploadId, compositionCount: fin.compositions, compositionsError: fin.compositionsError ?? null, compositions }, () => {
+    say(`${green("✔")} Uploaded to ${bold(f.project)}${changed ? ` in ${fmtDuration(Date.now() - started)}` : ""} · ${plural(fin.compositions, "composition")}`);
+    if (fin.compositionsError) say(yellow(`  Couldn't read compositions: ${fin.compositionsError}`));
+    printComps(compositions);
+    if (compositions[0]) say(dim(`\n  Next: tars-renderer render ${f.project} ${compositions[0].compId} --res 720p --quality draft`));
+  });
+}
+
+// ---------------------------------------------------------------- render, watch, download
+
+const RENDER_FLAGS = ["res=", "quality=", "frames=", "seconds=", "muted", "keep="];
+
+async function estimateFor(cfg, ref, compId, f) {
+  let comp;
+  if (f.seconds !== undefined) {
+    const { compositions } = await getProject(cfg, ref);
+    comp = compositions.find((c) => c.compId === compId);
+    if (!comp) throw new CliError(`No composition "${compId}" in ${ref}. Available: ${compositions.map((c) => c.compId).join(", ") || "none"}`);
+  }
+  const params = buildParams(f, comp);
+  const est = await request(cfg, "POST", "/renders/estimate", { projectRef: ref, compId, params });
+  return { params, est };
+}
+
+function printEstimate(est, ref, compId) {
+  const b = est.budget ?? {};
+  info(`${bold(compId)} in ${ref}`);
+  info(`  Output     ${est.width}×${est.height} · ${fmtInt(est.frames)} frames`);
+  info(`  Estimate   ${bold(fmtUsd(est.estimateUsd))}`);
+  if (b.spentThisMonthUsd !== undefined) {
+    info(`  Budget     ${fmtUsd(b.spentThisMonthUsd)}${b.budgetUsd != null ? ` of ${fmtUsd(b.budgetUsd)}` : ""} spent this month · ${plural(b.activeCount ?? 0, "active render")} of yours`);
+  }
+  if (est.blockedReason) info(red(`  Blocked    ${est.blockedReason}`));
+}
+
+async function cmdEstimate([ref, compId], f) {
+  const cfg = needLogin();
+  const { params, est } = await estimateFor(cfg, ref, compId, f);
+  done({ ...est, params }, () => {
+    printEstimate(est, ref, compId);
+    if (!est.blockedReason) say(dim(`  Render it: tars-renderer render ${ref} ${compId} [same options]`));
+  });
+}
+
+async function cmdRender([ref, compId], f) {
+  const cfg = needLogin();
+  const { params, est } = await estimateFor(cfg, ref, compId, f);
+  printEstimate(est, ref, compId);
+  if (est.blockedReason) throw new CliError(est.blockedReason, EXIT.ERROR, { estimate: est });
+  const big = est.needsConfirm ? yellow(" (above the $5 confirm limit)") : "";
+  if (!(await confirm(`Start this render for ${fmtUsd(est.estimateUsd)}${big}?`, f, { estimate: est, params }))) throw new CliError("Cancelled; nothing was rendered.");
+
+  let id;
+  try {
+    ({ id } = await request(cfg, "POST", "/renders", { projectRef: ref, compId, params, confirmed: true }));
+  } catch (e) {
+    if (e.code !== "confirm_required") throw e;
+    // The server's estimate moved past the confirm limit: ask again.
+    const usd = e.body?.estimateUsd ?? est.estimateUsd;
+    if (!(await confirm(`The server needs confirmation: this render costs ${fmtUsd(usd)}. Start it anyway?`, f, { estimate: { ...est, estimateUsd: usd }, params })))
+      throw new CliError("Cancelled; nothing was rendered.");
+    ({ id } = await request(cfg, "POST", "/renders", { projectRef: ref, compId, params, confirmed: true }));
+  }
+  info(`${green("✔")} Render started: ${bold(id)}`);
+
+  const out = { id, estimate: est, params };
+  if (f.watch || f.download) {
+    out.render = await watchRender(cfg, id);
+    if (f.download) out.download = await downloadRender(cfg, id, f.download === true ? undefined : f.download);
+  }
+  done(out, () => {
+    if (out.download) say(`${green("✔")} Saved ${out.download.path} (${fmtBytes(out.download.bytes)})`);
+    else if (out.render) say(dim(`  Download: tars-renderer download ${id}`));
+    else say(dim(`  Follow it: tars-renderer watch ${id}`));
+  });
+}
+
+/** Polls every 2 s, drawing the chunk strip. Returns the final row when done; throws when it failed. */
+async function watchRender(cfg, id) {
+  let lastKey = "";
+  let misses = 0;
+  for (;;) {
+    let r;
+    try {
+      r = await request(cfg, "GET", `/renders/${enc(id)}`);
+      misses = 0;
+    } catch (e) {
+      if (e instanceof ApiError || ++misses >= 8) throw e;
+      warn(`${e.message} (retrying)`);
+      await sleep(Math.min(30_000, POLL_MS * 2 ** misses)); // back off while the network is down: ~2.5 min in total
+      continue;
+    }
+    const line = progressLine(r);
+    const key = `${r.status}|${Math.floor((r.progress ?? 0) * 100)}`;
+    if (process.stderr.isTTY) live.update(line, true);
+    else if (key !== lastKey) info(line);
+    lastKey = key;
+    if (!ACTIVE.has(r.status)) {
+      live.clear();
+      if (process.stderr.isTTY) info(line);
+      if (r.status === "done") return r;
+      const why = r.status === "failed" ? r.error || "no error message" : `the render is ${r.status}`;
+      throw new CliError(`Render ${r.status}: ${why}`, EXIT.ERROR, { render: r });
+    }
+    await sleep(POLL_MS);
+  }
+}
+
+function describeRender(r) {
+  say(`${bold(idOf(r))}  ${statusColor(r.status)}`);
+  say(`  ${dim("Project ")} ${r.projectName ?? ""}${r.projectSlug ? ` (${r.projectSlug})` : ""} · ${r.compId}`);
+  say(`  ${dim("Output  ")} ${r.preset ?? ""} · ${r.width}×${r.height}${r.outputBytes ? ` · ${fmtBytes(r.outputBytes)}` : ""}`);
+  say(`  ${dim("Progress")} ${progressLine(r)}`);
+  if (r.expiresAt) say(`  ${dim("Expires ")} ${new Date(r.expiresAt).toISOString().slice(0, 16).replace("T", " ")} UTC`);
+  if (r.error) say(`  ${dim("Error   ")} ${red(r.error)}`);
+}
+
+async function cmdStatus([id]) {
+  const cfg = needLogin();
+  const r = await request(cfg, "GET", `/renders/${enc(id)}`);
+  done(r, () => {
+    describeRender(r);
+    if (ACTIVE.has(r.status)) say(dim(`  Follow it: tars-renderer watch ${id}`));
+    if (r.status === "done") say(dim(`  Download: tars-renderer download ${id}`));
+  });
+  return r.status === "failed" ? EXIT.ERROR : EXIT.OK;
+}
+
+async function cmdWatch([id]) {
+  const cfg = needLogin();
+  const r = await watchRender(cfg, id);
+  done(r, () => {
+    say(`${green("✔")} Done in ${fmtDuration(r.finishedAt - r.startedAt)} · ${fmtUsd(r.costUsd)}${r.outputBytes ? ` · ${fmtBytes(r.outputBytes)}` : ""}`);
+    say(dim(`  Download: tars-renderer download ${id}`));
+  });
+}
+
+/**
+ * Downloads a render with up to DOWNLOAD_AT_ONCE ranged GETs written at their offsets into a preallocated `.part` file.
+ * One stream from far away (India -> us-east-1) is capped by a single TCP window; several connections fill the link.
+ * Each range is retried on its own from where it stopped, an expired link is renewed, and a server that ignores
+ * Range gets one plain stream. Checks the size, and the MD5 when the ETag is one (single-PUT objects; multipart
+ * ETags are an MD5 of part MD5s, so those are only size-checked).
+ */
+async function downloadRender(cfg, id, out) {
+  const link = () => request(cfg, "POST", `/renders/${enc(id)}/download-url`, {});
+  let { url, fileName } = await link();
+  const safeName = path.basename(String(fileName || `${id}.mp4`)); // never let the server pick a directory
+  let dest = path.resolve(out ?? safeName);
+  if (out && fs.statSync(dest, { throwIfNoEntry: false })?.isDirectory()) dest = path.join(dest, safeName);
+  // An unpredictable name, created exclusively below: a file or symlink planted at a guessable path is never written through.
+  const tmp = path.join(path.dirname(dest), `.${path.basename(dest)}.${crypto.randomBytes(8).toString("hex")}.part`);
+  const ctrl = new AbortController();
+  const started = Date.now();
+  const meter = rateMeter();
+  let total = 0;
+  let got = 0;
+  const progress = (n) => {
+    got += n;
+    meter.update(got);
+    const eta = meter.etaMs(total - got);
+    const pct = total ? `  ${Math.floor((got / total) * 100)}%` : "";
+    const rate = meter.rate() ? `  ${fmtBytes(meter.rate())}/s` : "";
+    live.update(`Downloading  ${fmtBytes(got)}${total ? ` / ${fmtBytes(total)}` : ""}${pct}${rate}${eta != null ? `  ${fmtDuration(eta)} left` : ""}  ${path.basename(dest)}`);
+  };
+  // A link that expired mid-download (1 h) answers 403: get a new one, once for all the ranges that hit it.
+  let refreshing = null;
+  const renewed = async (used) => {
+    if (url === used) await (refreshing ??= link().then((l) => void (url = l.url)).finally(() => (refreshing = null)));
+    return url !== used;
+  };
+  /** One GET (inclusive `range`, or the whole file); the response body still has to be read with save(). */
+  const get = async (range) => {
+    const req = linked(ctrl.signal);
+    const used = url;
+    const res = await fetch(url, { headers: range ? { Range: `bytes=${range.pos}-${range.end}` } : {}, signal: req.ctrl.signal }).catch((e) => {
+      req.unlink();
+      throw e;
+    });
+    if (res.ok) return { res, req };
+    req.unlink();
+    await res.body?.cancel();
+    if (res.status === 403 && (await renewed(used))) throw new TransferError("The download link expired; retrying with a new one", 0);
+    throw new TransferError(`HTTP ${res.status}`, res.status);
+  };
+  /** Writes a response body at `pos` (positioned writes, so ranges land in any order); returns the next position. */
+  const save = async ({ res, req }, fh, pos) => {
+    const stall = stallTimer(req.ctrl, "data");
+    try {
+      for await (const chunk of res.body) {
+        stall.alive();
+        await fh.write(chunk, 0, chunk.length, pos);
+        pos += chunk.length;
+        progress(chunk.length);
+      }
+      return pos;
+    } finally {
+      stall.stop();
+      req.unlink();
+    }
+  };
+
+  onCancel = async () => {
+    ctrl.abort();
+    await fsp.rm(tmp, { force: true });
+  };
+  const fh = await fsp.open(tmp, "wx", 0o600);
+  let etag = null;
+  let connections = 1;
+  try {
+    const probe = await withRetry(() => get({ pos: 0, end: 0 }), ctrl.signal);
+    total = Number(probe.res.headers.get("content-range")?.split("/")[1]);
+    etag = probe.res.headers.get("etag");
+    if (probe.res.status !== 206 || !Number.isFinite(total)) {
+      // No range support: a 200 is already the whole file; anything else is fetched again in one piece.
+      let whole = probe;
+      if (probe.res.status !== 200) {
+        probe.req.unlink();
+        await probe.res.body?.cancel();
+        whole = await withRetry(() => get(), ctrl.signal);
+      }
+      total = Number(whole.res.headers.get("content-length")) || 0;
+      await save(whole, fh, 0);
+    } else {
+      await probe.res.body?.cancel();
+      probe.req.unlink();
+      connections = total >= 2 * RANGE_BYTES ? DOWNLOAD_AT_ONCE : 1;
+      await fh.truncate(total);
+      const ranges = splitRanges(total, RANGE_BYTES, connections);
+      let next = 0;
+      await runPool(
+        connections,
+        () => {
+          const r = ranges[next++];
+          if (!r) return undefined;
+          return () =>
+            withRetry(async () => {
+              const part = await get(r);
+              if (part.res.status !== 206) {
+                part.req.unlink();
+                await part.res.body?.cancel();
+                throw new TransferError(`Expected part of the file, got HTTP ${part.res.status}`, part.res.status, false);
+              }
+              const tag = part.res.headers.get("etag");
+              if (etag && tag && tag !== etag) {
+                part.req.unlink();
+                await part.res.body?.cancel();
+                throw new TransferError("The file changed during the download", 0, false);
+              }
+              r.pos = await save(part, fh, r.pos);
+              if (r.pos !== r.end + 1) throw new TransferError("The connection closed early", 0); // the retry resumes at r.pos
+            }, ctrl.signal);
+        },
+        ctrl,
+      );
+    }
+    await fh.close();
+    const size = (await fsp.stat(tmp)).size;
+    if (total && size !== total) throw new Error(`got ${fmtBytes(size)} of ${fmtBytes(total)}`);
+    if (/^"[0-9a-f]{32}"$/.test(etag ?? "")) {
+      const md5 = await new Promise((resolve, reject) => {
+        const h = crypto.createHash("md5");
+        fs.createReadStream(tmp, { highWaterMark: 1 << 20 }).on("data", (c) => h.update(c)).on("end", () => resolve(h.digest("hex"))).on("error", reject);
+      });
+      if (`"${md5}"` !== etag) throw new Error("the file doesn't match its checksum (MD5); run the download again");
+    }
+    await fsp.rename(tmp, dest);
+  } catch (e) {
+    await fh.close().catch(() => {});
+    await fsp.rm(tmp, { force: true });
+    throw e instanceof CliError ? e : new CliError(`Download failed: ${e.cause?.code || e.message}`);
+  } finally {
+    onCancel = null;
+    live.clear();
+  }
+  return { path: dest, bytes: got, fileName: safeName, connections, ms: Date.now() - started };
+}
+
+async function cmdDownload([id], f) {
+  const cfg = needLogin();
+  const r = await downloadRender(cfg, id, typeof f.out === "string" ? f.out : undefined);
+  done(r, () => say(`${green("✔")} Saved ${r.path} (${fmtBytes(r.bytes)})`));
+}
+
+async function cmdLink([id]) {
+  const cfg = needLogin();
+  const r = await request(cfg, "POST", `/renders/${enc(id)}/download-url`, { share: true });
+  done(r, () => {
+    say(r.url);
+    info(dim(`Anyone with this link can download ${r.fileName ?? "the file"} for ${fmtDuration((r.expiresIn ?? 86400) * 1000)}.`));
+  });
+}
+
+async function cmdRenders(_, f) {
+  const cfg = needLogin();
+  const q = new URLSearchParams();
+  if (f.mine) q.set("mine", "1");
+  if (typeof f.project === "string") q.set("projectRef", f.project);
+  if (typeof f.status === "string") q.set("status", f.status);
+  if (typeof f.limit === "string") q.set("limit", f.limit);
+  const rows = await request(cfg, "GET", `/renders${q.toString() ? `?${q}` : ""}`);
+  done(rows, () => {
+    if (!rows.length) return say("No renders.");
+    table(rows, [
+      ["ID", (r) => idOf(r)],
+      ["PROJECT", (r) => r.projectSlug || r.projectName],
+      ["COMPOSITION", (r) => r.compId],
+      ["PRESET", (r) => r.preset],
+      ["STATUS", (r) => statusColor(r.status) + (ACTIVE.has(r.status) ? ` ${Math.floor((r.progress ?? 0) * 100)}%` : "")],
+      ["COST", (r) => (r.costUsd ? fmtUsd(r.costUsd) : `~${fmtUsd(r.estimatedCostUsd)}`), "right"],
+      ["SIZE", (r) => (r.outputBytes ? fmtBytes(r.outputBytes) : "—"), "right"],
+      ["STARTED", (r) => when(r.startedAt)],
+      ["BY", (r) => r.userName],
+    ]);
+  });
+}
+
+async function cmdDeleteRender([id], f) {
+  const cfg = needLogin();
+  if (!(await confirm(`Delete render ${bold(id)} and its video file?`, f, { render: id }))) throw new CliError("Cancelled; nothing was deleted.");
+  await request(cfg, "DELETE", `/renders/${enc(id)}`);
+  done({ ok: true }, () => say(`${green("✔")} Deleted render ${id}`));
+}
+
+// ---------------------------------------------------------------- agent guide
+
+const BUILTIN_GUIDE = `# Rendering Remotion videos with tars-renderer
+
+You can upload a Remotion build to Tars Renderer ({{PORTAL_URL}}) and render it in the cloud with the \`tars-renderer\` CLI (install: \`npm i -g tars-renderer\`). Sign-in happens in the user's browser; never ask them for keys or passwords. Always pass \`--json\`: one JSON document goes to stdout, progress to stderr.
+
+Setup (once): \`tars-renderer doctor --json\`. If it exits 4, ask the human to run \`tars-renderer login\` and approve the code in their browser.
+
+Workflow:
+1. \`npx remotion bundle src/index.ts --out-dir build\`
+2. \`tars-renderer projects --json\` (or \`tars-renderer create "<name>" --json\`)
+3. \`tars-renderer upload build --project <slug> --json --yes\`  (only changed files are sent)
+4. \`tars-renderer comps <slug> --json\`
+5. \`tars-renderer estimate <slug> <compId> --res 1080p --quality standard --json\`
+6. Show the human the estimate (\`estimateUsd\`) and get a yes before spending money, then:
+   \`tars-renderer render <slug> <compId> --res 1080p --quality standard --yes --watch --json\`
+7. \`tars-renderer download <renderId> --out out.mp4 --json\`, or \`tars-renderer link <renderId> --json\` for a 24 h share link.
+
+Render flags: --res 360p|720p|1080p|4k, --quality draft|standard|high, --frames 0-299 or --seconds 0-10, --muted, --keep 1-day|3-days|7-days|30-days|forever. Use --res 720p --quality draft for test renders.
+
+Exit codes: 0 ok, 1 error (read "error" in the JSON), 2 bad usage, 3 confirmation needed (re-run with --yes after asking the human), 4 not logged in.
+Never print or log the CLI token (kept in the OS credential store, or ~/.tars-renderer/config.json).
+`;
+
+// ---------------------------------------------------------------- agent skill
+
+/** SKILL.md ships inside this package (cli/skill/SKILL.md), so the skill always matches the CLI version. */
+export function readSkill() {
+  return fs.readFileSync(new URL("./skill/SKILL.md", import.meta.url), "utf8");
+}
+
+/** Where each agent looks for skills: user-wide under ~, or per repo under the current folder (--repo). */
+export function skillTargets(forAgent, project, home = os.homedir(), cwd = process.cwd()) {
+  const base = project ? cwd : home;
+  const all = { claude: path.join(base, ".claude", "skills", "tars-renderer"), codex: path.join(base, ".codex", "skills", "tars-renderer") };
+  if (forAgent === "all") return all;
+  if (!(forAgent in all)) throw usage(`--for must be claude, codex or all, got "${forAgent}"`);
+  return { [forAgent]: all[forAgent] };
+}
+
+async function cmdSkill(_, f) {
+  const action = _[0] ?? "show";
+  if (action === "show") return done({ skill: readSkill() }, (d) => process.stdout.write(d.skill));
+  if (action !== "install") throw usage(`Unknown action "${action}". Use: tars-renderer skill install | show`);
+  const targets = skillTargets(typeof f.for === "string" ? f.for : "all", !!f.repo);
+  const skill = readSkill();
+  const installed = Object.entries(targets).map(([agent, dir]) => {
+    fs.mkdirSync(dir, { recursive: true });
+    const file = path.join(dir, "SKILL.md");
+    fs.writeFileSync(file, skill);
+    return { agent, file };
+  });
+  done({ ok: true, installed }, () => {
+    for (const i of installed) say(`${green("✔")} ${i.agent === "claude" ? "Claude Code" : "Codex"}: ${i.file}`);
+    say(dim("  Start a new agent session, then ask it to render your Remotion project."));
+  });
+}
+
+async function cmdAgentGuide(_, f) {
+  const cfg = loadConfig();
+  const portal = (typeof f.portal === "string" ? f.portal : cfg.portal)?.replace(/\/+$/, "");
+  let text = null;
+  let source = "built-in";
+  if (portal) {
+    try {
+      const res = await fetch(`${portal}/cli/AGENT_GUIDE.md`);
+      const body = await res.text();
+      // The SPA rewrite answers unknown paths with index.html and a 200, so check it isn't HTML.
+      if (res.ok && !/^\s*</.test(body) && !(res.headers.get("content-type") ?? "").includes("text/html")) {
+        text = body;
+        source = `${portal}/cli/AGENT_GUIDE.md`;
+      }
+    } catch {}
+    if (!text) warn(`Couldn't fetch ${portal}/cli/AGENT_GUIDE.md; printing the built-in guide.`);
+  }
+  const guide = (text ?? BUILTIN_GUIDE)
+    .replaceAll("{{LOGIN_COMMAND}}", !portal || portal === DEFAULT_PORTAL ? "tars-renderer login" : `tars-renderer login ${portal}`)
+    .replaceAll("{{PORTAL_URL}}", portal || DEFAULT_PORTAL)
+    .replaceAll("{{API_URL}}", cfg.api || "<https://<deployment>.convex.site>");
+  done({ source, guide }, () => process.stdout.write(guide.endsWith("\n") ? guide : guide + "\n"));
+}
+
+// ---------------------------------------------------------------- command table + main
+
+const COMMANDS = {
+  login: {
+    args: [],
+    optArgs: ["portal"],
+    flags: ["api=", "portal="],
+    usage: "login [portal-url]",
+    summary: "Log in through the browser with a one-time code and save the token",
+    help: `Prints a code and opens the portal's approval page. Check the code matches, click Approve,
+and the token is saved in the OS credential store (macOS Keychain, Windows DPAPI, Linux secret-tool),
+or in ~/.tars-renderer/config.json (mode 0600) when there is none. TARS_RENDERER_TOKEN_STORE=file forces the file.
+
+  [portal-url]     only for another deployment (development, staging); default ${DEFAULT_PORTAL}
+  --api <url>      advanced: the API address, if the portal can't be reached`,
+    examples: ["tars-renderer login"],
+    run: cmdLogin,
+  },
+  logout: {
+    args: [],
+    flags: ["all", "local", "purge"],
+    usage: "logout [--all] [--local] [--purge]",
+    summary: "Sign out (this device, or --all of your devices)",
+    help: `Revokes this device's sign-in on the server and removes it from your OS keychain / config.
+
+  --all     sign out every device and agent on your account (e.g. a lost laptop)
+  --local   only forget the sign-in here, without contacting the server (offline)
+  --purge   also delete ~/.tars-renderer (settings and upload hash cache)`,
+    examples: ["tars-renderer logout", "tars-renderer logout --all", "tars-renderer logout --purge"],
+    run: cmdLogout,
+  },
+  whoami: { args: [], flags: [], usage: "whoami", summary: "Show who you're logged in as", run: cmdWhoami },
+  doctor: {
+    args: [],
+    flags: [],
+    usage: "doctor",
+    summary: "Check Node, config, API reachability, token and allowlist",
+    help: "Exits 0 when everything is fine, 4 when not logged in, 1 otherwise.",
+    run: cmdDoctor,
+  },
+  projects: {
+    args: [],
+    flags: ["mine"],
+    usage: "projects [--mine]",
+    summary: "List projects",
+    help: "  --mine   only projects you own",
+    run: cmdProjects,
+  },
+  create: {
+    args: ["name"],
+    flags: ["keep="],
+    usage: "create <name> [--keep 7-days|30-days|90-days|never]",
+    summary: "Create a project",
+    help: "  --keep   delete the uploaded site after it's unused this long (default: the server's)",
+    examples: ['tars-renderer create "Launch video" --keep 30-days'],
+    run: cmdCreate,
+  },
+  upload: {
+    args: ["buildDir"],
+    flags: ["project=", "entry=", "version=", "yes", "rehash"],
+    usage: "upload <buildDir> --project <ref> [--entry src/index.ts] [--version 4.0.535] [--yes] [--rehash]",
+    summary: "Upload a `npx remotion bundle` build (only changed files are sent)",
+    help: `Checks index.html and bundle.js are at the root, detects the Remotion version from bundle.js,
+hashes every file (SHA-256), shows what changed and asks before uploading. Hashes are cached in
+~/.tars-renderer/hash-cache.json, so files whose size and modified time haven't changed aren't read again.
+
+  --project <ref>   project slug or id (required)
+  --entry <file>    the entry file you bundled, saved with the project
+  --version <v>     Remotion version, when it can't be detected from bundle.js
+  --yes             don't ask before uploading
+  --rehash          ignore the hash cache and read every file again`,
+    examples: ["npx remotion bundle src/index.ts --out-dir build", "tars-renderer upload build --project launch-video --yes"],
+    run: cmdUpload,
+  },
+  comps: { args: ["project"], flags: [], usage: "comps <project>", summary: "List a project's compositions", run: cmdComps },
+  estimate: {
+    args: ["project", "compId"],
+    flags: RENDER_FLAGS,
+    usage: "estimate <project> <compId> [render options]",
+    summary: "Show the cost, output size and frame count of a render",
+    help: "Takes the same render options as `render` (see tars-renderer render --help).",
+    run: cmdEstimate,
+  },
+  render: {
+    args: ["project", "compId"],
+    flags: [...RENDER_FLAGS, "yes", "watch", "download?"],
+    usage: "render <project> <compId> [options] [--yes] [--watch] [--download [path]]",
+    summary: "Start a render (shows the estimate and asks first)",
+    help: `  --res 360p|720p|1080p|4k                     output height (default 1080p)
+  --quality draft|standard|high                 default standard
+  --frames 0-299 | --seconds 0-10               render part of the composition
+  --muted                                       no audio
+  --keep 1-day|3-days|7-days|30-days|forever    how long the video is kept (default 7-days)
+  --yes                                         don't ask (with --json, without it exits 3)
+  --watch                                       follow progress until done
+  --download [path]                             watch, then download the video`,
+    examples: ["tars-renderer render launch-video Main --res 720p --quality draft --seconds 0-10", "tars-renderer render launch-video Main --yes --download out.mp4"],
+    run: cmdRender,
+  },
+  renders: {
+    args: [],
+    flags: ["mine", "project=", "status=", "limit="],
+    usage: "renders [--mine] [--project <ref>] [--status queued|rendering|done|failed|expired] [--limit n]",
+    summary: "List renders",
+    run: cmdRenders,
+  },
+  status: { args: ["renderId"], flags: [], usage: "status <renderId>", summary: "Show a render's current state once", run: cmdStatus },
+  watch: {
+    args: ["renderId"],
+    flags: [],
+    usage: "watch <renderId>",
+    summary: "Follow a render live until it's done (exit 0) or failed (exit 1)",
+    run: cmdWatch,
+  },
+  download: {
+    args: ["renderId"],
+    flags: ["out="],
+    usage: "download <renderId> [--out <path>]",
+    summary: "Download a finished render (default: its file name, in this folder)",
+    run: cmdDownload,
+  },
+  link: { args: ["renderId"], flags: [], usage: "link <renderId>", summary: "Print a 24-hour share link", run: cmdLink },
+  "delete-render": { args: ["renderId"], flags: ["yes"], usage: "delete-render <renderId> [--yes]", summary: "Delete a render and its video", run: cmdDeleteRender },
+  "delete-project": {
+    args: ["ref"],
+    flags: ["yes"],
+    usage: "delete-project <ref> [--yes]",
+    summary: "Delete a project and its uploaded files",
+    run: cmdDeleteProject,
+  },
+  skill: {
+    args: [],
+    optArgs: ["action"],
+    flags: ["for=", "repo"],
+    usage: "skill [install|show] [--for claude|codex|all] [--repo]",
+    summary: "Add the Tars Renderer skill to Claude Code / Codex",
+    help: `Installs the agent skill, so your coding agent knows how to use Tars Renderer in every session.
+
+  install          write SKILL.md for your agents (default: Claude Code and Codex)
+  show             print the skill (default)
+  --for <agent>    claude, codex or all (default all)
+  --repo           install into this repo (.claude/skills, .codex/skills) instead of your home folder`,
+    examples: ["npx tars-renderer skill install", "tars-renderer skill install --for claude --repo"],
+    run: cmdSkill,
+  },
+  "agent-guide": {
+    args: [],
+    flags: ["portal="],
+    usage: "agent-guide",
+    summary: "Print instructions for AI coding agents",
+    run: cmdAgentGuide,
+  },
+};
+
+function mainHelp() {
+  const w = Math.max(...Object.keys(COMMANDS).map((k) => k.length));
+  return `tars-renderer ${VERSION}: render Remotion videos on Tars Renderer
+
+Usage: tars-renderer <command> [options]
+
+Commands:
+${Object.entries(COMMANDS)
+  .map(([k, c]) => `  ${k.padEnd(w)}  ${c.summary}`)
+  .join("\n")}
+
+Options for every command:
+  --json   print one JSON document on stdout; progress and logs go to stderr
+  --help   help for a command (tars-renderer <command> --help)
+
+Exit codes: 0 ok · 1 error · 2 bad usage · 3 confirmation needed · 4 not logged in
+Config: ~/.tars-renderer/config.json (override with TARS_RENDERER_API and TARS_RENDERER_TOKEN)
+`;
+}
+
+function commandHelp(name) {
+  const c = COMMANDS[name];
+  return [`Usage: tars-renderer ${c.usage}`, `\n${c.summary}.`, c.help && `\n${c.help}`, c.examples && `\nExamples:\n${c.examples.map((e) => `  ${e}`).join("\n")}`]
+    .filter(Boolean)
+    .join("\n") + "\n";
+}
+
+function checkUsage(c, { _, flags }) {
+  const defs = new Map(c.flags.map((d) => [d.replace(/[=?]$/, ""), d]));
+  for (const [k, v] of Object.entries(flags)) {
+    if (k === "json" || k === "help") continue;
+    const d = defs.get(k);
+    if (!d) throw usage(`Unknown option --${k}`);
+    if (d.endsWith("=") && typeof v !== "string") throw usage(`--${k} needs a value`);
+  }
+  if (_.length < c.args.length) throw usage(`Missing <${c.args[_.length]}>`);
+  if (_.length > c.args.length + (c.optArgs?.length ?? 0)) throw usage(`Unexpected argument "${_[c.args.length]}"`);
+}
+
+/** Runs the CLI; resolves with the exit code. */
+/** Masks anything token-shaped. Applied to every byte the CLI writes, so no code path (or server message) can leak one. */
+export const redactTokens = (s) => s.replace(/\btrp_[A-Za-z0-9_-]{8,}/g, (t) => maskToken(t));
+
+function redactOutput() {
+  for (const stream of [process.stdout, process.stderr]) {
+    if (stream.__redacted) continue;
+    const write = stream.write.bind(stream);
+    stream.write = (chunk, ...rest) => write(typeof chunk === "string" ? redactTokens(chunk) : Buffer.isBuffer(chunk) ? redactTokens(chunk.toString("utf8")) : chunk, ...rest);
+    stream.__redacted = true;
+  }
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  redactOutput();
+  migrateLegacyConfigDir();
+  let name;
+  try {
+    const parsed = parseArgs(argv);
+    ctx.json = !!parsed.flags.json;
+    name = parsed._.shift();
+    if (!name || name === "help") {
+      if (!name && parsed.flags.version === true) {
+        process.stdout.write(VERSION + "\n");
+        return EXIT.OK;
+      }
+      const topic = parsed._[0];
+      process.stdout.write(topic && COMMANDS[topic] ? commandHelp(topic) : mainHelp());
+      return name || parsed.flags.help ? EXIT.OK : EXIT.USAGE;
+    }
+    const cmd = COMMANDS[name];
+    if (!cmd) throw usage(`Unknown command "${name}". Run tars-renderer --help for the list.`);
+    if (parsed.flags.help) {
+      process.stdout.write(commandHelp(name));
+      return EXIT.OK;
+    }
+    checkUsage(cmd, parsed);
+    const code = (await cmd.run(parsed._, parsed.flags)) ?? EXIT.OK;
+    if (code === EXIT.OK) migrateToken();
+    return code;
+  } catch (e) {
+    live.clear();
+    const exitCode = e instanceof CliError ? e.exitCode : EXIT.ERROR;
+    const message = e?.message || String(e);
+    if (ctx.json) process.stdout.write(JSON.stringify({ ok: false, error: message, ...(e?.code ? { code: e.code } : {}), exitCode, ...e?.extra }, null, 2) + "\n");
+    process.stderr.write(`${red("Error:")} ${message}\n`);
+    if (exitCode === EXIT.USAGE && name && COMMANDS[name]) process.stderr.write(dim(`Usage: tars-renderer ${COMMANDS[name].usage}\n`));
+    if (!(e instanceof CliError) && process.env.DEBUG) process.stderr.write(`${e?.stack}\n`);
+    return exitCode;
+  }
+}
+
+const isEntry = (() => {
+  try {
+    const a = fs.realpathSync(fileURLToPath(import.meta.url));
+    const b = fs.realpathSync(process.argv[1] ?? "");
+    return process.platform === "win32" ? a.toLowerCase() === b.toLowerCase() : a === b;
+  } catch {
+    return false;
+  }
+})();
+if (isEntry) {
+  process.on("SIGINT", interrupt);
+  main().then((code) => (process.exitCode = code));
+}