@shotstack/cli 0.11.0 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shotstack/cli",
-  "version": "0.11.0",
+  "version": "0.13.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.11.0** and needs `@shotstack/cli` **0.11.0** or later. Before the first `shotstack` command in a session:
+This skill is version **0.13.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.11.0, tell the user: what this skill documents, such as `analyze`, 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
 
@@ -123,18 +123,19 @@ shotstack generate seedance-2.0-text-to-video "Waves break over black sand at du
 
 ## Default workflow: preview in Studio (no key, no credits)
 
-**`shotstack studio <file>` is the default way to look at an edit** — prefer it over `render` unless you specifically need a cloud-exported MP4. It posts the JSON to https://shotstack.studio and opens `https://shotstack.studio/s/<slug>` in the browser — a short, shareable URL. No API key, no render credits charged; it previews client-side, so it works with no key. The human plays, edits, and decides whether to spend credits on a render.
+**`shotstack studio <file>` is the default way to look at an edit** — prefer it over `render` unless you specifically need a cloud-exported MP4. It posts the JSON to https://shotstack.studio and opens `https://shotstack.studio/s/<slug>` in the browser — a short, shareable URL. No render credits charged; it previews client-side, so it works with no key (a key only makes the short link permanent). The human plays, edits, and decides whether to spend credits on a render.
 
 ```sh
 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 --env stage  # share with the saved stage key
 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.
+**The short link is permanent when the CLI has an API key** (`SHOTSTACK_API_KEY`, or the key saved for `--env`/`SHOTSTACK_ENV`). Without one it lasts 30 days and the command says so on stderr; suggest `shotstack login` if the user wants links that last. A timeout, 429 or 5xx gets one retry, then the command falls back to the inline base64url form and prints the cause on stderr. If the share API refuses the edit (over 1 MB, missing `timeline` or `output`, or an invalid key), the command exits 1 with the reason: fix that, or use `--no-shorten`.
 
 **Default to `studio` for anything non-trivial** — multi-scene, multi-track, or any creative an interested human will review. It previews client-side, costs nothing, and lets the human hit Render when it's right. Use `render` directly only for single-shot/simple edits, automated pipelines, or when told "just render it".
 

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

@@ -18,7 +18,7 @@ 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.
+It needs an API key (`shotstack login`). The `src` must be a direct, public link to an audio or video file: share pages and redirects are refused.
 <!-- surface:cli -->
 ```sh
 shotstack analyze https://shotstack-assets.s3.amazonaws.com/music/unminus/lit.mp3 --output json > map.json