# Shotstack CLI

[![View on GitHub](https://img.shields.io/badge/GitHub-View_on_GitHub-blue?logo=github)](https://github.com/shotstack/shotstack-cli)
[![npm version](https://img.shields.io/npm/v/@shotstack/cli.svg)](https://www.npmjs.com/package/@shotstack/cli)

A terminal-native CLI for the Shotstack Edit API plus a [Claude Code Skill](https://docs.claude.com/en/docs/claude-code/skills) packaging the same conventions for IDE-based coding agents.

## Install

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

The skill works in any agent that supports [Agent Skills](https://docs.claude.com/en/docs/claude-code/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:

```sh
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:

```sh
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](/getting-started/quickstart-agent).

## Add your API key

Rendering, generating, ingesting and templates need a key. Get one at [app.shotstack.io](https://app.shotstack.io), then:

```sh
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.

## Commands

```sh
# 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](https://github.com/shotstack/shotstack-cli#commands).

## 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`](https://shotstack.io/docs/api/api.edit.json) and the [conventions](/agents/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](https://github.com/shotstack/shotstack-cli/blob/master/skills/shotstack/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](/agents/mcp-server) returns from its `get_shotstack_guide` tool, and the same content rendered at [`/agents/conventions`](/agents/conventions).

## Reference

- [CLI on GitHub](https://github.com/shotstack/shotstack-cli) — full command reference, changelog, source
- [CLI on npm](https://www.npmjs.com/package/@shotstack/cli) — current version, install
- [Edit JSON conventions](/agents/conventions) — track ordering, asset types, font allowlist
- [Edit API schema](https://shotstack.io/docs/api/api.edit.json) — `api.edit.json`, the source of truth for the JSON shape
- [Ingest API guide](/ingesting-footage/ingest-api/) — what `shotstack ingest` wraps
- [Edit API reference](https://shotstack.io/docs/api/) — full REST API for the underlying service