@shotstack/cli 0.4.1 → 0.5.0

package/README.md

@@ -24,7 +24,16 @@ All three install paths use the same `@shotstack/cli` package on npm.
 
 ## Authentication
 
-Set your API key as an environment variable:
+Save your API key once with `shotstack login`. It's stored in `~/.shotstack/credentials.json`, keyed per environment:
+
+```sh
+shotstack login                  # prompts for the key (hidden), saves the v1 key
+shotstack login --env stage      # save the stage key
+echo "$KEY" | shotstack login    # non-interactive: read the key from stdin (CI/agents)
+shotstack logout [--env <name>]  # remove a saved key (--all removes every env)
+```
+
+Alternatively, set an environment variable, which **overrides** any saved key:
 
 ```sh
 export SHOTSTACK_API_KEY=...
@@ -46,6 +55,8 @@ shotstack render template.json --env stage
 SHOTSTACK_ENV=stage shotstack render template.json
 ```
 
+The `ingest` commands target the parallel `https://api.shotstack.io/ingest/{env}` base with the same API key.
+
 ## Commands
 
 ### `shotstack render <file>`
@@ -87,6 +98,38 @@ shotstack studio my-template.json --output json # emit {"url":"...","shortened":
 
 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.
 
+### `shotstack ingest <subcommand>`
+
+Uploads your own local files (or fetches remote URLs) via the [Ingest API](https://shotstack.io/docs/guide/ingesting-footage/ingest-api/) and hosts them on Shotstack so they can be referenced from an Edit. An Edit can only reference media by URL, so this is how you get a local clip, image, audio file, or font into a render.
+
+```sh
+# Upload a local file; --watch polls until ready and prints the hosted URL.
+shotstack ingest upload ./clip.mp4 --watch
+# → ready  https://shotstack-ingest-api-v1-sources.s3.ap-southeast-2.amazonaws.com/.../source.mp4
+
+shotstack ingest upload ./clip.mp4 --output json   # returns {"id":"..."} immediately (no URL yet)
+shotstack ingest fetch https://example.com/v.mp4 --watch   # host a copy of a remote URL
+shotstack ingest status <source-id> --watch        # poll an existing source
+shotstack ingest list --output json                # list ingested sources
+shotstack ingest delete <source-id>                # remove a source from storage
+```
+
+Sources are stored until you delete them. The bare `upload`/`fetch` commands return only an id — use `--watch` (or `ingest status`) to get the hosted URL once ingestion is `ready`.
+
+### `shotstack login` / `shotstack logout`
+
+Saves (or removes) your API key so it persists across shell sessions. Keys are stored per environment in `~/.shotstack/credentials.json`.
+
+```sh
+shotstack login                  # prompt, save the v1 (production) key
+shotstack login --env stage      # save the stage key
+echo "$KEY" | shotstack login --env v1   # non-interactive (CI / agents)
+shotstack logout --env stage     # remove the stage key
+shotstack logout --all           # remove every saved key
+```
+
+The `SHOTSTACK_API_KEY` env var always takes precedence over a saved key, so CI and automation are unaffected.
+
 ### `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`.

package/SKILL.md

@@ -1,9 +1,10 @@
 ---
 name: shotstack
 description: |
-  Render video and poll render status via the Shotstack API.
-  Use when generating clips, building automated video pipelines, or orchestrating
-  cloud video renders from a script, agent, or CI workflow.
+  Render video, poll render status, and upload local source files via the
+  Shotstack API. Use when generating clips, building automated video pipelines,
+  uploading footage/audio/images to use in an Edit, or orchestrating cloud video
+  renders from a script, agent, or CI workflow.
   NOT for: real-time streaming, or live broadcasting.
 license: Apache-2.0
 ---
@@ -12,15 +13,28 @@ license: Apache-2.0
 
 This skill loads in **terminal-based AI agents** (Claude Code, Cursor, Codex CLI, Gemini CLI, etc.). All operations here are shell commands. There is no embedded UI, no iframe, no inline canvas, no MCP tool surface — only `shotstack` invocations from a terminal. To hand off to a human, run `shotstack studio <file>`; this opens the user's default browser to a `shotstack.studio` URL. Tell the user to click Render *in the browser tab*, not in any UI inside the terminal.
 
-Two commands for the Shotstack video rendering API. `render` submits an Edit JSON and returns a render ID; `status` polls a render until done.
+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.
+
+**Default loop — no API key required:** compose → `validate` (offline lint) → `studio` (browser preview). Only the API-backed commands (`render`, `status`, `ingest`) 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
 
+Save your API key once with `shotstack login` — it's stored in `~/.shotstack/credentials.json` (chmod 600), per environment, so you don't re-enter it every session:
+
+```sh
+shotstack login                  # prompts (hidden input); saves the v1 (production) key
+shotstack login --env stage      # save the stage key (Shotstack keys are env-specific)
+echo "$KEY" | shotstack login    # non-interactive (CI / agents): read the key from stdin
+shotstack logout --env stage     # forget one env;  shotstack logout --all  forgets all
+```
+
+Or set an environment variable (overrides the saved key — best for CI):
+
 ```sh
 export SHOTSTACK_API_KEY=...
 ```
 
-Get a key at <https://app.shotstack.io>. Without a key, every command exits with code 1.
+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`) require one; without a key *those* exit 1, while compose → validate → studio keeps working.
 
 ## Environments
 
@@ -29,27 +43,49 @@ Get a key at <https://app.shotstack.io>. Without a key, every command exits with
 --env v1       → https://api.shotstack.io/edit/v1      (production, default)
 ```
 
-Use `--env stage` for experimentation. Stage is free; v1 charges real credits. Override with `SHOTSTACK_ENV` env var for the session.
+**The cheapest iteration path is `studio` — not `stage`.** `studio` previews client-side in the browser with no key and no credits (see the Studio section below); iterate there. `--env stage` gives a free cloud render (With watermark) for when you need a rendered video for review; v1 charges real credits. Override the target with the `SHOTSTACK_ENV` env var for the session. `ingest` commands hit the parallel `…/ingest/{env}` base automatically using the same key.
 
 ## Quickstart
 
 ```sh
-# Submit + poll in one command (most agent flows want this).
+# 1 — Validate offline. Schema + same-track overlaps + fonts + URLs. No key, no credits.
+shotstack validate template.json
+
+# 2 — Preview in the browser. The DEFAULT next step: no key, no credits; a human hits Render.
+shotstack studio template.json
+# → opens https://shotstack.studio/s/<slug> and prints the short URL
+
+# 3 — Export to MP4. Needs an API key and charges credits. Submit + poll in one command.
 shotstack render template.json --watch
 # → done  https://shotstack-api-v1-output.s3.amazonaws.com/.../01ja7-x8m2k-39rzv-cmvxve.mp4
 
-# Submit only (returns ID).
-shotstack render template.json --output json
-# → {"id":"01ja7-x8m2k-39rzv-cmvxve"}
-
-# Poll an existing render to terminal state.
+# Poll an existing render to a terminal state.
 shotstack status 01ja7-x8m2k-39rzv-cmvxve --watch
 # → done  https://shotstack-api-v1-output.s3.amazonaws.com/.../01ja7-x8m2k-39rzv-cmvxve.mp4
 ```
 
-## Hand-off to a human before rendering
+## Uploading local files to use in an Edit
+
+An Edit can only reference media by **URL** — a local path in an `asset.src` will not render. To use a local file, host it first with `shotstack ingest upload`, then put the returned URL in your Edit.
+
+```sh
+# Upload a local file and poll until it's hosted. --watch prints the URL.
+shotstack ingest upload ./clip.mp4 --watch --output json
+# → {"id":"zzytey4v-...","status":"importing"}
+# → {"id":"zzytey4v-...","status":"ready","source":"https://shotstack-ingest-api-v1-sources.s3...amazonaws.com/.../source.mp4",...}
+
+# Capture the hosted URL straight into a variable:
+SRC=$(shotstack ingest upload ./clip.mp4 --watch --output json | tail -n1 | jq -r .source)
+# …then reference "$SRC" as an asset.src in your Edit JSON and run `shotstack render`.
+```
+
+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.**
+
+## Default workflow: preview in Studio (no key, no credits)
 
-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.
+**`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.
 
 ```sh
 shotstack studio template.json              # opens browser + prints short URL
@@ -62,7 +98,7 @@ On headless systems (no `xdg-open`, no `$DISPLAY`) the browser launch silently n
 
 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.
+**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".
 
 ## Four CLI rules
 
@@ -70,7 +106,7 @@ Use `render` only when you're confident the JSON is final, or there's no human t
 
 2. **Use `--watch`, not a polling loop.** `shotstack render <file> --watch` submits and polls in one shot; `shotstack status <id> --watch` polls an existing render. Both exit when terminal: `done` (exit 0) or `failed` (exit 1). Don't write `while true; do ...; sleep 3; done`.
 
-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.
+3. **Compose from `shared/agent-core.md`, then `shotstack validate`.** Its cheatsheet carries the property names, enums (transition/effect/position/fit) and rich-text fields you need — no schema download required. `shotstack validate <file>` then checks the JSON against the live schema offline and flags same-track overlaps, unloaded fonts and non-public URLs before you spend a credit. (For edge cases the full schema is at <https://shotstack.io/docs/api/api.edit.json> and the guide at <https://shotstack.io/docs/guide/llms-full.txt>.)
 
 4. **Hand off to a human via `shotstack studio <file>` when uncertain.** Don't burn render credits iterating. Generate JSON → `shotstack studio file.json` (opens browser) → human reviews/tweaks → render only when right.
 
@@ -113,9 +149,13 @@ Authoritative sources, in order of preference:
 
 This skill ships sub-references for the gnarly bits:
 
+- [`references/ingest.md`](references/ingest.md) — uploading local files (and fetching URLs) so they can be used in an Edit: the upload→render workflow, `--watch`, status values, supported types
 - [`references/timeline.md`](references/timeline.md) — track layering, transitions, background music via audio assets
+- [`references/positioning.md`](references/positioning.md) — coordinate model, `position`/`offset` (fraction of frame, +y up), clip bounding box & `fit`, text sizing, transform order
 - [`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/html5.md`](references/html5.md) — HTML5 asset: fields, preloaded libs (gsap/d3/anime/lottie), browser harness, sizing, worked examples
+- [`references/html5-snippets.md`](references/html5-snippets.md) — copy-paste motion-graphic clips: kinetic headline, count-up/price odometer, shine sweep, pulsing CTA, film grain
 - [`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
 - [`references/troubleshooting.md`](references/troubleshooting.md) — common errors and fixes