@hostr/cli 0.1.0 → 0.1.1

package/dist/cli.js

@@ -3483,7 +3483,7 @@ var {
 import { mkdir, readFile, writeFile, chmod } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
-var DEFAULT_API_BASE = "https://hostr-api.hostr.workers.dev";
+var DEFAULT_API_BASE = "https://api.hostr.sh";
 var configDir = (env = process.env) => env.HOSTR_CONFIG_DIR ?? join(homedir(), ".config", "hostr");
 async function loadConfig(dir = configDir()) {
   try {
@@ -4961,7 +4961,7 @@ import { mkdir as mkdir3, readFile as readFile3, writeFile as writeFile3 } from
 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://hostr-api.hostr.workers.dev     (override: HOSTR_API_BASE)\nMedia host  https://stream-dev.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 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). `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\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-dev.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\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| 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-dev.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 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). `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\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-dev.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\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| 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';
 
 // src/init-content.ts
 var BEGIN = "<!-- hostr:begin -->";
@@ -5050,7 +5050,7 @@ async function init(opts) {
 }
 
 // src/cli.ts
-var program2 = new Command("hostr").description("hostr \u2014 self-hosted video infrastructure (upload, transcode, HLS delivery)").version("0.1.0").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)").version("0.1.1").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();
 var run = (fn) => async (...args) => {
   const g = globals();

package/package.json

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