@hostr/cli 0.1.4 → 0.2.0

package/README.md

@@ -5,10 +5,12 @@ infrastructure: resumable upload → transcode → HLS delivery with signed
 playback URLs.
 
 ```bash
-npx @hostr/cli login          # paste an API key from your hostr dashboard
-npx @hostr/cli init           # write the integration guide + env template into your repo
+npx @hostr/cli                 # setup status and the next command to run
+npx @hostr/cli login           # opens a browser for a human to approve — no key to paste, ever
+npx @hostr/cli init            # write the integration guide + env template into your repo
+npx @hostr/cli keys create --name "app dev" --write-env .env.local
 npx @hostr/cli upload demo.mp4 --wait --json
-npx @hostr/cli webhooks set https://yourapp.example/hostr-webhook
+npx @hostr/cli webhooks set https://yourapp.example/hostr-webhook --write-env .env.local
 npx @hostr/cli tail --follow
 ```
 

package/dist/cli.js

@@ -3515,10 +3515,10 @@ var init_client = __esm({
     ApiError2 = class extends Error {
       status;
       code;
-      constructor(status, code) {
-        super(code ? `hostr api error ${status}: ${code}` : `hostr api error ${status}`);
+      constructor(status2, code) {
+        super(code ? `hostr api error ${status2}: ${code}` : `hostr api error ${status2}`);
         this.name = "ApiError";
-        this.status = status;
+        this.status = status2;
         this.code = code;
       }
     };
@@ -3570,13 +3570,13 @@ __export(gui_exports, {
 });
 import { createServer } from "node:http";
 import { randomBytes } from "node:crypto";
-import { spawn } from "node:child_process";
+import { spawn as spawn2 } from "node:child_process";
 async function uploadGui(ctx) {
   const secret = Array.from(randomBytes(16), (b) => b.toString(16).padStart(2, "0")).join("");
   const server = createServer(async (req2, res) => {
     const url = new URL(req2.url ?? "/", "http://localhost");
-    const send = (status, body, type = "application/json") => {
-      res.writeHead(status, { "content-type": type, "cache-control": "no-store" });
+    const send = (status2, body, type = "application/json") => {
+      res.writeHead(status2, { "content-type": type, "cache-control": "no-store" });
       res.end(body);
     };
     try {
@@ -3637,7 +3637,7 @@ async function uploadGui(ctx) {
 (drop a video in the browser; Ctrl+C here when done)
 `);
   const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
-  spawn(opener, [addr], { stdio: "ignore", detached: true }).unref();
+  spawn2(opener, [addr], { stdio: "ignore", detached: true }).unref();
   await new Promise(() => {
   });
 }
@@ -3786,7 +3786,7 @@ async function go(file) {
     const t = await local('/api/playback/' + assetId, { method: 'POST' });
     const mediaHost = API.replace('api.', 'stream.');
     if (t.unavailable) {
-      st.innerHTML = 'ready \u2014 asset <span class="mono">' + assetId + '</span><br><span class="hint">key lacks full scope, so no preview token \u2014 mint one server-side to play</span>';
+      st.innerHTML = 'ready \u2014 asset <span class="mono">' + assetId + '</span><br><span class="hint">key lacks playback scope, so no preview token \u2014 mint one server-side to play</span>';
       return;
     }
     const src = mediaHost + '/' + assetId + '.m3u8?token=' + encodeURIComponent(t.playback);
@@ -3834,6 +3834,7 @@ import { mkdir, readFile, writeFile, chmod } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
 var DEFAULT_API_BASE = "https://api.hostr.sh";
+var CLI_VERSION = "0.2.0";
 var configDir = (env = process.env) => env.HOSTR_CONFIG_DIR ?? join(homedir(), ".config", "hostr");
 async function loadConfig(dir = configDir()) {
   try {
@@ -3866,10 +3867,10 @@ function resolveAuth(opts) {
 var ApiError = class extends Error {
   status;
   body;
-  constructor(status, body) {
-    const msg = body?.error ?? `http_${status}`;
-    super(`API error ${status}: ${msg}`);
-    this.status = status;
+  constructor(status2, body) {
+    const msg = body?.error ?? `http_${status2}`;
+    super(`API error ${status2}: ${msg}`);
+    this.status = status2;
     this.body = body;
   }
 };
@@ -3918,6 +3919,30 @@ function makeClient(opts) {
     webhookDelete: () => req2("DELETE", "/v1/webhooks")
   };
 }
+function makeDeviceClient(opts) {
+  const doFetch = opts.fetchFn ?? fetch;
+  const base = opts.apiBase.replace(/\/$/, "");
+  const post = async (path, body) => {
+    const res = await doFetch(`${base}${path}`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body)
+    });
+    return { status: res.status, body: await res.json().catch(() => ({})) };
+  };
+  return {
+    async start(b) {
+      const r = await post("/v1/device/code", b);
+      if (r.status !== 201) throw new ApiError(r.status, r.body);
+      return r.body;
+    },
+    async poll(deviceCode) {
+      const r = await post("/v1/device/token", { deviceCode });
+      if (r.status === 200) return { ok: true, value: r.body };
+      return { ok: false, error: String(r.body.error ?? `http_${r.status}`) };
+    }
+  };
+}
 
 // src/context.ts
 var makeOut = (json) => ({
@@ -3947,7 +3972,7 @@ function fail(out, e) {
 }
 
 // src/commands-account.ts
-import { createInterface } from "node:readline/promises";
+import { hostname } from "node:os";
 
 // ../control/src/fmt.ts
 function fmtBytes(n) {
@@ -3978,26 +4003,132 @@ function table(rows, cols) {
   ].join("\n");
 }
 
+// src/device.ts
+import { spawn } from "node:child_process";
+function pollAction(errorCode) {
+  switch (errorCode) {
+    case "authorization_pending":
+      return { kind: "wait", addSec: 0 };
+    case "slow_down":
+      return { kind: "wait", addSec: 5 };
+    case "access_denied":
+      return { kind: "stop", error: "authorization was denied in the browser" };
+    case "expired_token":
+      return { kind: "stop", error: "the code expired \u2014 run `hostr login` again" };
+    default:
+      return { kind: "stop", error: `unexpected device-flow error: ${errorCode}` };
+  }
+}
+async function awaitApproval(o) {
+  const deadline = o.now() + o.expiresInSec * 1e3;
+  let interval = o.intervalSec;
+  for (; ; ) {
+    const reply = await o.poll();
+    if (reply.ok) return reply.value;
+    const action = pollAction(reply.error);
+    if (action.kind === "stop") throw new Error(action.error);
+    interval += action.addSec;
+    if (o.now() + interval * 1e3 > deadline)
+      throw new Error("the code expired before it was approved \u2014 run `hostr login` again");
+    await o.sleep(interval * 1e3);
+  }
+}
+var openBrowser = (addr) => {
+  const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+  try {
+    spawn(opener, [addr], { stdio: "ignore", detached: true }).unref();
+  } catch {
+  }
+};
+
+// src/env-file.ts
+import { chmod as chmod2, readFile as readFile2, writeFile as writeFile2 } from "node:fs/promises";
+import { basename } from "node:path";
+var readOrNull = (p) => readFile2(p, "utf8").catch(() => null);
+function upsertEnvLine(existing, name, value) {
+  const line = `${name}=${value}`;
+  if (existing === null || existing.trim() === "") return `${line}
+`;
+  const eol = existing.includes("\r\n") ? "\r\n" : "\n";
+  const lines = existing.split("\n");
+  const i = lines.findIndex((l) => l.trimStart().startsWith(`${name}=`));
+  if (i === -1) {
+    const body = existing.replace(/[\r\n]*$/, "");
+    return `${body}${eol}${line}${eol}`;
+  }
+  const hadCR = lines[i].endsWith("\r");
+  lines[i] = hadCR ? `${line}\r` : line;
+  return lines.join("\n");
+}
+var patternCovers = (pattern, candidates) => {
+  const body = pattern.replace(/^\//, "");
+  const re = new RegExp(
+    "^" + body.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, "[^/]*") + "$"
+  );
+  return candidates.some((c) => re.test(c));
+};
+function gitignoreCovers(gitignore, file) {
+  if (gitignore === null) return false;
+  const candidates = [file.replace(/^\.\//, ""), basename(file)];
+  return gitignore.split("\n").map((l) => l.trim()).filter((l) => l !== "" && !l.startsWith("#") && !l.startsWith("!")).some((l) => patternCovers(l, candidates));
+}
+async function isGitignored(file) {
+  return gitignoreCovers(await readOrNull(".gitignore"), file);
+}
+async function writeEnvVar(file, name, value) {
+  const next = upsertEnvLine(await readOrNull(file), name, value);
+  await writeFile2(file, next, { mode: 384 });
+  await chmod2(file, 384);
+  return { gitignored: await isGitignored(file) };
+}
+
 // src/commands-account.ts
 async function login(opts) {
   const out = makeOut(!!opts.json);
-  let key = opts.key ?? process.env.HOSTR_API_KEY;
-  if (!key) {
-    const rl = createInterface({ input: process.stdin, output: process.stderr });
-    key = (await rl.question("API key (from your hostr dashboard or `hostr keys create`): ")).trim();
-    rl.close();
-  }
-  if (!key) fail(out, new Error("an API key is required"));
   const cfg = await loadConfig(configDir());
   const apiBase = resolveAuth({ flagApi: opts.api, env: process.env, profile: activeProfile(cfg) }).apiBase;
-  const client = makeClient({ apiBase, key });
+  const name = opts.profile ?? "default";
+  const explicit = opts.key ?? process.env.HOSTR_API_KEY;
+  if (explicit) {
+    try {
+      const acct = await makeClient({ apiBase, key: explicit }).account();
+      await saveConfig(setProfile(cfg, name, { key: explicit, apiBase }), configDir());
+      out.print(
+        `logged in to ${acct.name} (plan: ${acct.plan}) as profile "${name}"`,
+        { ok: true, accountId: acct.accountId, name: acct.name, plan: acct.plan, profile: name }
+      );
+    } catch (e) {
+      fail(out, e);
+    }
+    return;
+  }
+  const dev = makeDeviceClient({ apiBase });
   try {
-    const acct = await client.account();
-    const name = opts.profile ?? "default";
-    await saveConfig(setProfile(cfg, name, { key, apiBase }), configDir());
+    const start = await dev.start({ client: `hostr-cli/${CLI_VERSION}`, hostname: hostname() });
+    process.stderr.write(
+      `
+  Your code: ${start.userCode}
+  Approve at: ${start.verificationUriComplete}
+
+  Opening your browser\u2026 waiting for approval.
+  (If you are an agent: hand this URL and code to your human. Do not
+   ask them to paste an API key.)
+
+`
+    );
+    openBrowser(start.verificationUriComplete);
+    const res = await awaitApproval({
+      poll: () => dev.poll(start.deviceCode),
+      sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+      intervalSec: start.interval,
+      expiresInSec: start.expiresIn,
+      now: () => Date.now()
+    });
+    await saveConfig(setProfile(cfg, name, { key: res.key, apiBase }), configDir());
     out.print(
-      `logged in to ${acct.name} (plan: ${acct.plan}) as profile "${name}"`,
-      { ok: true, accountId: acct.accountId, name: acct.name, plan: acct.plan, profile: name }
+      `authorized \u2014 ${res.accountName} (plan: ${res.plan}) as profile "${name}"
+key stored in ${configDir()}/config.json; revoke it on the Keys page any time`,
+      { ok: true, accountId: res.accountId, name: res.accountName, plan: res.plan, profile: name }
     );
   } catch (e) {
     fail(out, e);
@@ -4048,9 +4179,31 @@ async function keysList(ctx) {
     { items }
   );
 }
+var parseScopes = (csv) => {
+  const parts = (csv ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+  return parts.length ? parts : ["playback"];
+};
 async function keysCreate(ctx, opts) {
-  const scopes = opts.scopes?.split(",").map((s) => s.trim());
-  const k = await ctx.client.keysCreate({ ...opts.name ? { name: opts.name } : {}, ...scopes ? { scopes } : {} });
+  const scopes = parseScopes(opts.scopes);
+  const k = await ctx.client.keysCreate({ ...opts.name ? { name: opts.name } : {}, scopes });
+  if (opts.writeEnv) {
+    let gitignored;
+    try {
+      ({ gitignored } = await writeEnvVar(opts.writeEnv, "HOSTR_API_KEY", k.key));
+    } catch (e) {
+      throw new Error(
+        `key ${k.id} was created, but writing it to ${opts.writeEnv} failed: ${e?.message ?? e}. It is live with nobody holding it \u2014 run \`npx hostr keys list\` and \`npx hostr keys revoke ${k.id}\` to clean it up.`
+      );
+    }
+    ctx.out.print(
+      `wrote HOSTR_API_KEY to ${opts.writeEnv} (value not shown)
+id       ${k.id}
+scopes   ${k.scopes.join(",")}` + (gitignored ? "" : `
+WARNING: ${opts.writeEnv} does not look gitignored \u2014 do not commit it.`),
+      { ok: true, wrote: "HOSTR_API_KEY", file: opts.writeEnv, id: k.id, scopes: k.scopes, gitignored }
+    );
+    return;
+  }
   ctx.out.print(
     `key      ${k.key}
 id       ${k.id}
@@ -4071,6 +4224,33 @@ created  ${fmtWhen(w.createdAt)}`, w);
 }
 async function webhooksSet(ctx, url, opts) {
   const w = await ctx.client.webhookSet({ url, ...opts.secret ? { secret: opts.secret } : {} });
+  if (opts.writeEnv && w.secret) {
+    let gitignored;
+    try {
+      ({ gitignored } = await writeEnvVar(opts.writeEnv, "HOSTR_WEBHOOK_SECRET", w.secret));
+    } catch (e) {
+      throw new Error(
+        `webhook secret for ${w.url} was set, but writing it to ${opts.writeEnv} failed: ${e?.message ?? e}. Nobody has a copy \u2014 re-run \`npx hostr webhooks set ${url}\` to mint a fresh one, and confirm the write succeeds this time.`
+      );
+    }
+    ctx.out.print(
+      `url      ${w.url}
+enabled  ${w.enabled}
+wrote HOSTR_WEBHOOK_SECRET to ${opts.writeEnv} (value not shown)` + (gitignored ? "" : `
+WARNING: ${opts.writeEnv} does not look gitignored \u2014 do not commit it.`),
+      { ok: true, url: w.url, enabled: w.enabled, wrote: "HOSTR_WEBHOOK_SECRET", file: opts.writeEnv, gitignored }
+    );
+    return;
+  }
+  if (opts.writeEnv && !w.secret) {
+    ctx.out.print(
+      `url      ${w.url}
+enabled  ${w.enabled}
+nothing written to ${opts.writeEnv} \u2014 you supplied --secret, so the server returned none.`,
+      { ok: true, url: w.url, enabled: w.enabled, wrote: null, file: opts.writeEnv }
+    );
+    return;
+  }
   ctx.out.print(
     `url      ${w.url}
 enabled  ${w.enabled}` + (w.secret ? `
@@ -4094,11 +4274,11 @@ async function webhooksTest(ctx) {
 }
 
 // src/commands-media.ts
-import { basename } from "node:path";
+import { basename as basename2 } from "node:path";
 import { stat } from "node:fs/promises";
 
 // ../upload/src/node/index.ts
-import { open, mkdir as mkdir2, readFile as readFile2, writeFile as writeFile2, unlink } from "node:fs/promises";
+import { open, mkdir as mkdir2, readFile as readFile3, writeFile as writeFile3, unlink } from "node:fs/promises";
 import { join as join2 } from "node:path";
 import { tmpdir } from "node:os";
 
@@ -4135,9 +4315,9 @@ function classifyPut(res, err) {
   if (err instanceof NetworkError) return "network";
   if (err != null) return "fatal";
   if (res === null) return "network";
-  const { status } = res;
-  if (status === 403) return "expired";
-  if (status === 429 || status >= 500 && status < 600) return "transient";
+  const { status: status2 } = res;
+  if (status2 === 403) return "expired";
+  if (status2 === 429 || status2 >= 500 && status2 < 600) return "transient";
   return "fatal";
 }
 function classifyApi(err) {
@@ -5045,7 +5225,7 @@ function fileStateStore(dir) {
   return {
     async get(key) {
       try {
-        return await readFile2(fileFor(key), "utf8");
+        return await readFile3(fileFor(key), "utf8");
       } catch (err) {
         if (err?.code === "ENOENT") return null;
         throw err;
@@ -5053,7 +5233,7 @@ function fileStateStore(dir) {
     },
     async set(key, value) {
       await mkdir2(dir, { recursive: true });
-      await writeFile2(fileFor(key), value, "utf8");
+      await writeFile3(fileFor(key), value, "utf8");
     },
     async delete(key) {
       try {
@@ -5190,8 +5370,8 @@ async function subtitlesList(ctx, id) {
   );
 }
 async function subtitlesSet(ctx, id, file, opts) {
-  const { readFile: readFile4 } = await import("node:fs/promises");
-  const vtt = await readFile4(file, "utf8");
+  const { readFile: readFile6 } = await import("node:fs/promises");
+  const vtt = await readFile6(file, "utf8");
   const r = await ctx.client.subtitleSet(id, opts.lang, vtt, { name: opts.name, default: opts.default });
   ctx.out.print(`subtitle ${r.lang} ("${r.name}") attached to ${r.assetId}${r.default ? " as default" : ""}`, r);
 }
@@ -5222,7 +5402,7 @@ async function upload(ctx, file, opts) {
   const session = await createUploadSession({
     endpoint: ctx.apiBase,
     apiKey,
-    filename: basename(file),
+    filename: basename2(file),
     contentType: opts.contentType ?? mimeOf(file),
     size
   });
@@ -5237,7 +5417,7 @@ async function upload(ctx, file, opts) {
   const isTty = process.stderr.isTTY;
   up.on("progress", (p) => {
     const pct = p.totalBytes ? Math.floor(p.bytesConfirmed / p.totalBytes * 100) : 0;
-    const line = `uploading ${basename(file)}  ${pct}%  (${p.partsDone}/${p.partsTotal} parts)`;
+    const line = `uploading ${basename2(file)}  ${pct}%  (${p.partsDone}/${p.partsTotal} parts)`;
     if (isTty) process.stderr.write(`\r${line}   `);
   });
   up.start();
@@ -5263,11 +5443,11 @@ size     ${fmtBytes(size)}`,
 }
 
 // src/commands-init.ts
-import { mkdir as mkdir3, readFile as readFile3, writeFile as writeFile3 } from "node:fs/promises";
+import { mkdir as mkdir3, readFile as readFile4, writeFile as writeFile4 } from "node:fs/promises";
 import { join as join3 } from "node:path";
 
 // ../../docs/integrate.md
-var integrate_default = '# hostr \u2014 integration guide\n\nhostr is self-hosted video infrastructure: resumable upload \u2192 transcode \u2192\nHLS delivery, with signed playback URLs. This document is the complete,\nself-contained integration reference. It is written to be executed by a\ncoding agent; every command has a `--json` mode and every flow is\nverifiable from the terminal.\n\n```\nAPI base    https://api.hostr.sh                         (override: HOSTR_API_BASE)\nMedia host  https://stream.hostr.sh                 (playback URLs are built on this)\nDocs        GET {API base}/llms.txt  \xB7  GET {API base}/llms-full.txt (this file)\n```\n\n## 0. TL;DR for an integrating agent\n\n```bash\nnpx @hostr/cli login --key $HOSTR_API_KEY   # validate + save the key (or export HOSTR_API_KEY)\nnpx @hostr/cli init                          # write docs/hostr.md + AGENTS.md section + .env.example entries\nnpx @hostr/cli upload demo.mp4 --wait --json # -> { assetId, status: "ready", ... }\nnpx @hostr/cli upload                        # no file: opens a local drag-drop page in the browser\nnpx @hostr/cli webhooks set https://yourapp.example/hostr-webhook --json  # -> { secret: "whsec_..." } ONCE\nnpx @hostr/cli tail --follow                 # watch the event log live\n```\n\nThen in your app: store `assetId`/`playbackId` per video, mint playback\ntokens server-side (\xA76), and hand players\n`{Media host}/{playbackId}.m3u8?token=\u2026`. Verify webhooks with the snippet\nin \xA75. That is the whole integration.\n\n## 1. Authentication\n\nEvery API call sends `Authorization: Bearer <credential>`. There are two\ncredential kinds an integrator sees:\n\n- **API key** \u2014 `hostr_sk_live_\u2026`, minted per account in the hostr\n  dashboard or via `POST /v1/keys` / `npx @hostr/cli keys create`. Scoped:\n  - `read` \u2014 GETs only (status, listing, usage, events)\n  - `upload` \u2014 read + the upload lifecycle\n  - `full` \u2014 everything, including playback-token minting and key management\n  Keys are hashed at rest; the plaintext is shown exactly once at mint.\n  Rotation = create new + revoke old (`DELETE /v1/keys/:id`); revocation\n  takes effect within ~60 s. **Keep keys server-side.** Never ship one in a\n  browser or mobile app.\n- **Upload token** \u2014 short-lived HMAC scoped to a single upload\n  (`uploadToken` in the create-upload response). This is the only\n  credential an untrusted client (browser/mobile) should ever hold: it can\n  drive that one upload and nothing else.\n\nAuth errors: `401 {"error":"unauthorized"}` (bad/missing/revoked key, or a\nresource you don\'t own \u2014 hostr does not reveal which),\n`403 {"error":"insufficient_scope","need":"upload"}`,\n`403 {"error":"account_suspended"}`,\n`503 {"error":"control_plane_unavailable"}` (transient \u2014 retry with backoff;\nin-flight uploads with upload tokens are unaffected).\n\n## 2. Upload\n\nThree ways, strongest first:\n\n### 2a. CLI (recommended \u2014 resumable, integrity-checked)\n\n```bash\nnpx @hostr/cli upload path/to/video.mp4 --json           # returns when bytes are verified in R2\nnpx @hostr/cli upload path/to/video.mp4 --wait --json    # returns when transcode is ready/failed\n```\n\nOutput: `{ "assetId": "\u2026", "status": "queued"|"ready", "bytes": n, "etag": "\u2026", "sha256": "\u2026" }`.\nThe CLI wraps hostr\'s upload SDK: chunked multipart direct to storage,\nresume after crash/restart (server-authoritative \u2014 it asks storage which\nparts landed), retry with backoff, and three-layer integrity verification.\nExit code 1 + JSON on stderr on failure.\n\n### 2b. Raw HTTP (any language, no SDK)\n\n```\nPOST /v1/uploads                     {"filename":"a.mp4","size":<bytes>,"contentType":"video/mp4"}\n  -> 201 { assetId, partSize, expectedParts, uploadToken, tokenExpiresAt, key, uploadId }\n     (forward ONLY assetId/uploadToken/partSize/expectedParts/tokenExpiresAt to untrusted clients)\n\nPOST /v1/uploads/:id/parts           {"partNumbers":[1,2,...]}        (\u2264100 per call)\n  -> { urls: [{partNumber, url}], expiresIn }\nPUT  <each presigned url>            body = that part\'s bytes; capture the ETag response header\n\nGET  /v1/uploads/:id                 -> { status, uploadedParts, parts, bytesUploaded }   (resume)\nPOST /v1/uploads/:id/complete        {"sha256":"<hex of whole file>"}  (sha256 optional)\n  -> { assetId, status: "uploaded"|"queued", bytes, etag }\nDELETE /v1/uploads/:id               abort\nPOST /v1/uploads/:id/token           re-mint the upload token (API key with upload scope)\n```\n\nRules: every part is `partSize` bytes except the last; `size` must be\nexact \u2014 completion verifies both part count and total bytes against what\nactually landed and returns `409 incomplete_upload` (with the missing part\nnumbers) or `409 size_mismatch` otherwise. Completion is idempotent \u2014 a\ncrashed client retries it safely. Uploads are quota-gated:\n`403 {"error":"quota_uploads_daily"|"quota_assets"|"quota_storage","limit":n}`.\n\n### 2c. Browser/mobile clients\n\nCreate the upload server-side (2b), hand the client only\n`{assetId, uploadToken, partSize, expectedParts}`, and let it PUT parts\ndirectly to the presigned URLs \u2014 upload bytes never touch your servers.\n(A browser needs the storage bucket to allow your origin via CORS \u2014 if\npart PUTs stall at 0% with network-looking errors, that\'s the cause.)\n\n## 3. Asset lifecycle\n\n`uploading \u2192 uploaded \u2192 queued \u2192 processing \u2192 ready | failed` (plus\n`aborted`). Poll `GET /v1/assets/:id` (`read` scope) or \u2014 better \u2014 use\nwebhooks (\xA75). While `processing`, the asset carries live transcode\nprogress \u2014 `progress: { encodedSec, totalSec, speed }` (speed is the\nencode multiple of realtime; the field is null/absent outside\n`processing`) \u2014 so a UI can show a real percentage instead of a spinner. `GET /v1/assets?limit=&status=&cursor=` lists your assets\nnewest-first with keyset pagination (`nextCursor`).\n\nWhen `ready`, the asset record and the `video.ready` event both carry\n`playbackId` (equals `assetId` today \u2014 store it as its own field) and\n`durationSec`.\n\n## 4. Account, usage, keys\n\n```\nGET  /v1/account        -> { accountId, name, plan, limits, usage }      (read)\nGET  /v1/usage?from&to  -> { days: [{day, uploads, bytesUploaded, encodedSeconds}] }  (read)\nPOST /v1/keys           {"name":"ci","scopes":["upload"]} -> { key: "hostr_sk_live_..." } ONCE  (full)\nGET  /v1/keys           -> metadata only, never hashes                    (full)\nDELETE /v1/keys/:id     -> { revoked: true }                              (full)\n```\n\n## 5. Webhooks + the event log\n\nConfigure one endpoint per account:\n\n```\nPUT  /v1/webhooks   {"url":"https://yourapp.example/hostr-webhook"}      (full)\n  -> { url, enabled, secret: "whsec_..." }        # secret returned ONLY when generated, ONLY once\nGET  /v1/webhooks   -> { url, enabled, createdAt }                        # never the secret\nDELETE /v1/webhooks -> disables (delivery history retained)\n```\n\nEvents \u2014 body `{ id, type, createdAt, data }`; `id` is the durable event\nrow\'s id (dedupe on it):\n\n| type             | fired when                             | data highlights                          |\n|------------------|----------------------------------------|------------------------------------------|\n| `upload.created` | multipart session opened               | `assetId`, `filename`, `declaredSize`    |\n| `video.uploaded` | bytes verified in storage, transcode queued | `assetId`, `bytes`, `etag`, `sha256?` |\n| `video.ready`    | HLS renditions live                    | `assetId`, `playbackId`, `durationSec?`  |\n| `video.errored`  | transcode failed                       | `assetId`, `error` (always present)      |\n| `video.deleted`  | asset erased; playback over            | `assetId`                                |\n| `video.input.non_standard` | the source needed a judgement call | `assetId`, `input`, `findings[]`  |\n\n`video.input.non_standard` is advisory \u2014 the transcode proceeds normally and\na `video.ready` still follows. It fires at most once per asset, only when\nthere is something to say, and reports what the encoder had to assume:\n\n| finding code         | meaning                                                                 |\n|----------------------|-------------------------------------------------------------------------|\n| `hdr_tags_on_8bit`   | source carries HLG/PQ tags but is 8-bit. HDR is a 10-bit format, so the tag is stale \u2014 treated as SDR, pixels untouched |\n| `hdr_source`         | genuine 10-bit HDR. The ladder outputs 8-bit SDR; no tone mapping is applied |\n| `wide_gamut_tags`    | BT.2020 primaries without an HDR transfer; output is BT.709, colour not converted |\n| `variable_frame_rate`| container rate and measured rate disagree; normalised to CFR             |\n| `frame_rate_changed` | source rate was not a broadcast standard and was snapped to the nearest  |\n\n`data.input` carries the full probe: `videoCodec`, `pixFmt`, `bitDepth`,\n`width`, `height`, `declaredFps`, `averageFps`, `targetFps`,\n`isVariableFrameRate`, `colorSpace`, `colorTransfer`, `colorPrimaries`. The\nsame block is on the asset record as `input`, so it can be read back at any\ntime without replaying events.\n\nEndpoint URLs: both `https` and `http` are accepted, including private\naddresses \u2014 hostr does not currently block internal ranges, so a local\nreceiver works in development exactly like production.\n\nEvery delivery carries `hostr-signature`, a comma-separated list currently\ncontaining `t=<unix-seconds>` and `v1=<hex>` where\n`v1 = HMAC-SHA256(secret, "<t>.<rawBody>")` \u2014 the Stripe scheme. Parse it\nas a list (future fields may be added); verify before trusting\n(constant-time compare, bounded timestamp):\n\n```js\nimport { createHmac, timingSafeEqual } from \'node:crypto\';\n\nexport function verifyHostrWebhook(secret, header, rawBody, toleranceSec = 300) {\n  const m = /^t=(\\d+),v1=([0-9a-f]{64})$/.exec(header ?? \'\');\n  if (!m) return false;\n  if (Math.abs(Date.now() / 1000 - Number(m[1])) > toleranceSec) return false;\n  const expected = createHmac(\'sha256\', secret).update(`${m[1]}.${rawBody}`).digest(\'hex\');\n  return expected.length === m[2].length &&\n    timingSafeEqual(Buffer.from(expected), Buffer.from(m[2]));\n}\n// Use the RAW request body bytes \u2014 parse JSON only after verification.\n```\n\nDelivery is at-least-once (3 attempts with backoff, each recorded). The\nwebhook is the wake-up signal; the **durable event log** is the ledger:\n\n```\nGET  /v1/events?after=<cursor>&limit=&type=   ascending; reuse nextCursor verbatim   (read)\nGET  /v1/events?order=desc&limit=1            newest first (e.g. the latest event)   (read)\nPOST /v1/events/:id/redeliver                 replay any stored event                (full)\n```\n\n`npx @hostr/cli tail --follow` polls this for you; `npx @hostr/cli webhooks test`\nredelivers the newest event to prove your endpoint end-to-end. Respond\n`2xx` fast (do the work async) \u2014 anything else is retried.\n\n## 6. Playback\n\nPlayback is token-gated. Mint per view, server-side, with a `full` key:\n\n```\nPOST /v1/assets/:id/tokens    {"ttlSec":3600,"viewerId":"user-123"}      (optional body)\n  -> { playback, thumbnail, storyboard, expiresAt }                       (expiresAt in ms)\nnpx @hostr/cli assets token <assetId> --json                                   (CLI equivalent)\n```\n\nMinting works any time after the asset exists (it 404s only for unknown\nassets); the stream itself returns 404 until the asset is `ready` \u2014 gate\nyour UI on `video.ready` / asset status, not on whether minting succeeds.\n\nBuild the URL and hand it to any HLS player:\n\n```\nhttps://stream.hostr.sh/{playbackId}.m3u8?token={playback}\n```\n\n- Use hls.js in browsers without native HLS; Safari/iOS play it natively.\n- The token is checked once at the master playlist; the stream then works\n  for the whole viewing session (segment credentials are handled\n  internally). Default TTL 1 h \u2014 it only needs to be valid when playback\n  *starts*.\n- `viewerId` enables per-viewer concurrency observation.\n- **Non-browser user agents are rejected** (`403 blocked_user_agent`):\n  curl/wget/ffmpeg/vlc UAs are blocked as a casual-ripping speed bump. For\n  server-side smoke tests send a browser-like `User-Agent`.\n- Signed URLs are not DRM: they stop link-sharing and hotlinking, not an\n  entitled viewer recording their screen.\n- `DELETE /v1/assets/:id` erases an asset for good: source and renditions\n  are purged from storage, the storage quota is freed, and `video.deleted`\n  is emitted. Deletion is idempotent (repeat calls return `deleted`\n  again). New playback tokens stop minting immediately; tokens already\n  issued can replay edge-cached segments for at most a few hours until\n  they expire. There is no undelete.\n\nThe token bundle also covers the poster image and scrub previews \u2014 same\nhost, same query-token shape, each URL taking its matching token from the\nmint response:\n\n```\nhttps://stream.hostr.sh/{playbackId}/thumbnail.jpg?token={thumbnail}\nhttps://stream.hostr.sh/{playbackId}/storyboard.vtt?token={storyboard}\n```\n\nThe storyboard is a standard "thumbnails" WebVTT track (cues point into a\ntiled sprite with `#xywh=` fragments) \u2014 hand it to mux-player\'s\n`storyboard-src`, media-chrome\'s preview track, or any player that consumes\nthat convention; the sprite URLs inside the VTT are pre-signed for you.\nPlayers treat the track as optional: for assets encoded before storyboards\nexisted the URL 404s and scrubbing simply shows no preview.\n\n## 6b. Subtitles\n\nHuman-authored WebVTT tracks, attached any time after the asset is `ready`\n(409 `not_ready` before that \u2014 the playlist needs the duration):\n\n```\nPUT    /v1/assets/:id/subtitles/:lang?name=English&default=true    (body: raw WebVTT, upload scope)\nGET    /v1/assets/:id/subtitles                 -> { tracks: [{ lang, name, default, rev }] }\nDELETE /v1/assets/:id/subtitles/:lang\nnpx @hostr/cli subtitles set <assetId> subs.vtt --lang en --name English --default\n```\n\n- `:lang` is a BCP 47 tag (`en`, `pt-BR`); one track per tag, PUT replaces.\n- Tracks appear in the master playlist automatically (`EXT-X-MEDIA`\n  subtitles group) \u2014 the next master fetch after a PUT includes them, no\n  re-encode, no new playback URL. Players show them in the captions menu.\n- `default=true` demotes any previous default.\n- Replacements propagate on the next playback session; a viewer mid-session\n  keeps the track they started with.\n\n## 7. Error handling summary\n\n| status | error                        | meaning / action |\n|--------|------------------------------|------------------|\n| 401    | `unauthorized`               | bad/revoked key, or not your resource \u2014 check key + assetId |\n| 403    | `insufficient_scope`         | key scope too low; `need` names the required scope |\n| 403    | `quota_*`                    | account limit hit; `limit` is the ceiling |\n| 403    | `account_suspended`          | contact the operator |\n| 409    | `incomplete_upload`          | parts missing (`missing` lists them) \u2014 upload them, re-complete |\n| 409    | `size_mismatch`              | declared size \u2260 bytes landed \u2014 abort and restart |\n| 409    | `not_uploading`              | upload already finished/aborted |\n| 413    | `file_too_large`             | raise `partSize` or split |\n| 503    | `control_plane_unavailable`  | transient \u2014 retry with backoff |\n| 500    | `signing_not_configured`     | operator-side: the playback signing key isn\'t loaded on this API deployment. Not your integration\'s fault and not retryable from the client \u2014 report it |\n\n## 8. Full route table\n\n| Method | Path | Scope | Purpose |\n|---|---|---|---|\n| POST | `/v1/uploads` | upload | create upload session |\n| GET | `/v1/uploads/:id` | upload* | status + landed parts (resume) |\n| POST | `/v1/uploads/:id/parts` | upload* | presigned part URLs |\n| POST | `/v1/uploads/:id/complete` | upload* | verify + finalize |\n| POST | `/v1/uploads/:id/token` | upload | re-mint upload token |\n| DELETE | `/v1/uploads/:id` | upload* | abort |\n| GET | `/v1/assets` | read | list own assets |\n| GET | `/v1/assets/:id` | read | asset record |\n| POST | `/v1/assets/:id/tokens` | full | playback credentials |\n| DELETE | `/v1/assets/:id` | full | erase asset: R2 purged, quota freed, `video.deleted` emitted |\n| PUT | `/v1/assets/:id/subtitles/:lang` | upload | attach/replace WebVTT track |\n| GET | `/v1/assets/:id/subtitles` | read | list subtitle tracks |\n| DELETE | `/v1/assets/:id/subtitles/:lang` | upload | remove subtitle track |\n| GET | `/v1/account` | read | whoami: plan, limits, usage |\n| GET | `/v1/usage` | read | daily usage rows |\n| GET | `/v1/events` | read | durable event log (ascending tail; `order=desc` for newest-first) |\n| POST | `/v1/events/:id/redeliver` | full | replay a webhook |\n| GET/PUT/DELETE | `/v1/webhooks` | full | endpoint config |\n| POST/GET | `/v1/keys` | full | mint / list keys |\n| DELETE | `/v1/keys/:id` | full | revoke key |\n\n\\* also accepted: that upload\'s own `uploadToken`.\n\n## 9. CLI reference\n\n`npx @hostr/cli <cmd>` \u2014 every command takes `--json` (one JSON document on\nstdout; NDJSON for `tail --follow`; errors as JSON on stderr, exit 1).\nCredentials: `--key` flag > `HOSTR_API_KEY` env > saved profile\n(`hostr login`). API base: `--api` > `HOSTR_API_BASE` > profile > default.\n\n```\nlogin \xB7 whoami \xB7 usage \xB7 init\nkeys create|list|revoke\nwebhooks get|set|delete|test\nassets list|get \xB7 assets token <id> [--ttl <sec>] \xB7 upload <file> [--wait] \xB7 tail [--follow]\n```\n';
+var integrate_default = '# hostr \u2014 integration guide\n\nhostr is self-hosted video infrastructure: resumable upload \u2192 transcode \u2192\nHLS delivery, with signed playback URLs. This document is the complete,\nself-contained integration reference. It is written to be executed by a\ncoding agent; every command has a `--json` mode and every flow is\nverifiable from the terminal.\n\n```\nAPI base    https://api.hostr.sh                         (override: HOSTR_API_BASE)\nMedia host  https://stream.hostr.sh                 (playback URLs are built on this)\nDocs        GET {API base}/llms.txt  \xB7  GET {API base}/llms-full.txt (this file)\n```\n\n## 0. Getting started\n\nRun `npx @hostr/cli` in your app\'s repo. With no arguments it reports what is\nconfigured and names the single next step \u2014 authorize, prepare the repo, mint\nan application key \u2014 and it is the intended entry point for a coding agent.\nThis document is the *reference*: consult it while implementing, section by\nsection, rather than reading it front to back.\n\nNo Node available? Every flow here has a raw-HTTP form. Start at \xA72b.\n\n## 1. Authentication\n\nEvery API call sends `Authorization: Bearer <credential>`. There are two\ncredential kinds an integrator sees:\n\n- **API key** \u2014 `hostr_sk_live_\u2026`, minted per account in the hostr\n  dashboard or via `POST /v1/keys` / `npx @hostr/cli keys create`. Scoped:\n  - `read` \u2014 GETs only (status, listing, usage, events)\n  - `upload` \u2014 read + the upload lifecycle\n  - `playback` \u2014 upload + minting playback tokens. **This is what an\n    application key should be**: it can ingest and it can let viewers watch,\n    but it cannot delete assets or manage keys.\n  - `full` \u2014 everything, including deletion, key and webhook management\n  Keys are hashed at rest; the plaintext is shown exactly once at mint.\n  Rotation = create new + revoke old (`DELETE /v1/keys/:id`); revocation\n  takes effect within ~60 s. **Keep keys server-side.** Never ship one in a\n  browser or mobile app.\n- **Upload token** \u2014 short-lived HMAC scoped to a single upload\n  (`uploadToken` in the create-upload response). This is the only\n  credential an untrusted client (browser/mobile) should ever hold: it can\n  drive that one upload and nothing else.\n\n`npx @hostr/cli login` opens your browser and mints the CLI\'s own `full`-scoped\nkey after you approve it \u2014 nothing is pasted, and no key passes through a\ncoding agent that runs the command. It appears on the dashboard Keys page named\n`CLI \u2014 <hostname>` and is revocable like any other. `--key` (or `HOSTR_API_KEY`)\nstill works and is the right path for CI and headless automation.\n\nCommands that mint a secret take `--write-env <file>`, which writes the value\nstraight to that file and prints only the variable name \u2014 in `--json` mode too.\nUse it whenever an agent is driving the terminal.\n\nAuth errors: `401 {"error":"unauthorized"}` (bad/missing/revoked key, or a\nresource you don\'t own \u2014 hostr does not reveal which),\n`403 {"error":"insufficient_scope","need":"upload"}`,\n`403 {"error":"account_suspended"}`,\n`503 {"error":"control_plane_unavailable"}` (transient \u2014 retry with backoff;\nin-flight uploads with upload tokens are unaffected).\n\n## 2. Upload\n\nThree ways, strongest first:\n\n### 2a. CLI (recommended \u2014 resumable, integrity-checked)\n\n```bash\nnpx @hostr/cli upload path/to/video.mp4 --json           # returns when bytes are verified in R2\nnpx @hostr/cli upload path/to/video.mp4 --wait --json    # returns when transcode is ready/failed\n```\n\nOutput: `{ "assetId": "\u2026", "status": "queued"|"ready", "bytes": n, "etag": "\u2026", "sha256": "\u2026" }`.\nThe CLI wraps hostr\'s upload SDK: chunked multipart direct to storage,\nresume after crash/restart (server-authoritative \u2014 it asks storage which\nparts landed), retry with backoff, and three-layer integrity verification.\nExit code 1 + JSON on stderr on failure.\n\n### 2b. Raw HTTP (any language, no SDK)\n\n```\nPOST /v1/uploads                     {"filename":"a.mp4","size":<bytes>,"contentType":"video/mp4"}\n  -> 201 { assetId, partSize, expectedParts, uploadToken, tokenExpiresAt, key, uploadId }\n     (forward ONLY assetId/uploadToken/partSize/expectedParts/tokenExpiresAt to untrusted clients)\n\nPOST /v1/uploads/:id/parts           {"partNumbers":[1,2,...]}        (\u2264100 per call)\n  -> { urls: [{partNumber, url}], expiresIn }\nPUT  <each presigned url>            body = that part\'s bytes; capture the ETag response header\n\nGET  /v1/uploads/:id                 -> { status, uploadedParts, parts, bytesUploaded }   (resume)\nPOST /v1/uploads/:id/complete        {"sha256":"<hex of whole file>"}  (sha256 optional)\n  -> { assetId, status: "uploaded"|"queued", bytes, etag }\nDELETE /v1/uploads/:id               abort\nPOST /v1/uploads/:id/token           re-mint the upload token (API key with upload scope)\n```\n\nRules: every part is `partSize` bytes except the last; `size` must be\nexact \u2014 completion verifies both part count and total bytes against what\nactually landed and returns `409 incomplete_upload` (with the missing part\nnumbers) or `409 size_mismatch` otherwise. Completion is idempotent \u2014 a\ncrashed client retries it safely. Uploads are quota-gated:\n`403 {"error":"quota_uploads_daily"|"quota_assets"|"quota_storage","limit":n}`.\n\n### 2c. Browser/mobile clients\n\nCreate the upload server-side (2b), hand the client only\n`{assetId, uploadToken, partSize, expectedParts}`, and let it PUT parts\ndirectly to the presigned URLs \u2014 upload bytes never touch your servers.\n(A browser needs the storage bucket to allow your origin via CORS \u2014 if\npart PUTs stall at 0% with network-looking errors, that\'s the cause.)\n\n## 3. Asset lifecycle\n\n`uploading \u2192 uploaded \u2192 queued \u2192 processing \u2192 ready | failed` (plus\n`aborted`). Poll `GET /v1/assets/:id` (`read` scope) or \u2014 better \u2014 use\nwebhooks (\xA75). While `processing`, the asset carries live transcode\nprogress \u2014 `progress: { encodedSec, totalSec, speed }` (speed is the\nencode multiple of realtime; the field is null/absent outside\n`processing`) \u2014 so a UI can show a real percentage instead of a spinner. `GET /v1/assets?limit=&status=&cursor=` lists your assets\nnewest-first with keyset pagination (`nextCursor`).\n\nWhen `ready`, the asset record and the `video.ready` event both carry\n`playbackId` (equals `assetId` today \u2014 store it as its own field) and\n`durationSec`.\n\n## 4. Account, usage, keys\n\n```\nGET  /v1/account        -> { accountId, name, plan, limits, usage }      (read)\nGET  /v1/usage?from&to  -> { days: [{day, uploads, bytesUploaded, encodedSeconds}] }  (read)\nPOST /v1/keys           {"name":"ci","scopes":["upload"]} -> { key: "hostr_sk_live_..." } ONCE  (full)\nGET  /v1/keys           -> metadata only, never hashes                    (full)\nDELETE /v1/keys/:id     -> { revoked: true }                              (full)\n```\n\n## 5. Webhooks + the event log\n\nConfigure one endpoint per account:\n\n```\nPUT  /v1/webhooks   {"url":"https://yourapp.example/hostr-webhook"}      (full)\n  -> { url, enabled, secret: "whsec_..." }        # secret returned ONLY when generated, ONLY once\nGET  /v1/webhooks   -> { url, enabled, createdAt }                        # never the secret\nDELETE /v1/webhooks -> disables (delivery history retained)\n```\n\nEvents \u2014 body `{ id, type, createdAt, data }`; `id` is the durable event\nrow\'s id (dedupe on it):\n\n| type             | fired when                             | data highlights                          |\n|------------------|----------------------------------------|------------------------------------------|\n| `upload.created` | multipart session opened               | `assetId`, `filename`, `declaredSize`    |\n| `video.uploaded` | bytes verified in storage, transcode queued | `assetId`, `bytes`, `etag`, `sha256?` |\n| `video.ready`    | HLS renditions live                    | `assetId`, `playbackId`, `durationSec?`  |\n| `video.errored`  | transcode failed                       | `assetId`, `error` (always present)      |\n| `video.deleted`  | asset erased; playback over            | `assetId`                                |\n| `video.input.non_standard` | the source needed a judgement call | `assetId`, `input`, `findings[]`  |\n\n`video.input.non_standard` is advisory \u2014 the transcode proceeds normally and\na `video.ready` still follows. It fires at most once per asset, only when\nthere is something to say, and reports what the encoder had to assume:\n\n| finding code         | meaning                                                                 |\n|----------------------|-------------------------------------------------------------------------|\n| `hdr_tags_on_8bit`   | source carries HLG/PQ tags but is 8-bit. HDR is a 10-bit format, so the tag is stale \u2014 treated as SDR, pixels untouched |\n| `hdr_source`         | genuine 10-bit HDR. The ladder outputs 8-bit SDR; no tone mapping is applied |\n| `wide_gamut_tags`    | BT.2020 primaries without an HDR transfer; output is BT.709, colour not converted |\n| `variable_frame_rate`| container rate and measured rate disagree; normalised to CFR             |\n| `frame_rate_changed` | source rate was not a broadcast standard and was snapped to the nearest  |\n\n`data.input` carries the full probe: `videoCodec`, `pixFmt`, `bitDepth`,\n`width`, `height`, `declaredFps`, `averageFps`, `targetFps`,\n`isVariableFrameRate`, `colorSpace`, `colorTransfer`, `colorPrimaries`. The\nsame block is on the asset record as `input`, so it can be read back at any\ntime without replaying events.\n\nEndpoint URLs: both `https` and `http` are accepted, including private\naddresses \u2014 hostr does not currently block internal ranges, so a local\nreceiver works in development exactly like production.\n\nEvery delivery carries `hostr-signature`, a comma-separated list currently\ncontaining `t=<unix-seconds>` and `v1=<hex>` where\n`v1 = HMAC-SHA256(secret, "<t>.<rawBody>")` \u2014 the Stripe scheme. Parse it\nas a list (future fields may be added); verify before trusting\n(constant-time compare, bounded timestamp):\n\n```js\nimport { createHmac, timingSafeEqual } from \'node:crypto\';\n\nexport function verifyHostrWebhook(secret, header, rawBody, toleranceSec = 300) {\n  const m = /^t=(\\d+),v1=([0-9a-f]{64})$/.exec(header ?? \'\');\n  if (!m) return false;\n  if (Math.abs(Date.now() / 1000 - Number(m[1])) > toleranceSec) return false;\n  const expected = createHmac(\'sha256\', secret).update(`${m[1]}.${rawBody}`).digest(\'hex\');\n  return expected.length === m[2].length &&\n    timingSafeEqual(Buffer.from(expected), Buffer.from(m[2]));\n}\n// Use the RAW request body bytes \u2014 parse JSON only after verification.\n```\n\nDelivery is at-least-once (3 attempts with backoff, each recorded). The\nwebhook is the wake-up signal; the **durable event log** is the ledger:\n\n```\nGET  /v1/events?after=<cursor>&limit=&type=   ascending; reuse nextCursor verbatim   (read)\nGET  /v1/events?order=desc&limit=1            newest first (e.g. the latest event)   (read)\nPOST /v1/events/:id/redeliver                 replay any stored event                (full)\n```\n\n`npx @hostr/cli tail --follow` polls this for you; `npx @hostr/cli webhooks test`\nredelivers the newest event to prove your endpoint end-to-end. Respond\n`2xx` fast (do the work async) \u2014 anything else is retried.\n\n## 6. Playback\n\nPlayback is token-gated. Mint per view, server-side, with a `playback` key:\n\n```\nPOST /v1/assets/:id/tokens    {"ttlSec":3600,"viewerId":"user-123"}      (optional body)\n  -> { playback, thumbnail, storyboard, expiresAt }                       (expiresAt in ms)\nnpx @hostr/cli assets token <assetId> --json                                   (CLI equivalent)\n```\n\nMinting works any time after the asset exists (it 404s only for unknown\nassets); the stream itself returns 404 until the asset is `ready` \u2014 gate\nyour UI on `video.ready` / asset status, not on whether minting succeeds.\n\nBuild the URL and hand it to any HLS player:\n\n```\nhttps://stream.hostr.sh/{playbackId}.m3u8?token={playback}\n```\n\n- Use hls.js in browsers without native HLS; Safari/iOS play it natively.\n- The token is checked once at the master playlist; the stream then works\n  for the whole viewing session (segment credentials are handled\n  internally). Default TTL 1 h \u2014 it only needs to be valid when playback\n  *starts*.\n- `viewerId` enables per-viewer concurrency observation.\n- **Non-browser user agents are rejected** (`403 blocked_user_agent`):\n  curl/wget/ffmpeg/vlc UAs are blocked as a casual-ripping speed bump. For\n  server-side smoke tests send a browser-like `User-Agent`.\n- Signed URLs are not DRM: they stop link-sharing and hotlinking, not an\n  entitled viewer recording their screen.\n- `DELETE /v1/assets/:id` erases an asset for good: source and renditions\n  are purged from storage, the storage quota is freed, and `video.deleted`\n  is emitted. Deletion is idempotent (repeat calls return `deleted`\n  again). New playback tokens stop minting immediately; tokens already\n  issued can replay edge-cached segments for at most a few hours until\n  they expire. There is no undelete.\n\nThe token bundle also covers the poster image and scrub previews \u2014 same\nhost, same query-token shape, each URL taking its matching token from the\nmint response:\n\n```\nhttps://stream.hostr.sh/{playbackId}/thumbnail.jpg?token={thumbnail}\nhttps://stream.hostr.sh/{playbackId}/storyboard.vtt?token={storyboard}\n```\n\nThe storyboard is a standard "thumbnails" WebVTT track (cues point into a\ntiled sprite with `#xywh=` fragments) \u2014 hand it to mux-player\'s\n`storyboard-src`, media-chrome\'s preview track, or any player that consumes\nthat convention; the sprite URLs inside the VTT are pre-signed for you.\nPlayers treat the track as optional: for assets encoded before storyboards\nexisted the URL 404s and scrubbing simply shows no preview.\n\n## 6b. Subtitles\n\nHuman-authored WebVTT tracks, attached any time after the asset is `ready`\n(409 `not_ready` before that \u2014 the playlist needs the duration):\n\n```\nPUT    /v1/assets/:id/subtitles/:lang?name=English&default=true    (body: raw WebVTT, upload scope)\nGET    /v1/assets/:id/subtitles                 -> { tracks: [{ lang, name, default, rev }] }\nDELETE /v1/assets/:id/subtitles/:lang\nnpx @hostr/cli subtitles set <assetId> subs.vtt --lang en --name English --default\n```\n\n- `:lang` is a BCP 47 tag (`en`, `pt-BR`); one track per tag, PUT replaces.\n- Tracks appear in the master playlist automatically (`EXT-X-MEDIA`\n  subtitles group) \u2014 the next master fetch after a PUT includes them, no\n  re-encode, no new playback URL. Players show them in the captions menu.\n- `default=true` demotes any previous default.\n- Replacements propagate on the next playback session; a viewer mid-session\n  keeps the track they started with.\n\n## 7. Error handling summary\n\n| status | error                        | meaning / action |\n|--------|------------------------------|------------------|\n| 401    | `unauthorized`               | bad/revoked key, or not your resource \u2014 check key + assetId |\n| 403    | `insufficient_scope`         | key scope too low; `need` names the required scope |\n| 403    | `quota_*`                    | account limit hit; `limit` is the ceiling |\n| 403    | `account_suspended`          | contact the operator |\n| 409    | `incomplete_upload`          | parts missing (`missing` lists them) \u2014 upload them, re-complete |\n| 409    | `size_mismatch`              | declared size \u2260 bytes landed \u2014 abort and restart |\n| 409    | `not_uploading`              | upload already finished/aborted |\n| 413    | `file_too_large`             | raise `partSize` or split |\n| 429    | `rate_limited`               | `POST /v1/device/code` only \u2014 it is unauthenticated, so it is capped per IP. A real login makes one call here; if you are seeing this, something is looping. Wait a minute and retry |\n| 503    | `control_plane_unavailable`  | transient \u2014 retry with backoff |\n| 500    | `signing_not_configured`     | operator-side: the playback signing key isn\'t loaded on this API deployment. Not your integration\'s fault and not retryable from the client \u2014 report it |\n\n## 8. Full route table\n\n| Method | Path | Scope | Purpose |\n|---|---|---|---|\n| POST | `/v1/uploads` | upload | create upload session |\n| GET | `/v1/uploads/:id` | upload* | status + landed parts (resume) |\n| POST | `/v1/uploads/:id/parts` | upload* | presigned part URLs |\n| POST | `/v1/uploads/:id/complete` | upload* | verify + finalize |\n| POST | `/v1/uploads/:id/token` | upload | re-mint upload token |\n| DELETE | `/v1/uploads/:id` | upload* | abort |\n| GET | `/v1/assets` | read | list own assets |\n| GET | `/v1/assets/:id` | read | asset record |\n| POST | `/v1/assets/:id/tokens` | playback | playback credentials |\n| DELETE | `/v1/assets/:id` | full | erase asset: R2 purged, quota freed, `video.deleted` emitted |\n| PUT | `/v1/assets/:id/subtitles/:lang` | upload | attach/replace WebVTT track |\n| GET | `/v1/assets/:id/subtitles` | read | list subtitle tracks |\n| DELETE | `/v1/assets/:id/subtitles/:lang` | upload | remove subtitle track |\n| GET | `/v1/account` | read | whoami: plan, limits, usage |\n| GET | `/v1/usage` | read | daily usage rows |\n| GET | `/v1/events` | read | durable event log (ascending tail; `order=desc` for newest-first) |\n| POST | `/v1/events/:id/redeliver` | full | replay a webhook |\n| GET/PUT/DELETE | `/v1/webhooks` | full | endpoint config |\n| POST/GET | `/v1/keys` | full | mint / list keys |\n| DELETE | `/v1/keys/:id` | full | revoke key |\n| POST | `/v1/device/code` | \u2014 | begin browser-authorized CLI login |\n| POST | `/v1/device/token` | \u2014 | poll it; returns the key once approved |\n\n\\* also accepted: that upload\'s own `uploadToken`.\n\n## 9. CLI reference\n\n`npx @hostr/cli <cmd>` \u2014 every command takes `--json` (one JSON document on\nstdout; NDJSON for `tail --follow`; errors as JSON on stderr, exit 1).\nRun it with **no arguments** for setup status and the next step.\n\nCredentials: `--key` flag > `HOSTR_API_KEY` env > saved profile\n(`hostr login`). API base: `--api` > `HOSTR_API_BASE` > profile > default.\n\n```\n(no args)  setup status and the next step\nlogin      browser-authorized; --key <k> for CI\nwhoami \xB7 usage \xB7 init\nkeys create [--name] [--scopes read|upload|playback|full] [--write-env <file>] | list | revoke <id>\nwebhooks get | set <url> [--write-env <file>] | delete | test\nassets list|get <id> \xB7 assets token <id> [--ttl <sec>] \xB7 upload [file] [--wait] \xB7 tail [--follow]\nsubtitles list <id> | set <id> <file> --lang <tag> | rm <id> <lang>\n```\n\n`--write-env <file>` writes the minted secret into that file and prints only\nthe variable name. Nothing else in the CLI prints a credential.\n';
 
 // src/init-content.ts
 var BEGIN = "<!-- hostr:begin -->";
@@ -5297,6 +5477,9 @@ function missingEnvLines(existing) {
   );
   return ENV_LINES.filter((l) => !have.has(l.split("=")[0]));
 }
+var guideStamp = (version) => `<!-- hostr guide \xB7 CLI ${version} -->`;
+var GUIDE_STAMP_RE = /^<!-- hostr guide · CLI ([0-9]+\.[0-9]+\.[0-9]+) -->/;
+var readGuideStamp = (doc) => GUIDE_STAMP_RE.exec(doc ?? "")?.[1] ?? null;
 var agentsSection = (apiBase) => `
 ## hostr (video hosting)
 
@@ -5317,7 +5500,7 @@ transcode, HLS playback with signed URLs.
 `;
 
 // src/commands-init.ts
-var readOrNull = (p) => readFile3(p, "utf8").catch(() => null);
+var readOrNull2 = (p) => readFile4(p, "utf8").catch(() => null);
 async function init(opts) {
   const out = makeOut(!!opts.json);
   const dir = opts.dir ?? process.cwd();
@@ -5325,27 +5508,29 @@ async function init(opts) {
   const actions = {};
   await mkdir3(join3(dir, "docs"), { recursive: true });
   const docPath = join3(dir, "docs/hostr.md");
-  const prevDoc = await readOrNull(docPath);
-  if (prevDoc === integrate_default) actions["docs/hostr.md"] = "unchanged";
+  const stamped = `${guideStamp(CLI_VERSION)}
+${integrate_default}`;
+  const prevDoc = await readOrNull2(docPath);
+  if (prevDoc === stamped) actions["docs/hostr.md"] = "unchanged";
   else {
-    await writeFile3(docPath, integrate_default);
+    await writeFile4(docPath, stamped);
     actions["docs/hostr.md"] = prevDoc === null ? "written" : "updated";
   }
   const agentsPath = join3(dir, "AGENTS.md");
-  const prevAgents = await readOrNull(agentsPath);
+  const prevAgents = await readOrNull2(agentsPath);
   const nextAgents = spliceMarkers(prevAgents, agentsSection(apiBase));
   if (nextAgents === prevAgents) actions["AGENTS.md"] = "unchanged";
   else {
-    await writeFile3(agentsPath, nextAgents);
+    await writeFile4(agentsPath, nextAgents);
     actions["AGENTS.md"] = prevAgents === null ? "written" : "updated";
   }
   const envPath = join3(dir, ".env.example");
-  const prevEnv = await readOrNull(envPath);
+  const prevEnv = await readOrNull2(envPath);
   const missing = missingEnvLines(prevEnv);
   if (!missing.length) actions[".env.example"] = "unchanged";
   else {
     const base = prevEnv === null ? "" : prevEnv.replace(/\n*$/, "\n");
-    await writeFile3(envPath, `${base}${missing.join("\n")}
+    await writeFile4(envPath, `${base}${missing.join("\n")}
 `);
     actions[".env.example"] = prevEnv === null ? "written" : "updated";
   }
@@ -5355,9 +5540,99 @@ async function init(opts) {
   );
 }
 
+// src/commands-status.ts
+import { readFile as readFile5 } from "node:fs/promises";
+import { join as join4 } from "node:path";
+
+// src/status.ts
+var APP_KEY_CMD = 'npx hostr keys create --name "app dev" --write-env .env.local';
+function computeStatus(i) {
+  const staleGuide = i.guideStampVersion !== null && i.guideStampVersion !== i.cliVersion;
+  const authorized = !i.hasProfileKey ? { mark: "\u2717", label: "not authorized", detail: "" } : i.account ? { mark: "\u2713", label: "authorized", detail: `account "${i.account.name}" (plan: ${i.account.plan})` } : { mark: "?", label: "authorized", detail: "key saved; could not reach the API to confirm" };
+  const prepared = i.guideStampVersion === null ? { mark: "\u2717", label: "repo not prepared", detail: "" } : {
+    mark: "\u2713",
+    label: "repo prepared",
+    detail: staleGuide ? `docs/hostr.md written by CLI ${i.guideStampVersion}; you are running ${i.cliVersion} \u2014 re-run npx hostr init` : "docs/hostr.md, AGENTS.md, .env.example"
+  };
+  const appKey = i.envKeyFile === null ? { mark: "\u2717", label: "no app key", detail: "" } : { mark: "\u2713", label: "app key", detail: `HOSTR_API_KEY in ${i.envKeyFile}` };
+  const rows = [authorized, prepared, appKey];
+  let nextCommand = null;
+  let nextNote = null;
+  if (authorized.mark === "\u2717") {
+    nextCommand = "npx hostr login";
+    nextNote = "Opens a browser for your human to approve. Do NOT ask them to paste an\n  API key, and do not put a key in your context.";
+  } else if (prepared.mark === "\u2717") {
+    nextCommand = "npx hostr init";
+    nextNote = "Writes docs/hostr.md, an AGENTS.md section, and .env.example entries. No network.";
+  } else if (appKey.mark === "\u2717") {
+    nextCommand = APP_KEY_CMD;
+    nextNote = "Writes the key straight to the file \u2014 the value is never printed.";
+  }
+  const activity = !i.online || !i.account ? "account: not checked (offline)" : `account: ${i.account.assetCount} assets \xB7 ${i.webhookUrl ? `webhook ${i.webhookUrl}` : "no webhook configured"}`;
+  return { rows, nextCommand, nextNote, activity, staleGuide };
+}
+function renderStatus(r) {
+  const body = r.rows.map((x) => `  ${x.mark} ${x.label.padEnd(18)}${x.detail}`.trimEnd()).join("\n");
+  const next = r.nextCommand ? `
+
+Next: ${r.nextCommand}${r.nextNote ? `
+  ${r.nextNote}` : ""}` : "\n\nSetup complete. Implement from docs/hostr.md \u2014 \xA75 webhooks, \xA76 playback.\nRegister your webhook once the endpoint is deployed:\n  npx hostr webhooks set <url> --write-env .env.local";
+  return `hostr \u2014 video for this app.
+
+${body}${next}
+
+${r.activity}
+`;
+}
+
+// src/commands-status.ts
+var readOrNull3 = (p) => readFile5(p, "utf8").catch(() => null);
+async function findEnvKey(dir) {
+  for (const f of [".env.local", ".env"]) {
+    const body = await readOrNull3(join4(dir, f));
+    if (body && /^\s*HOSTR_API_KEY=\S/m.test(body)) return f;
+  }
+  return null;
+}
+async function status(opts) {
+  const out = makeOut(!!opts.json);
+  const dir = process.cwd();
+  const cfg = await loadConfig(configDir());
+  const { key, apiBase } = resolveAuth({
+    flagKey: opts.key,
+    flagApi: opts.api,
+    env: process.env,
+    profile: activeProfile(cfg)
+  });
+  const input = {
+    hasProfileKey: !!key,
+    guideStampVersion: readGuideStamp(await readOrNull3(join4(dir, "docs/hostr.md"))),
+    cliVersion: CLI_VERSION,
+    envKeyFile: await findEnvKey(dir),
+    account: null,
+    webhookUrl: null,
+    online: false
+  };
+  if (key) {
+    const client = makeClient({ apiBase, key });
+    try {
+      const a = await client.account();
+      input.account = { name: a.name, plan: a.plan, assetCount: a.usage.assetCount };
+      input.online = true;
+      input.webhookUrl = await client.webhookGet().then((w) => w.url).catch(() => null);
+    } catch {
+    }
+  }
+  const report = computeStatus(input);
+  out.print(renderStatus(report), { ...report, cliVersion: CLI_VERSION });
+}
+
 // src/cli.ts
-var program2 = new Command("hostr").description("hostr \u2014 self-hosted video infrastructure (upload, transcode, HLS delivery)").version("0.1.3").option("--key <key>", "API key (overrides HOSTR_API_KEY and the saved profile)").option("--api <url>", "API base URL (overrides HOSTR_API_BASE and the saved profile)").option("--json", "machine-readable output: one JSON document (NDJSON for tail --follow)");
+var program2 = new Command("hostr").description("hostr \u2014 self-hosted video infrastructure (upload, transcode, HLS delivery)\nRun `npx hostr` with no arguments for setup status and the next step.").version(CLI_VERSION).option("--key <key>", "API key (overrides HOSTR_API_KEY and the saved profile)").option("--api <url>", "API base URL (overrides HOSTR_API_BASE and the saved profile)").option("--json", "machine-readable output: one JSON document (NDJSON for tail --follow)");
 var globals = () => program2.opts();
+program2.action(async () => {
+  await status(globals());
+});
 var run = (fn) => async (...args) => {
   const g = globals();
   const ctx = await makeCtx(g);
@@ -5378,11 +5653,11 @@ program2.command("whoami").description("account, plan, limits, live usage").acti
 program2.command("usage").description("daily usage rows").option("--from <date>", "YYYY-MM-DD (default: 30 days ago)").option("--to <date>", "YYYY-MM-DD (default: today)").action(run(usage));
 var keys = program2.command("keys").description("API key management");
 keys.command("list").action(run(keysList));
-keys.command("create").option("--name <name>").option("--scopes <scopes>", "comma-separated: read,upload,full").action(run(keysCreate));
+keys.command("create").option("--name <name>").option("--scopes <scopes>", "comma-separated: read,upload,playback,full (default: playback)").option("--write-env <file>", "write HOSTR_API_KEY into <file> instead of printing it").action(run(keysCreate));
 keys.command("revoke <id>").action(run(keysRevoke));
 var webhooks = program2.command("webhooks").description("webhook endpoint config");
 webhooks.command("get").action(run(webhooksGet));
-webhooks.command("set <url>").option("--secret <secret>", "bring your own whsec (default: generated, shown once)").action(run((ctx, url, opts) => webhooksSet(ctx, url, opts)));
+webhooks.command("set <url>").option("--secret <secret>", "bring your own whsec (default: generated, shown once)").option("--write-env <file>", "write HOSTR_WEBHOOK_SECRET into <file> instead of printing it").action(run((ctx, url, opts) => webhooksSet(ctx, url, opts)));
 webhooks.command("delete").action(run(webhooksDelete));
 webhooks.command("test").description("redeliver the newest stored event to your endpoint").action(run(webhooksTest));
 var subtitles = program2.command("subtitles").description("subtitle tracks (WebVTT)");
@@ -5393,7 +5668,7 @@ var assets = program2.command("assets").description("asset listing and status");
 assets.command("list").option("--status <status>").option("--limit <n>").option("--cursor <cursor>").action(run(assetsList));
 assets.command("get <id>").action(run((ctx, id) => assetsGet(ctx, id)));
 assets.command("delete <id>").description("erase an asset: R2 objects purged, playback ends (requires full scope)").action(run((ctx, id) => assetsDelete(ctx, id)));
-assets.command("token <id>").description("mint playback credentials (requires full scope)").option("--ttl <sec>").option("--viewer-id <id>").action(run((ctx, id, opts) => assetsToken(ctx, id, opts)));
+assets.command("token <id>").description("mint playback credentials (requires playback scope)").option("--ttl <sec>").option("--viewer-id <id>").action(run((ctx, id, opts) => assetsToken(ctx, id, opts)));
 program2.command("tail").description("event log (durable; ascending). One page by default.").option("-f, --follow", "poll every 2s").option("--type <type>", "filter: upload.created | video.uploaded | video.ready | video.errored").option("--limit <n>").option("--after <cursor>", "start after this event id").action(run(tail));
 program2.command("init").description("make this repo agent-ready: docs/hostr.md + AGENTS.md section + .env.example entries").option("--dir <dir>", "target directory (default: cwd)").action(async (opts) => {
   await init({ ...globals(), ...opts });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hostr/cli",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "description": "CLI for hostr \u2014 self-hosted video infrastructure (upload, transcode, HLS delivery)",
   "license": "MIT",
   "type": "module",