feat: add URL shortening via share API to studio command

Author: dazzatronus

README.md

@@ -1,6 +1,6 @@
 # Shotstack CLI
 
-Command-line interface for the [Shotstack](https://shotstack.io) video rendering API. Built for humans and AI coding agents.
+Command-line interface for the [Shotstack](https://shotstack.io) video rendering API. Built for humans and AI agents.
 
 ```sh
 shotstack render template.json
@@ -16,7 +16,7 @@ npm i -g @shotstack/cli
 # one-shot via npx
 npx @shotstack/cli render template.json
 
-# one-shot via bun (~100x faster than npx for cached invocations)
+# one-shot via bun
 bunx @shotstack/cli render template.json
 ```
 
@@ -27,7 +27,7 @@ All three install paths use the same `@shotstack/cli` package on npm.
 Set your API key as an environment variable:
 
 ```sh
-export SHOTSTACK_API_KEY=sk_...
+export SHOTSTACK_API_KEY=...
 ```
 
 Get a key at <https://shotstack.io>.
@@ -69,23 +69,24 @@ shotstack status 01ja7-x8m2k-... --watch
 shotstack status 01ja7-x8m2k-... --output json
 ```
 
-### `shotstack preview <file>`
+### `shotstack studio <file>`
 
-Opens a `shotstack.studio` URL that loads the Edit JSON directly into the browser-based editor. No API call, no key, no charge — pure client-side encoding via the URL hash. Use it to hand a generated edit off to a human for review or quick tweaks before rendering.
+Opens a `shotstack.studio` URL that loads the Edit JSON in the browser-based editor. By default, posts the JSON to the share API and emits a short URL like `https://shotstack.studio/s/abc12345` — clean, shareable, expires in 30 days. Falls back to inline base64url encoding if the share API is unreachable.
+
+No render API key required; no render credits charged. Use to hand a generated edit off to a human for review or quick tweaks before rendering.
 
 ```sh
-shotstack preview my-template.json
-# → opens browser silently
+shotstack studio my-template.json
+# → opens browser silently with https://shotstack.studio/s/<slug>
 
-shotstack preview my-template.json --copy        # also copies URL to clipboard
-shotstack preview my-template.json --no-open     # print URL, don't open browser
-shotstack preview my-template.json --output json # emit {"url":"..."} on stdout
+shotstack studio my-template.json --copy        # also copies URL to clipboard
+shotstack studio my-template.json --no-open     # print URL, don't open browser
+shotstack studio my-template.json --no-shorten  # emit base64url inline (offline / debug)
+shotstack studio my-template.json --output json # emit {"url":"...","shortened":true} on stdout
 ```
 
 When a browser can be launched, the command is silent — the URL only opens in the browser. On a headless server (no `$DISPLAY`, no `xdg-open`), the URL is printed to stdout instead so you can copy it elsewhere.
 
-Templates whose encoded URL exceeds ~6KB print a stderr warning. Browser URL limits vary; if you regularly exceed it, host the JSON publicly and link to it via `https://shotstack.studio/#src=<https-url>`.
-
 ### `shotstack feedback`
 
 Opens a pre-filled GitHub issue with a sanitised dossier of your last 5 CLI invocations (render IDs, errors, exit codes). API keys and signed URLs are stripped at write time. You review and submit in your browser; nothing is transmitted automatically. Inspect the log at `~/.shotstack/log.jsonl`.

SKILL.md

@@ -47,16 +47,19 @@ shotstack status 01ja7-x8m2k-39rzv-cmvxve --watch
 
 ## Hand-off to a human before rendering
 
-When a human is in the loop and may want to tweak the result, prefer **`shotstack preview <file>`** over `shotstack render`. By default it opens the browser to `https://shotstack.studio/#json=<base64url>` and prints the URL — the timeline loads directly into the browser-based editor. No API call, no key, no charge. The human can play, edit, and decide whether to render — saving credits when the AI's first attempt isn't quite right.
+When a human is in the loop and may want to tweak the result, prefer **`shotstack studio <file>`** over `shotstack render`. By default it posts the JSON to the share API and opens `https://shotstack.studio/s/<slug>` in the browser — a short, shareable URL. No API key, no render credits charged. The human can play, edit, and decide whether to render.
 
 ```sh
-shotstack preview template.json              # opens browser + prints URL
-shotstack preview template.json --no-open    # headless: just print the URL
-shotstack preview template.json --output json # piping: {"url":"..."}, no browser
+shotstack studio template.json              # opens browser + prints short URL
+shotstack studio template.json --no-open    # headless: just print the URL
+shotstack studio template.json --no-shorten # emit base64url URL inline (offline / debug)
+shotstack studio template.json --output json # piping: {"url":"...","shortened":true}, no browser
 ```
 
 On headless systems (no `xdg-open`, no `$DISPLAY`) the browser launch silently no-ops; the URL is still printed. Safe to run anywhere.
 
+If the share API is unreachable, the command falls back to the inline base64url form automatically and prints a stderr warning. Shares expire after 30 days.
+
 Use `render` only when you're confident the JSON is final, or there's no human to review.
 
 ## Four CLI rules
@@ -67,7 +70,7 @@ Use `render` only when you're confident the JSON is final, or there's no human t
 
 3. **Fetch the current schema and docs before generating Edit JSON.** The Shotstack API evolves; LLM training data is often stale. Pull <https://shotstack.io/docs/api/api.edit.json> and <https://shotstack.io/docs/guide/llms-full.txt> for the current schema and guides before composing an Edit from scratch.
 
-4. **Hand off to a human via `preview` when uncertain.** Don't burn render credits iterating. Generate JSON → `shotstack preview` → human reviews/tweaks → render only when right.
+4. **Hand off to a human via `studio` when uncertain.** Don't burn render credits iterating. Generate JSON → `shotstack studio` → human reviews/tweaks → render only when right.
 
 ## Authoring Edit JSON
 
@@ -100,8 +103,8 @@ Authoritative sources, in order of preference:
 
 This skill ships sub-references for the gnarly bits:
 
-- [`references/timeline.md`](references/timeline.md) — track layering, transitions, soundtrack vs audio
-- [`references/rich-caption.md`](references/rich-caption.md) — sizing per resolution, default style, the 5 named presets, alias pattern
+- [`references/timeline.md`](references/timeline.md) — track layering, transitions, background music via audio assets
+- [`references/caption.md`](references/caption.md) — sizing per resolution, default style, the 5 named presets, alias pattern (asset type: `rich-caption`)
 - [`references/svg.md`](references/svg.md) — required attrs, supported elements
 - [`references/fonts.md`](references/fonts.md) — built-in fonts, Google Fonts URL pattern, custom-font workflow
 - [`references/asset-library.md`](references/asset-library.md) — placeholder videos, images, music

package.json

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

references/asset-library.md

@@ -30,7 +30,7 @@ https://shotstack-assets.s3.amazonaws.com/images/waterfall.jpeg
 
 ## Music
 
-Royalty-free tracks from the Unminus library, hosted on Shotstack's CDN. Suitable for `timeline.soundtrack` or as audio assets.
+Royalty-free tracks from the Unminus library, hosted on Shotstack's CDN. Use as `audio` assets on a dedicated track. (`timeline.soundtrack` is deprecated — use `audio` with `length: "end"` instead.)
 
 ```
 https://shotstack-assets.s3.amazonaws.com/music/unminus/white.mp3

references/rich-caption.md references/caption.mdreferences/rich-caption.md renamed to references/caption.md

@@ -1,7 +1,9 @@
-# Rich-caption guide
+# Caption guide
 
 Word-level animated captions. The most failure-prone asset type — read this fully before composing one.
 
+The asset type to use is **`rich-caption`** (Shotstack's name for word-level captions). The deprecated `caption` type still parses but produces inferior output — always use `rich-caption`.
+
 ## Contents
 
 - The five named presets (use these verbatim when possible)
@@ -182,7 +184,7 @@ Rich-caption transcribes audio to produce word-level timing. Three ways to sourc
 | `src` value | Behaviour |
 |---|---|
 | `alias://<name>` | Auto-transcribe a referenced audio/video/text-to-speech clip. Set `alias: "<name>"` on the source clip. **Preferred for sync.** |
-| Subtitle file URL | Use existing `.srt`, `.vtt`, `.ttml`, or `.dfxp` file. No auto-transcription. |
+| Subtitle file URL | Use existing `.srt` or `.vtt` file. No auto-transcription. |
 | Audio/video file URL | Auto-transcribe a standalone media file. Use when there's no source clip on the timeline. |
 
 The `alias://` form keeps the captions in sync with the source clip even when you change its `start` or `length`.

references/fonts.md

@@ -1,6 +1,6 @@
 # Fonts guide
 
-The Shotstack render engine ships a small built-in font set; everything else must be loaded as a custom font via `timeline.fonts[]`. Per the [Shotstack docs](https://shotstack.io/docs/guide/architecting-an-application/rich-text/#custom-fonts), **prefer custom Google Fonts** for predictable rendering and full typographic range.
+The Shotstack render engine ships a small built-in font set; everything else must be loaded as a custom font via `timeline.fonts[]`. Per the [Shotstack docs](https://shotstack.io/docs/guide/architecting-an-application/rich-text.md), **prefer custom Google Fonts** for predictable rendering and full typographic range.
 
 ## Contents
 

references/svg.md

@@ -57,46 +57,97 @@ Standard fill, stroke, and transform attributes work: `fill`, `fill-opacity`, `s
 
 Animated SVGs are not rendered — only the static initial frame is used.
 
-## Worked example: lower-third bar
+## Worked example: speech bubble for a testimonial
+
+Speech bubbles are an example "rich-text can't do this" case — a rounded body with a tail pointing at the speaker requires a `<path>`. Pair the SVG bubble with a `rich-text` clip for the quote inside it.
 
 ```json
 {
   "timeline": {
     "tracks": [
       {
-        "clips": [{
-          "asset": {
-            "type": "rich-text",
-            "text": "Jane Smith — CEO",
-            "font": { "family": "JTUSjIg1_i6t8kCHKm45xW5rygbi49c", "size": 48, "color": "#ffffff" }
-          },
-          "start": 0, "length": 5,
-          "offset": { "x": -0.2, "y": -0.35 }
-        }]
+        "clips": [
+          {
+            "asset": {
+              "type": "rich-text",
+              "text": "This changed our workflow completely.",
+              "font": {
+                "family": "JTUSjIg1_i6t8kCHKm45xW5rygbi49c",
+                "size": 44,
+                "color": "#0f172a",
+                "weight": 600
+              },
+              "align": {
+                "horizontal": "center",
+                "vertical": "middle"
+              }
+            },
+            "start": 0.5,
+            "length": 4,
+            "width": 540,
+            "height": 160,
+            "offset": {
+              "x": 0.235,
+              "y": 0.373
+            }
+          }
+        ]
       },
       {
-        "clips": [{
-          "asset": {
-            "type": "svg",
-            "src": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 1920 200\" width=\"1920\" height=\"200\"><rect x=\"0\" y=\"0\" width=\"1920\" height=\"200\" fill=\"#000000\" fill-opacity=\"0.7\"/></svg>"
-          },
-          "start": 0, "length": 5,
-          "offset": { "x": 0, "y": -0.35 }
-        }]
+        "clips": [
+          {
+            "asset": {
+              "type": "svg",
+              "src": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 600 220\" width=\"600\" height=\"220\"><path d=\"M 40 0 H 560 Q 600 0 600 40 V 140 Q 600 180 560 180 H 200 L 160 220 L 170 180 H 40 Q 0 180 0 140 V 40 Q 0 0 40 0 Z\" fill=\"#ffffff\" stroke=\"#0f172a\" stroke-width=\"4\"/></svg>"
+            },
+            "start": 0.5,
+            "length": 4,
+            "width": 600,
+            "height": 220,
+            "offset": {
+              "x": 0.235,
+              "y": 0.356
+            },
+            "transition": {
+              "in": "fade",
+              "out": "fade"
+            }
+          }
+        ]
       },
       {
-        "clips": [{
-          "asset": { "type": "video", "src": "https://shotstack-assets.s3.amazonaws.com/footage/beach.mp4" },
-          "start": 0, "length": 5
-        }]
+        "clips": [
+          {
+            "asset": {
+              "type": "image",
+              "src": "https://shotstack-assets.s3.amazonaws.com/images/business-man.jpg"
+            },
+            "start": 0,
+            "length": 5,
+            "fit": "crop"
+          }
+        ]
       }
     ]
   },
-  "output": { "format": "mp4", "resolution": "1080" }
+  "output": {
+    "format": "mp4",
+    "resolution": "1080"
+  }
 }
 ```
 
-Track order: text on top, semi-transparent black bar in the middle, video on the bottom.
+Track order: rich-text quote on top, SVG bubble in the middle, talking-head video at the bottom. The `<path>` `d` attribute draws a rounded rectangle (40px corner radius via `Q` curves) with a triangular tail at the bottom pointing toward the speaker. `stroke` gives the bubble an outline; `fill="#ffffff"` makes the body opaque.
+
+Position the bubble with `offset` so the tail points at the subject's head. Adjust the path's tail coordinates (`L 160 220 L 170 180`) to point left/right/up depending on where the speaker is in frame.
+
+Other patterns SVG is right for:
+
+- **Tutorial highlight rings** — `<circle>` with `fill="none"` and a thick `stroke`, positioned over a UI element.
+- **Brand badges** — small geometric lockups using `<rect>`/`<polygon>` plus `transform`.
+- **Decorative dividers** — wavy lines or geometric frames between scenes.
+
+If you only need a coloured rectangle behind text, **don't reach for SVG** — `rich-text` already supports `background.color`/`opacity`/`borderRadius`. Reserve SVG for shapes rich-text can't produce.
 
 ## When to use SVG vs rich-text
 

references/timeline.md

@@ -1,6 +1,6 @@
 # Timeline conventions
 
-Detailed guide to track layering, the soundtrack vs audio distinction, and `timeline.fonts[]`. Read this when building any non-trivial Edit JSON.
+Detailed guide to track layering, background music (via `audio` assets — `timeline.soundtrack` is deprecated), and `timeline.fonts[]`. Read this when building any non-trivial Edit JSON.
 
 ## Contents
 
@@ -17,7 +17,7 @@ The single most counter-intuitive Shotstack convention.
 
 `timeline.tracks` is an array. **The first element is the TOP layer (foreground); the last is the BOTTOM (background).** The order of the JSON array IS the visual stacking order, top-to-bottom.
 
-Per the [official docs](https://shotstack.io/docs/guide/architecting-an-application/guidelines/):
+Per the [official docs](https://shotstack.io/docs/guide/getting-started/core-concepts.md):
 
 > Tracks are layered on top of each other in the same order they are added to the array with the top most track layered over the top of those below it.
 
@@ -72,25 +72,32 @@ If you put the video first and the captions last, the video covers the captions
 | Title card on video | Title clip in early track, video in later track |
 | Picture-in-picture | PiP video in early track, main video in later track |
 
-## Soundtrack vs audio asset
+## Background music: use `audio`, not `timeline.soundtrack`
 
-Prefer `Audio` assets — they support custom timing, keyframes, and effects, and can do everything `timeline.soundtrack` can. Use `timeline.soundtrack` only when you want a single background track spanning the whole edit.
+`timeline.soundtrack` is **deprecated**. Always use an `audio` asset on its own track with `length: "end"`. The audio asset path supports keyframes, custom timing, multi-clip mixing, and the full effect set; soundtrack does not.
 
 ```json
 {
   "timeline": {
-    "soundtrack": {
-      "src": "https://shotstack-assets.s3.amazonaws.com/music/unminus/palmtrees.mp3",
-      "effect": "fadeOut"
-    },
-    "tracks": [/* ... */]
+    "tracks": [
+      /* ...other tracks... */
+      {
+        "clips": [{
+          "asset": {
+            "type": "audio",
+            "src": "https://shotstack-assets.s3.amazonaws.com/music/unminus/palmtrees.mp3",
+            "effect": "fadeOut"
+          },
+          "start": 0,
+          "length": "end"
+        }]
+      }
+    ]
   }
 }
 ```
 
-`soundtrack.effect` accepts `fadeIn`, `fadeOut`, or `fadeInFadeOut`.
-
-An `audio` clip with `length: "end"` is functionally identical to `timeline.soundtrack`.
+`asset.effect` on audio accepts `fadeIn`, `fadeOut`, or `fadeInFadeOut` (same enum the deprecated soundtrack used).
 
 ## `timeline.fonts[]` for custom fonts
 
@@ -127,7 +134,7 @@ See `references/fonts.md` for the full pattern.
 
 ## Common track-layout patterns
 
-**Slideshow:** images in one track, soundtrack for music. One image per clip; use `start: "auto"` to chain them.
+**Slideshow:** images in one track, an `audio` asset on a separate track with `length: "end"` for the background music. One image per clip; use `start: "auto"` to chain them.
 
 **Voiceover with captions:** captions in track[0], audio in track[1] (with `alias` for the captions to reference), video/image in track[2].
 

references/troubleshooting.md

@@ -61,7 +61,7 @@ You used a font name that isn't in the built-in list and didn't load it via `tim
 
 A `rich-caption` clip without `width`, `height`, and `fit: "none"` defaults to filling the entire output.
 
-**Fix:** use one of the five named presets in `references/rich-caption.md` (Nico, Kai, Kapow, Lovely Little Lychee, Rizz) which include the right dimensions, or set `width`/`height`/`fit: "none"` explicitly on your clip.
+**Fix:** use one of the five named presets in `references/caption.md` (Nico, Kai, Kapow, Lovely Little Lychee, Rizz) which include the right dimensions, or set `width`/`height`/`fit: "none"` explicitly on your clip.
 
 ## Timeline renders but layers are wrong