@shotstack/cli 0.12.0 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shotstack/cli",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Command-line interface for the Shotstack video rendering API.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/shotstack/shotstack-cli",

package/skills/shotstack/SKILL.md

@@ -15,18 +15,18 @@ This skill loads in **terminal-based AI agents** (Claude Code, Cursor, Codex CLI
 
 ## Check versions once per session
 
-This skill is version **0.12.0** and needs `@shotstack/cli` **0.12.0** or later. Before the first `shotstack` command in a session:
+This skill is version **0.14.0** and needs `@shotstack/cli` **0.13.0** or later. Before the first `shotstack` command in a session:
 
-1. Run `shotstack --version`. If it is older than 0.12.0, tell the user: what this skill documents, such as `studio --env`, is missing until they run `npm install -g @shotstack/cli@latest`.
+1. Run `shotstack --version`. If it is older than 0.13.0, tell the user: what this skill documents, such as `analyze`, is missing until they run `npm install -g @shotstack/cli@latest`.
 2. Run `npm view @shotstack/cli version`. If it is newer than this skill's version, tell the user an update is available and ask whether to install it. Only on a yes, run `npx skills update shotstack -y` and `npm install -g @shotstack/cli@latest`. Never update without asking. `npx skills check` is not a read-only check: it installs the update.
 
 If a check fails (no network, no npm, a sandbox), skip it and carry on.
 
 **Open-ended first render? Ask before composing.** If the ask doesn't state what the video is (subject, format or destination) — e.g. "render my first video", "make me a video", "set up Shotstack" — read [`references/onboarding.md`](references/onboarding.md) and ask its discovery questions, then WAIT for answers. Do not write an Edit first. An open-ended ask is not a specification, and a stray JSON file in the project doesn't make the user experienced. Compose without asking only when the user has stated what the video is, or explicitly says to just show anything.
 
-Commands for the Shotstack video rendering API. `render` submits an Edit JSON and returns a render ID; `status` polls a render until done. `ingest` uploads your own local files (or fetches remote URLs) and hosts them so they can be referenced from an Edit. `validate` lints an Edit — run it before every render. `studio` opens an edit in the browser editor for a human to preview, tweak, and render. `template list|get|create|update|delete` reads and writes templates saved to the account: `list` shows saved templates (id + name); `get <id>` fetches a saved template's Edit JSON (e.g. one the user designed in Studio) so you can render or remix it; `create <file> --name <name>` saves an edit as a new template; `update <id> <file>` overwrites one; `delete <id>` removes one. `models` lists the generation models for prompt-driven assets and whether this key can use each one; `models <id>` prints the options a model accepts. `generate <model> "<prompt>"` generates one asset on its own and prints its URL. `analyze <url>` measures a music track's tempo, beats, bars, drops and sections, free and without a key.
+Commands for the Shotstack video rendering API. `render` submits an Edit JSON and returns a render ID; `status` polls a render until done. `ingest` uploads your own local files (or fetches remote URLs) and hosts them so they can be referenced from an Edit. `validate` lints an Edit — run it before every render. `studio` opens an edit in the browser editor for a human to preview, tweak, and render. `template list|get|create|update|delete` reads and writes templates saved to the account: `list` shows saved templates (id + name); `get <id>` fetches a saved template's Edit JSON (e.g. one the user designed in Studio) so you can render or remix it; `create <file> --name <name>` saves an edit as a new template; `update <id> <file>` overwrites one; `delete <id>` removes one. `models` lists the generation models for prompt-driven assets and whether this key can use each one; `models <id>` prints the options a model accepts. `generate <model> "<prompt>"` generates one asset on its own and prints its URL. `analyze <url>` measures a music track's tempo, beats, bars, drops and sections, free, and needs an API key.
 
-**Default loop — no API key required:** compose → `validate` (offline lint) → `studio` (browser preview). Only the API-backed commands (`render`, `status`, `ingest`, `models`, `generate`) need a key. Reach for `render` when you specifically need a final MP4 exported in the cloud; reach for `studio` for everything else — it is the cheapest way to see an edit and the right default for any creative a human will review.
+**Default loop — no API key required:** compose → `validate` (offline lint) → `studio` (browser preview). Only the API-backed commands (`render`, `status`, `ingest`, `models`, `generate`, `analyze`) need a key. Reach for `render` when you specifically need a final MP4 exported in the cloud; reach for `studio` for everything else — it is the cheapest way to see an edit and the right default for any creative a human will review.
 
 ## Authentication
 
@@ -45,7 +45,7 @@ Or set an environment variable (overrides the saved key — best for CI):
 export SHOTSTACK_API_KEY=...
 ```
 
-Resolution precedence: **`SHOTSTACK_API_KEY` env var → saved key for the target `--env` → error.** Get a key at <https://app.shotstack.io>. **`validate` and `studio` need no key** — only the API-backed commands (`render`, `status`, `ingest`, `models`, `generate`) require one; without a key *those* exit 1, while compose → validate → studio keeps working.
+Resolution precedence: **`SHOTSTACK_API_KEY` env var → saved key for the target `--env` → error.** Get a key at <https://app.shotstack.io>. **`validate` and `studio` need no key** — only the API-backed commands (`render`, `status`, `ingest`, `models`, `generate`, `analyze`) require one; without a key *those* exit 1, while compose → validate → studio keeps working.
 
 ## Environments
 
@@ -90,6 +90,8 @@ SRC=$(shotstack ingest upload ./clip.mp4 --watch --output json | tail -n1 | jq -
 # …then reference "$SRC" as an asset.src in your Edit JSON and run `shotstack render`.
 ```
 
+This includes images and fonts for an `html5` page: put the URL in its `html` or `css`.
+
 The bare command (no `--watch`) returns only an `id`; the hosted `source` URL does not exist until ingestion is `ready`. Always `--watch` (or follow up with `shotstack ingest status <id> --watch`) when you need the URL.
 
 Other ingest subcommands: `ingest fetch <url>` (host a copy of a remote URL), `ingest status <id>`, `ingest list`, `ingest delete <id>`. **Read [`references/ingest.md`](references/ingest.md) for the full upload→render workflow, status values, and supported file types.**

package/skills/shotstack/references/beat-sync.md

@@ -18,8 +18,10 @@ Host a local file with `shotstack ingest upload <file> --watch`. Generate a trac
 
 Analysis is free, takes 15–30 s and reads the first 10 minutes of the track.
 
-It needs no API key. The `src` must be a direct, public link to an audio or video file: share pages and redirects are refused.
+The `src` must be a direct, public link to an audio or video file: share pages and redirects are refused.
 <!-- surface:cli -->
+It needs an API key (`shotstack login`).
+
 ```sh
 shotstack analyze https://shotstack-assets.s3.amazonaws.com/music/unminus/lit.mp3 --output json > map.json
 ```

package/skills/shotstack/references/html5-effects.md

@@ -102,7 +102,7 @@ What you can build inside one `html5` clip, listed by the effect you'd reach for
 - **WebGL, shaders, 3D models:** use CSS 2.5D and SVG filters.
 - **Video or audio inside the clip:** put footage and sound on other timeline tracks; `html5` is the graphics layer.
 - **Scroll, drag or pointer-driven animation:** capture is time-driven only.
-- **Remote fonts, images, scripts:** inline them as `data:` URIs.
+- **Remote scripts, and images or fonts you haven't ingested:** inline them as `data:` URIs. Images and fonts you ingested work by URL; see [`html5.md`](html5.md).
 
 ## Cost
 

package/skills/shotstack/references/html5-snippets.md

@@ -16,8 +16,8 @@ Read [`html5.md`](html5.md) for the rules these obey. The non-negotiables:
 - **Size the clip to the content, not the canvas.** `html, body` pinned to the clip's `width`/`height`; place with `offset` (`{x:0,y:0}` is centred, `y` positive is up). Use **px**, never `vw`/`vh`/`%`.
 - **The body is transparent by default** — the clip composites over the layers below (only set an opaque background if you want one).
 - **Canvas only from the seek hook.** Draw canvas 2D inside `window.__shotstackSeek(ms)`, never in a `requestAnimationFrame` loop. WebGL is blank in the cloud render. SVG or positioned DOM is usually lighter.
-- **No network.** gsap (with its plugins), anime, d3 and lottie are preloaded; external `<script src>`, `fetch`, remote `<img>`, and remote fonts are all CSP-blocked — inline everything as `data:` URIs.
-- **Fonts:** `timeline.fonts[]` does **not** reach `html5` and remote `@font-face` is blocked. These snippets name a display font first but render in the `system-ui` fallback unless you inline the font as a `data:` `@font-face`.
+- **No network.** gsap (with its plugins), anime, d3 and lottie are preloaded; external `<script src>`, `fetch`, remote `<img>`, and remote fonts are all CSP-blocked. Inline them as `data:` URIs, or use the URL of an image or font you ingested (see [`html5.md`](html5.md)).
+- **Fonts:** `timeline.fonts[]` does **not** reach `html5` and remote `@font-face` is blocked. These snippets name a display font first but render in the `system-ui` fallback unless you load the font, from an ingested font's URL or a `data:` `@font-face`.
 - **Use unique element IDs for GSAP targets, not `:nth-child` or compound CSS selectors.** Studio preview doesn't resolve `.parent:nth-child(n) .child` patterns; `#id` works everywhere. When animating repeated elements (list rows, bars, cards), generate a unique ID per item (`id="row0"`, `id="bar0"`) rather than relying on structural selectors.
 
 Coordinates below assume a **1080×1920 vertical** canvas; adjust `offset` for other sizes.
@@ -48,7 +48,7 @@ The reference entrance: opacity, blur and a 16 px rise settle **together** off o
 }
 ```
 
-`base` (0.6 s) entrance on `power3.out`, then a `hold` (1.5 s) settle. Swap `{{title}}` via top-level `merge[]`. `Clash Display` falls back to `system-ui` unless you inline it as a `data:` `@font-face` (see Fonts above).
+`base` (0.6 s) entrance on `power3.out`, then a `hold` (1.5 s) settle. Swap `{{title}}` via top-level `merge[]`. `Clash Display` falls back to `system-ui` unless you load it, from an ingested font's URL or a `data:` `@font-face` (see Fonts above).
 
 ---
 

package/skills/shotstack/references/html5.md

@@ -11,7 +11,7 @@ This is the **modern replacement for the deprecated `html` asset.** `html5` runs
 - Required and optional fields
 - Preloaded libraries
 - The browser harness (deterministic auto-seek)
-- Sandbox restrictions: no network, inline everything (incl. fonts)
+- Sandbox restrictions: no network; ingested images and fonts by URL, everything else inline
 - Sizing
 - 3D: what renders in preview and render
 - Worked example: animated lower-third (GSAP)
@@ -89,25 +89,56 @@ Frames are captured by **seeking** the animation to each timestamp, not by playi
 
 **Duration comes from the clip's `length`** — there's no animation-duration auto-detection. Size your animation to run within (or fill) the clip's `length`.
 
-## Sandbox restrictions: no network, inline everything
+## Sandbox restrictions: no network, ingested files by URL
 
 The iframe renders under a strict Content-Security-Policy (`default-src 'none'`), in both Studio preview and cloud render. Nothing is fetched from the network at render time:
 
 - **No external `<script src=>`.** Only the bundled GSAP/anime.js/D3/Lottie run (they're inlined for you). Another library would have to be inlined into your `js` — and must be seekable.
 - **No `fetch` / `XMLHttpRequest`** (`connect-src 'none'`). Bundle any data inline — e.g. the JS array in the bar-chart example.
-- **No remote images** (`img-src 'self' data: blob:`). Embed images as `data:` URIs. A `data:image/svg+xml` background is fine.
-- **No remote fonts** (`font-src 'self' data:`) — see below.
+- **No remote images** (`img-src 'self' data: blob:`), except images you ingested (below). Otherwise embed images as `data:` URIs. A `data:image/svg+xml` background is fine.
+- **No remote fonts** (`font-src 'self' data:`), except fonts you ingested (below). See *Fonts in HTML5*.
+
+### Images and fonts you ingested
+
+Reference an ingested image or font by its `source` URL, straight from `html` or `css`: an `<img src>`, a CSS `url()` or an `@font-face` `src`. Before capture the renderer fetches each file and inlines it, so the page itself still makes no request.
+
+<!-- surface:cli -->
+Upload with `shotstack ingest upload`, or host a copy of a URL with `shotstack ingest fetch`:
+
+```sh
+PHOTO=$(shotstack ingest upload ./hero.jpg --watch --output json | tail -n1 | jq -r .source)
+FONT=$(shotstack ingest upload ./Brand.woff2 --watch --output json | tail -n1 | jq -r .source)
+```
+<!-- /surface -->
+
+```css
+@font-face { font-family: 'Brand'; src: url(<FONT>) format('woff2'); }
+.hero { background: url(<PHOTO>) center / cover; }
+```
+
+- **Same account and environment only.** A file ingested on `stage` works in `stage` renders, not in `v1`, and another account's files are refused. Every other remote URL is still blocked.
+- **10 MiB per file, 25 MiB per page.** A file counts once for every place the page references it, so reference a large image once (a CSS class, say) and reuse the class.
+- **Size images to the clip.** A photo much larger than the clip makes a heavier page and a slower capture. If the source has a WebP rendition named `html5-512`, `html5-1024`, `html5-2048` or `html5-4096`, the renderer uses the smallest one that covers the clip's longest edge; otherwise it uses the original.
+- **A file that can't be used fails the render**, for example one that's missing, too large, or not an image or font.
+- **Studio's preview doesn't load ingested files yet**, so they show as missing there. The render is unaffected.
+<!-- surface:cli -->
+- Until Studio supports them, check the page with `shotstack render <file> --env stage --watch`.
+<!-- /surface -->
 
 ### Fonts in HTML5
 
-`timeline.fonts[]` does **not** apply to `html5` assets (it loads fonts for `rich-text` / `rich-caption` only), and a remote `@font-face` URL (Google Fonts, etc.) is CSP-blocked. Two ways to get a custom font into an `html5` clip:
+`timeline.fonts[]` does **not** apply to `html5` assets (it loads fonts for `rich-text` / `rich-caption` only), and a remote `@font-face` URL (Google Fonts, etc.) is CSP-blocked. Three ways to get a custom font into an `html5` clip:
 
-1. **Inline it as a `data:` `@font-face`** — base64-encode the `.woff2` / `.ttf`:
+1. **Ingest it and use its URL** (see *Images and fonts you ingested*).
+   <!-- surface:cli -->
+   For a Google Font, `shotstack ingest fetch` the font file's `fonts.gstatic.com` URL and use the hosted copy.
+   <!-- /surface -->
+2. **Inline it as a `data:` `@font-face`** — base64-encode the `.woff2` / `.ttf`:
    ```css
    @font-face { font-family: 'Brand'; src: url('data:font/woff2;base64,<…>') format('woff2'); }
    .title { font-family: 'Brand', sans-serif; }
    ```
-2. **Use a system family** (`system-ui`, `Arial`, `Georgia`, …) — resolves with no load, but each machine picks its own font, so text in Studio's preview won't match the cloud render exactly. Embed a font whenever the text must match.
+3. **Use a system family** (`system-ui`, `Arial`, `Georgia`, …) — resolves with no load, but each machine picks its own font, so text in Studio's preview won't match the cloud render exactly. Embed a font whenever the text must match.
 
 An unresolved family silently falls back to the browser default — the render won't fail, but the text won't be your font. For a single styled line, a `rich-text` asset (which *does* use `timeline.fonts[]`; verified catalogue in `shared/agent-core.md`) is simpler than a `data:` font embed.
 

package/skills/shotstack/references/ingest.md

@@ -78,6 +78,13 @@ shotstack studio edit.json
 Remember `tracks[0]` is the **top** layer (see `shared/agent-core.md`), so the
 logo track sits above the video.
 
+## Images and fonts in an html5 page
+
+An `html5` page can use images and fonts you ingested by putting their
+`source` URLs in its `html` or `css` (`<img src>`, CSS `url()`, `@font-face`).
+The file must belong to the same account and environment as the render. Limits
+and details are in [`html5.md`](html5.md).
+
 ## Fetch a remote URL instead of uploading
 
 If the media is already at a URL but you want Shotstack to host its own copy

package/skills/shotstack/shared/agent-core.md

@@ -168,8 +168,9 @@ Pick `output.resolution` (preset) OR `output.size.width`+`output.size.height` (c
 | `sd` | 1024×576 @ 25 |
 | `hd` | 1280×720 @ 25 (default) |
 | `1080` | 1920×1080 @ 25 |
+| `4k` | 3840×2160 @ 25 (Pro, Scale and Volume plans) |
 
-Custom sizes must be divisible by 2.
+Custom sizes must be divisible by 2, up to 3840px on each side (1920px for `gif`). Video can be up to 3840×2160 pixels in any shape, for example 2160×3840 for vertical 4K; larger sizes are rejected. Video above 1920×1080 pixels needs a plan that includes 4K.
 
 ## Merge fields
 
@@ -231,7 +232,7 @@ Use only the **current** asset types; the deprecated ones still parse but should
 | `audio` | Audio clip placed at a specific time on the timeline, or AI-generated speech or music from a `prompt`. |
 | `rich-text` | Styled text overlay with full typography control. **Use this instead of `text`/`html`/`title`.** |
 | `svg` | Vector graphics from raw SVG markup: `src` starts with `<svg`, never a URL or `data:` URI (the render fails). See **`svg` assets** below. |
-| `html5` | Self-contained HTML/CSS/JS page rendered in an iframe (motion graphics, charts, animated overlays). Preloads gsap with its plugins (SplitText, DrawSVG, MorphSVG, MotionPath, Flip and more), d3, anime and lottie. See `references/html5.md`. **Never use the deprecated `html` asset.** |
+| `html5` | Self-contained HTML/CSS/JS page rendered in an iframe (motion graphics, charts, animated overlays). Preloads gsap with its plugins (SplitText, DrawSVG, MorphSVG, MotionPath, Flip and more), d3, anime and lottie. Images and fonts: the URL of a file you ingested, or a `data:` URI; other remote URLs are blocked. See `references/html5.md`. **Never use the deprecated `html` asset.** |
 | `rich-caption` | Word-level animated captions sourced from audio, video, or subtitle files. See `references/caption.md`. |
 | `luma` | Luma matte for masking effects. |