cueframe

Agent-native CLI for CueFrame — turn media into rendered video from the terminal. Every command speaks --json (an NDJSON event stream) and the binary self-describes via npx -y cueframe describe --json, so agents can drive it without guesswork.

Connects to the hosted CueFrame service — create an API key at app.cueframe.ai, or use npx -y cueframe login.

Run it

There is nothing to install. Every command in this README runs as npx -y cueframe … and is executable verbatim:

npx -y cueframe --help

npx -y cueframe install wires the CueFrame MCP server into every agent on your machine — but note it installs no binary: npx unpacks to an ephemeral cache and leaves nothing on your PATH. That is deliberate. npx re-resolves the current version on every call (~0.5s warm), so these commands can never go stale the way a pinned global install does.

Running many commands in a row and want to skip that overhead? Install it once and drop the npx -y prefix:

npm i -g cueframe               # optional — needs a user-writable npm prefix

This is an optimization, not the supported path. On a default Linux install it fails with EACCES: permission denied, mkdir '/usr/local/lib/node_modules/cueframe' unless you have configured an npm prefix in your home directory.

Authenticate

npx -y cueframe auth <cf_live_… key>        # static API key (CI / headless)
# or
npx -y cueframe login                       # OAuth device flow (browser)

The key can also be supplied via the CUEFRAME_API_KEY environment variable.

Quick start — upload → author → render

# 1. Register media (video / image / audio)
npx -y cueframe upload ./source.mp4 --json              # → mediaItemId

# 2. Create a project (sets aspect / format)
npx -y cueframe project create -n promo -a 9:16 --json  # → projectId

# 3. Author the composition — tracks of clips, per-clip reframe/trim,
#    optional captions. The composition is the source of truth.
npx -y cueframe composition put <projectId> -b @composition.json

# 4. Render the saved composition to MP4 (queues, SSE-watches, downloads)
npx -y cueframe render <projectId> -o out.mp4 --json

render takes only a project id and renders whatever composition is saved on it — no clip suggestion required. Run npx -y cueframe describe --json for the full composition schema and every command + flag.

Let CueFrame pick the clip (podcast → short)

npx -y cueframe upload ./long.mp4 --analyze --json                 # media + AI clip suggestions
npx -y cueframe clips <mediaItemId> --json                         # list suggestions (sug_…)
npx -y cueframe project create -n short -a 9:16 --from-suggestion <sug_…> --json
npx -y cueframe render <projectId> -o short.mp4 --json

Both paths converge on render; the suggestion on-ramp just authors the composition for you instead of you hand-writing it.

Package a recipe offline

cueframe recipe pack is an authoring command, separate from recipe run. It validates a prepared project draft and already-bundled component sources, calculates their canonical source versions, pins every component placement, and writes a portable version-4 .cueframe project. It needs no login, network, rendering runtime, or separately installed kernel. It does not compile or execute component code; preview the result in a compatible CueFrame runtime before publishing.

cueframe recipe pack --body @recipe-input.json --out recipe.cueframe --json
cueframe recipe pack --body @recipe-input.json --out recipe.cueframe --check --json
# --body @- accepts stdin; --dry-run validates without creating/replacing output.

The versioned input is { "version": 1, "project": { ... }, "components": [...] }:

• project is a version-4 project draft: id, name, explicit createdAt and modifiedAt, composition, pool, and recipe metadata. No timestamps are invented.
• recipe declares schemaVersion: 1, slug, one mediaSlots entry (the current recipe run --media contract), cloudBrandKit, and components metadata entries with componentId, name, category, and optional propSchema.
• components contains self-contained component-v2 source objects: { version: 2, componentId, tsxSource, manifest }. Bundle owned modules with esbuild and packages: 'external'; the CLI checks remaining imports against the authoritative runtime allowlist and enforces the recipe source-size limit.
• Omit authoredComponents, metadata sourceVersionId, and placement props.componentRef: the packer generates these consistently. Declare and bind required component assets to matching pool entries before packaging.

This is not an automatic exporter for arbitrary existing projects: authors explicitly choose the replaceable media and prepare the recipe metadata. Keep the generated artifact under version control; consumers can use it without rebuilding or installing the recipe's development dependencies.

Use a recipe with cueframe recipe run ./recipe.cueframe --media ./input.svg --no-render --json. That authenticated workflow uploads media, installs owned components, and creates an editable project. Omit --no-render for immediate rendering, or render the created project after previewing and editing it.

Wire it into your agents

npx -y cueframe install

Detects every agent on the machine — Claude Code, Cursor, Codex, VS Code, Windsurf, Zed, Antigravity CLI, Copilot CLI and more — and wires the CueFrame MCP server into each one's config. Auth happens on the agent's first call via a browser "Allow"; no API key.

It also copies the usage skills to ~/.claude/skills/. Only Claude Code reads that directory — every other agent gets the same verb surface as MCP tools from the server, so there is nothing further to install for them.

Claude Desktop and ChatGPT can't be wired from the command line (neither reads a local MCP config) — add https://api.cueframe.ai/v1/mcp as a custom connector instead.

For agents

• --json everywhere — NDJSON lifecycle: <verb>_prepare → <verb>_progress* → <verb>_complete | error, plus a non-zero exit on failure.
• npx -y cueframe describe --json — the full command tree as structured JSON.
• npx -y cueframe api <METHOD> <path> — raw escape hatch over the v1 API.

Common commands

| Need to… | Command | |---|---| | List projects | npx -y cueframe list | | Read a composition + ETag | npx -y cueframe composition get <projectId> --json | | Write a composition | npx -y cueframe composition put <projectId> -b @comp.json | | Export to Final Cut / Premiere | npx -y cueframe export fcpxml \| premiere <projectId> -s <sug_…> --wait -o cut.zip | | Validate without mutating | append --dry-run |

© CueFrame — AGPL-3.0-only. Commercial licences available.