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

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

Get an API key at [app.shotstack.io](https://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

```sh
# 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](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).

## Claude Code Skill

The CLI repo ships a [SKILL.md](https://github.com/shotstack/shotstack-cli/blob/main/SKILL.md) that teaches Claude Code how to use the CLI and how to author Edit JSON correctly.

```sh
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](/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