Skip to main content

Shotstack CLI

View on GitHub npm version

A terminal-native CLI for the Shotstack Edit API plus a Claude Code Skill packaging the same conventions for IDE-based coding agents.

Install​

npm install -g @shotstack/cli
npx skills add shotstack/shotstack-cli

The skill works in any agent that supports Agent Skills, including Claude Code, Cursor, Codex CLI and Gemini CLI.

Keep the CLI and skill current​

The CLI and skill are updated often. Each release improves the authoring rules, motion guidance and caption presets your agent follows, and that shows in the videos it makes. Check for a new release before you start:

shotstack --version                    # the version you have
npm view @shotstack/cli version        # the latest release
npm install -g @shotstack/cli@latest   # update the CLI
npx skills update shotstack -y         # update the skill

Try it without an API key​

Writing, checking and previewing an edit needs no key and no credits:

shotstack validate edit.json   # offline: schema, overlapping clips, fonts and media URLs
shotstack studio edit.json     # opens the edit at https://shotstack.studio/s/abc12345

New to this? Follow the quickstart.

Add your API key​

Rendering, generating, ingesting and templates need a key. Get one at app.shotstack.io, then:

shotstack login        # prompts for your API key, saves it for future sessions

shotstack login stores the key per environment in ~/.shotstack/credentials.json (chmod 600). Prefer env vars for CI? export SHOTSTACK_API_KEY=... works too and takes precedence over the stored key. Renders in the stage environment are free and watermarked.

shotstack studio makes a short https://shotstack.studio/s/{slug} link. With an API key saved for the --env you use, or in SHOTSTACK_API_KEY, the link is permanent. Without one it lasts 30 days, and the CLI tells you so. --no-shorten prints a long link that carries the edit itself instead.

Each link is a snapshot: edits made after opening it never change it, and sharing again makes a new link. Links copied in Studio follow the same rule. Signed in, they're permanent. Signed out, they last 30 days, and signing up in the same browser keeps the links it made.

Commands​

# Render an Edit JSON and poll until done.
shotstack render edit.json --watch
# → done  https://shotstack-api-...-e21df7168d9a.mp4

# Poll an existing render.
shotstack status <renderId> --watch

# Save an edit as a template, then list, fetch, update or delete templates.
shotstack template create edit.json --name "Product promo"
shotstack template list
shotstack template get <id>          # e.g. a template a person designed in Studio
shotstack template update <id> edit.json
shotstack template delete <id>

# List generation models, or print the options one accepts.
shotstack models
shotstack models <modelId>

# Generate one asset from a prompt. --quote prints the cost without charging.
shotstack generate <modelId> "<prompt>" --quote
shotstack generate <modelId> "<prompt>" --watch

# Bring your own local files into a render via the Ingest API.
shotstack ingest upload ./clip.mp4 --watch
# → ready  https://shotstack-ingest-api-v1-sources.s3.../source.mp4
shotstack ingest fetch https://example.com/v.mp4 --watch
shotstack ingest list --output json

Every command accepts --env stage|v1 (defaults to v1) and --output json for machine-readable output. Full reference: the CLI README.

Five CLI rules for agents​

  1. Pipe → --output json. Default output is human-readable; pass --output json when scripting.
  2. Use --watch, not a polling loop. render, status, and ingest upload|fetch|status accept --watch and exit on terminal state.
  3. Validate before rendering. Run shotstack validate <file> to catch schema errors offline — no API call, no credits.
  4. Fetch the schema before composing JSON. Pull api.edit.json and the conventions — LLM training data is often stale.
  5. Hand off to a human via studio when uncertain. Don't burn render credits iterating; let a human click Render after reviewing.

Exit codes: 0 success, 1 permanent error, 2 transient (safe to retry).

The skill​

The CLI repo ships a SKILL.md that teaches your agent how to use the CLI and how to author Edit JSON correctly. Your agent reads it on demand, and its references/ (timeline layering, caption presets, SVG constraints, fonts, asset library, troubleshooting) load only when relevant.

Conventions are shared with the MCP server​

The skill's shared/agent-core.md is the same content the MCP server returns from its get_shotstack_guide tool, and the same content rendered at /agents/conventions.

Reference​