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
shotstack login        # prompts for your API key, saves it for future sessions
shotstack --help

Get an API key at app.shotstack.io. Stage credentials are free for testing. 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.

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

# Validate an Edit offline against the schema before spending credits.
shotstack validate edit.json

# 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).

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​