feat: Shotstack CLI v0.1 — render, status, feedback, flight recorder, JS bundle, release workflow

Author: Derk Zomer

.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,22 @@
+name: Bug, feature request, or question
+description: Report an issue, request a feature, or ask a question.
+labels: ["needs-triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Tip: run `shotstack feedback` from your terminal to pre-fill this form with your environment and a sanitised dossier of your last 5 CLI invocations. Review the pre-filled body in your browser before submitting.
+  - type: textarea
+    id: details
+    attributes:
+      label: Details
+      description: Describe the bug, feature request, or question. If you used `shotstack feedback`, the dossier will appear here automatically.
+      placeholder: |
+        ## Environment
+        - Shotstack CLI: 0.1.x
+        - OS: ...
+
+        ## What I expected vs what happened
+        ...
+    validations:
+      required: true

.github/workflows/release.yml

@@ -0,0 +1,26 @@
+name: Release
+
+on:
+  push:
+    tags: ['v*']
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          registry-url: 'https://registry.npmjs.org'
+      - run: npm install -g npm@latest
+      - run: bun install --frozen-lockfile
+      - run: bun run typecheck
+      - run: bun test
+      - run: bun run build
+      - run: npm publish --provenance

.gitignore

@@ -0,0 +1,8 @@
+node_modules/
+dist/
+.env
+.env.*
+*.log
+.DS_Store
+.idea/
+.vscode/

README.md

@@ -0,0 +1,107 @@
+# Shotstack CLI
+
+Command-line interface for the [Shotstack](https://shotstack.io) video rendering API. Built for humans and AI coding agents.
+
+```sh
+shotstack render template.json
+shotstack status <render-id> --watch
+```
+
+## Install
+
+```sh
+# npm (global)
+npm i -g @shotstack/cli
+
+# one-shot via npx
+npx @shotstack/cli render template.json
+
+# one-shot via bun (~100x faster than npx for cached invocations)
+bunx @shotstack/cli render template.json
+```
+
+All three install paths use the same `@shotstack/cli` package on npm.
+
+## Authentication
+
+Set your API key as an environment variable:
+
+```sh
+export SHOTSTACK_API_KEY=sk_...
+```
+
+Get a key at <https://shotstack.io>.
+
+## Environments
+
+Pick the API environment with `--env` or `SHOTSTACK_ENV`. Defaults to `v1` (production).
+
+| `--env` | Endpoint |
+|---|---|
+| `stage` | `https://api.shotstack.io/edit/stage` |
+| `v1` (default) | `https://api.shotstack.io/edit/v1` |
+
+```sh
+shotstack render template.json --env stage
+SHOTSTACK_ENV=stage shotstack render template.json
+```
+
+## Commands
+
+### `shotstack render <file>`
+
+Submits a Shotstack Edit JSON to the render API. Returns a render ID.
+
+```sh
+shotstack render my-template.json
+shotstack render my-template.json --output json
+```
+
+### `shotstack status <id>`
+
+Polls the render status. Use `--watch` to poll continuously until the render completes.
+
+```sh
+shotstack status 01ja7-x8m2k-...
+shotstack status 01ja7-x8m2k-... --watch
+shotstack status 01ja7-x8m2k-... --output json
+```
+
+### `shotstack feedback`
+
+Opens a pre-filled GitHub issue with a sanitised dossier of your last 5 CLI invocations (render IDs, errors, exit codes). API keys and signed URLs are stripped at write time. You review and submit in your browser; nothing is transmitted automatically. Inspect the log at `~/.shotstack/log.jsonl`.
+
+## Output
+
+Default is human-readable. Pass `--output json` for machine-readable output. Exit codes:
+
+- `0` success
+- `1` permanent error (4xx, validation, missing API key)
+- `2` transient/retryable error (5xx, network)
+
+## For AI agents
+
+This repo ships a [`SKILL.md`](./SKILL.md) at the root, following the [Agent Skills open standard](https://agentskills.io). Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, and 50+ other agents.
+
+```sh
+npx skills add shotstack/shotstack-cli
+```
+
+The skill loads at session start (~50-100 tokens metadata) and teaches the agent three things `--help` doesn't:
+
+- Always pass `--output json` when piping
+- Use `shotstack status --watch` instead of writing a polling loop
+- Fetch the current timeline schema from <https://shotstack.io/docs/llms.txt> before submitting
+
+## Telemetry
+
+Every API request includes two headers so we can split CLI traffic in dashboards:
+
+- `x-shotstack-origin: cli`
+- `x-shotstack-environment: stage | v1`
+
+No other data is sent. The CLI never phones home; it only talks to the Shotstack API.
+
+## Licence
+
+Apache 2.0.