npm i -g cutsio

The footage backend for coding agents.

Semantic transcript search, one-command sync of mezzanine masters, and sidecar transcripts for RAG. Every read is JSON-friendly, every run is idempotent, and auth is a single API key — no browser, no OAuth.

Works withClaudeChatGPTCursorVS CodeOpenCodeClineWindsurfWarpGemini

npm install -g cutsio

Six commands. Footage in, answers out.

The agent loop: inventory, search, plan, materialize, publish back.

One API key. Or run cutsio login once and forget it.

export CUTSIO_API_KEY=ak_...

Inventory: folders, collections, videos. Pipe it anywhere.

cutsio list --json

Semantic transcript search. Timestamped chunks with similarity scores.

cutsio search "launch day crowd" --json --limit 5

Plan first. See what would download, change nothing.

cutsio sync --search "launch day" --out ./footage --transcripts --dry-run

Materialize: mezzanine masters + sidecar transcripts, resumable.

cutsio sync --search "launch day" --out ./footage --transcripts

Publish the finished cut back. 8 MB parts, 100 GB cap.

cutsio upload cut.mp4 --title "Final" --folder <folder-id>

Every command, scriptable.

--json on whoami, list, and search. --dry-run on sync and transcript. Exit 0 on success, 1 on failure, errors on stderr.

cutsio login

Verify the ak_… key and store it (macOS Keychain, or mode-600 config). Piped input works: key on line 1, workspace choice on line 2.

cutsio whoami

Identity card: user, key, workspace, scopes. Pass --json for the machine-readable version.

cutsio list

Browse without downloading. Collections, folder tree with counts, optional --videos. --json returns the raw manifest.

cutsio search

Semantic transcript search, limit 1–25. Up to 3 timestamped chunks per video; --json adds retrieval_mode and per-chunk similarity.

cutsio transcript

One transcript in vtt, srt, txt, or json. --dry-run prints to stdout — pipe straight into RAG.

cutsio sync

Incremental mirror of masters. Bare sync refuses — pick --all, --folder, --collection, --video, --search, --name, --unfiled, or --interactive. --transcripts adds sidecars.

cutsio upload

Multipart upload with progress. Reports processing as <video_id>.

CLI vs MCP server

MCP is OAuth inside your AI client — search and organize, no downloads
CLI is an API key in your terminal or CI — plus media downloads, transcript files, uploads
Use MCP to look around, the CLI to materialize footage for edits and RAG

MCP details live on the MCP server page.

Sync you can trust

Idempotent: only new or changed videos download
Resumable: interrupted transfers continue from the byte offset
State file per directory, scoped to one workspace
Nothing local is ever deleted by a sync
Files land as <Folder>/<Title> [<id8>].mp4

Questions.

How is this different from the MCP server?

MCP is OAuth in your AI client — search and organize, no downloads. The CLI is an API key in your terminal or CI — plus media downloads, transcript files, and uploads. Use MCP to look around, the CLI to materialize footage.

Do I need a browser?

No. Create one personal API key (Profile → API Keys), export CUTSIO_API_KEY, and every command works headless. login is a convenience, not a requirement.

Is it safe to re-run sync?

Yes. Sync tracks versions in <out>/.cutsio-state.json and downloads only what is new or changed. Interrupted transfers resume from the byte offset. Nothing local is ever deleted.

Can scripts parse the output?

Yes. whoami, list, and search accept --json. Status lines go to stderr when piped, so stdout is clean JSON. Exits are 0 success, 1 failure.

What are the limits?

Uploads cap at 100 GB per file in 8 MB parts. Search returns up to 25 results. 429/5xx responses retry with backoff; waits over 30s fail fast with a human message.

Read more: MCP Server · Media Asset Management · npm package

Give your agent the footage.

One API key, six commands, footage and transcripts wherever your pipeline runs.