@mediaruntime/cli 1.1.0 → 1.3.0

package/docs/AUTH.md

@@ -61,6 +61,14 @@ Authenticated commands resolve credentials in this order:
 No command-line API-key flag exists. No plaintext credential-file fallback exists. A
 machine without a supported credential vault must use `MEDIARUNTIME_API_KEY`.
 
+Hosted Sticker Runtime has one deliberately narrower exception. For collection-bound
+`stickers packs list`, `search`, `typeahead`, `get`, and `resolve`,
+`MEDIARUNTIME_STICKER_CLIENT_TOKEN` selects a short-lived scoped client without reading the
+master API key or stored login. The explicit collection must match the token claim.
+Collection management, pack binding, workspace usage, and token issuance never accept that
+credential and continue using the normal resolution order above. See
+[the Sticker Runtime contract](STICKERS.md) for the exact boundary.
+
 ## Security invariants
 
 - Device codes and PKCE verifiers carry at least 256 bits of randomness.

package/docs/CLI_SDD.md

@@ -1,6 +1,6 @@
 # MediaRuntime CLI software design
 
-Status: stable public contract released as `1.1.0`
+Status: stable public contract released as `1.2.0`
 
 Package: `@mediaruntime/cli`
 
@@ -18,6 +18,17 @@ mediaruntime run <source> --output <alias>
 mediaruntime run <source> --preset <public-preset>
 mediaruntime capabilities
 mediaruntime presets list
+mediaruntime recipes list
+mediaruntime recipes get <name>
+mediaruntime recipes create --file <recipe.json>
+mediaruntime recipes version <name> --file <recipe.json> --expected <version>
+mediaruntime recipes archive <name>
+mediaruntime stickers collections list
+mediaruntime stickers collections packs enable <collection_id> --pack <pack_id>
+mediaruntime stickers search <query> --collection <collection_id>
+mediaruntime stickers resolve <sticker_id> --variant <name> --collection <collection_id>
+mediaruntime stickers usage
+mediaruntime stickers token create --collection <collection_id>
 mediaruntime jobs list
 mediaruntime jobs get <job_id>
 mediaruntime trigger job.completed --to http://127.0.0.1:3000/webhooks/mediaruntime
@@ -36,6 +47,11 @@ The canonical result remains one expiring ZIP bundle containing the complete out
 The CLI downloads that ZIP as-is; it does not expose individual artifacts or infer an
 engine directory layout.
 
+Hosted Sticker Runtime commands are the other explicit asset-delivery surface. They bind
+all reads to one application collection and use the SDK's short-lived, generation-pinned
+sticker resolution rather than the job ZIP contract. The complete command and security
+contract is maintained in `docs/STICKERS.md`.
+
 ## 2. Goals and non-goals
 
 ### Goals
@@ -56,7 +72,7 @@ engine directory layout.
   authenticated connections, event ownership, expiry, rate limits, and an abuse model.
 - Named multi-account profiles are deferred. Browser login stores one credential per API
   origin; an explicit environment key remains the account override.
-- Batch submission, custom output recipe editing, moderation, watermark management,
+- Batch submission, arbitrary inline output-object editing, moderation, watermark management,
   webhook registration, media-report retrieval, and moderation-result retrieval remain
   available through the SDK/API but are not CLI v1 commands. Named public presets are
   supported through `--preset`; arbitrary output objects remain deferred.
@@ -125,6 +141,28 @@ mediaruntime run <source>
   [--json]
 ```
 
+When exactly one `contact_sheet_v1` preset is selected, `run` also accepts bounded
+`--contact-columns`, `--contact-rows`, `--contact-tile-width`,
+`--contact-tile-height`, `--contact-interval`, `--contact-start`,
+`--contact-duration`, `--contact-max-sheets`, `--contact-format`, and
+`--contact-quality` controls. They are rejected with recipes, mixed outputs, or any
+other preset so the CLI cannot attach them ambiguously.
+
+When exactly one `audiogram_v1` preset is selected, `--audiogram-artwork` is required.
+`--audiogram-captions` is optional and explicitly enables caption burning. Layout,
+background/waveform colours, start, duration, and frame-rate controls mirror the bounded
+gateway contract. Artwork and captions may be HTTP(S), `gs://`, `file://`, or local
+paths. Local secondary assets use the same authenticated signed-upload client as the
+main source; the submitted job contains only the resulting account-scoped `gs://` URI.
+Raw filters, font paths, and arbitrary rendering arguments are not accepted.
+
+Privacy redaction is a Premium Preview for still-image inputs and public image presets with one or
+more repeatable `--privacy-detector face|license_plate|text` flags. The CLI accepts only
+the gateway's bounded style, strength, failure-mode, confidence, segmented frame-count,
+padding, pixel-block, debug-observation, and solid-colour controls. It resolves aliases through the live capabilities document so
+the request carries explicit output objects, rejects video, audio, animated-image, and recipe combinations
+locally, and never accepts model paths, raw OCR retention, or arbitrary detector options.
+
 `-o` is the short spelling of `--output`. Exactly one source and at least one output or preset are
 required. `<source>` may be an HTTP(S) URL, `gs://` URI, local path, or `file://` URL. The
 CLI passes it to the SDK so local inputs use the SDK's signed-upload flow.
@@ -164,6 +202,10 @@ mediaruntime run ./launch.mp4 \
 mediaruntime run ./launch.mp4 \
   --preset dash_ladder_v1 --preset webm_vp9_1080p \
   --download ./adaptive-and-vp9.zip
+
+mediaruntime run ./launch.mp4 \
+  --recipe team-video@3 \
+  --download ./launch.zip
 ```
 
 ### 5.2 Capability and preset discovery
@@ -179,7 +221,15 @@ features, and the ordered public preset table. JSON uses the Node SDK's camelCas
 `presets list --json` returns `{presets: [...]}` in gateway order. Neither command infers
 public availability from the broader internal preset map.
 
-### 5.3 `jobs list`
+### 5.3 Hosted recipes
+
+`recipes list/get/create/version/archive` delegates to the Node SDK recipe resource.
+Create and version commands read explicit JSON files; secrets are never accepted in a
+recipe or printed. `version --expected` is the optimistic-lock precondition. `run
+--recipe` is mutually exclusive with aliases and public presets, and a resolved recipe
+uses the same job wait, exit, spinner, and atomic ZIP path as any other job.
+
+### 5.4 `jobs list`
 
 ```text
 mediaruntime jobs list
@@ -198,7 +248,7 @@ The human table columns are `ID`, `STATUS`, `TIER`, `UNITS`, `BUNDLE`, and `UPDA
 List rows intentionally have no bundle download URL; `jobs get` is the download-aware
 surface.
 
-### 5.4 `jobs get`
+### 5.5 `jobs get`
 
 ```text
 mediaruntime jobs get <job_id>

package/docs/STICKERS.md

@@ -0,0 +1,98 @@
+# Hosted Sticker Runtime CLI contract
+
+## Authentication boundary
+
+Sticker commands use the normal trusted credential by default: an explicit
+`MEDIARUNTIME_API_KEY`, then the API key stored by `mediaruntime login`. There is no
+command-line secret flag.
+
+`MEDIARUNTIME_STICKER_CLIENT_TOKEN` is an optional short-lived credential for only these
+collection-bound runtime reads:
+
+```text
+stickers packs list
+stickers search
+stickers typeahead
+stickers get
+stickers resolve
+```
+
+When this variable is set for one of those reads, the CLI constructs the Node SDK's scoped
+`StickerRuntime` directly and does not resolve or send a master API key. The explicit
+`--collection` must match the token claim. A scoped token cannot manage collections or pack
+bindings, inspect workspace usage, or mint another token. Those commands always require the
+trusted credential.
+
+## Collection management
+
+```text
+mediaruntime stickers collections list [--include-archived] [--json]
+mediaruntime stickers collections create --name <name> [--description <text>] [--json]
+mediaruntime stickers collections get <collection_id> [--json]
+mediaruntime stickers collections update <collection_id>
+  [--name <name>] [--description <text> | --clear-description]
+  [--status active|archived] [--json]
+mediaruntime stickers collections archive <collection_id> [--json]
+```
+
+Archive is recoverable and retains pack-binding history. Restore an archived collection with
+`collections update <collection_id> --status active`. JSON output is the SDK's camel-case
+projection.
+
+## Pack bindings
+
+```text
+mediaruntime stickers collections packs list <collection_id> [--json]
+mediaruntime stickers collections packs enable <collection_id>
+  (--pack <pack_id> | --activation <activation_id>) [--json]
+mediaruntime stickers collections packs disable <collection_id> --pack <pack_id> [--json]
+```
+
+These commands bind an existing paid Hosted Pack activation to an application collection.
+They do not purchase, activate, revoke, or charge for a pack. The stable pack-ID form is
+idempotent and suitable for configuration scripts. The activation-ID form is useful just
+after an account administrator completes activation elsewhere.
+
+Disabling removes the pack from new-use discovery while retaining the binding and its
+historical-access policy. Exact historical references can therefore remain renderable when
+the policy is `preserve`; search and metadata retrieval no longer return the disabled pack.
+
+## Runtime reads
+
+```text
+mediaruntime stickers packs list --collection <collection_id> [--json]
+mediaruntime stickers search <query> --collection <collection_id>
+  [--pack <pack_id>] [--category <category>]
+  [--animated | --static] [--limit <1..50>] [--json]
+mediaruntime stickers typeahead <prefix> --collection <collection_id>
+  [--pack <pack_id>] [--locale <locale>] [--limit <1..20>] [--json]
+mediaruntime stickers get <sticker_id> --collection <collection_id> [--json]
+mediaruntime stickers resolve <sticker_id> --variant <variant>
+  --collection <collection_id> [--json]
+```
+
+Search is metadata-only. Persist the stable `stickerId`, then call `resolve` only when an
+approved representation is needed. Resolution intentionally prints the short-lived signed
+URL because delivery authorization is the command's purpose. The URL is collection checked,
+variant checked, generation pinned, and expiring; do not persist it or write it to logs.
+
+Supported variants are `animated`, `reduced_motion`, `small_80`, `small_100`, `small_160`,
+and `thumbnail`. The gateway remains authoritative and may reject a supported name when the
+specific sticker does not publish that representation.
+
+## Usage and scoped token issuance
+
+```text
+mediaruntime stickers usage [--json]
+mediaruntime stickers token create --collection <collection_id>
+  [--expires-in <60..3600>]
+  [--scope packs:read|stickers:search|stickers:read|assets:resolve]...
+  [--json]
+```
+
+Omitting `--scope` asks the gateway for all four read scopes. Repeated scopes are
+deduplicated. Token output is secret-bearing by explicit request; redirect it only to a
+protected sink and avoid CI log capture. Usage is pooled at workspace/month level and
+reports operations, authorized delivery bytes, included allowances, settled overage, and
+health status. URL issuance records maximum authorized bytes; it does not claim that the
+client completed a CDN transfer.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mediaruntime/cli",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Official command-line client for MediaRuntime",
   "license": "MIT",
   "type": "module",
@@ -32,7 +32,7 @@
   },
   "dependencies": {
     "@napi-rs/keyring": "^1.3.0",
-    "@mediaruntime/node": "^1.1.1"
+    "@mediaruntime/node": "^1.3.0"
   },
   "devDependencies": {
     "@types/node": "^24.3.0",