Skip to main content

Shotstack CLI

View on GitHub npm version

Beta

The Shotstack CLI and Claude Code Skill are currently in beta. Commands and conventions may change without notice.

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
export SHOTSTACK_API_KEY=...
shotstack --help

Get an API key at app.shotstack.io. Stage credentials are free for testing.

Two commands​

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

# Open a draft in Studio for a human to review (no render credits).
shotstack studio edit.json
# → opens browser at https://shotstack.studio/s/abc12345

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

Four 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. Both render and status accept --watch and exit on terminal state.
  3. Fetch the schema before composing JSON. Pull api.edit.json and the conventions — LLM training data is often stale.
  4. 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).

Claude Code Skill​

The CLI repo ships a SKILL.md that teaches Claude Code how to use the CLI and how to author Edit JSON correctly.

npx skills add shotstack/shotstack-cli

Once installed, Claude Code reads the skill on demand — references in references/ (timeline layering, caption presets, SVG constraints, fonts, asset library, troubleshooting) load only when relevant.

The skill works with any Anthropic Skills-compatible client.

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​