framecompose
v1.0.0
Published
Build, edit and render editable FrameCompose video projects from your terminal or an AI coding agent: JSON recipe to multi-track timeline, one-second edits, MP4 render.
Maintainers
Readme
FrameCompose CLI
Build, edit and render real, editable video projects from your terminal or your AI coding agent.
Point framecompose at a folder of clips and a JSON recipe and it builds a full
FrameCompose project: clips, transitions, camera moves,
voiceover, word-timed captions, music that ducks under speech, sound effects and an end card.
Open it in the browser editor, fix anything by hand, change any scene from the terminal in
about a second, and render the MP4.
Works with Claude Code, Cursor, OpenAI Codex, Gemini CLI, GitHub Copilot agent mode and any
other agent that can run a command. Every command speaks --json and returns a fixed exit code.
Install
Needs Node.js 20 or newer.
npm install -g framecomposeOr run any command once without installing: npx framecompose --help.
Sign in
- Create a free API key at https://www.framecompose.com/settings/api-keys (every plan, the free plan included). It is shown once.
- Run
framecompose loginand paste it. Input is hidden, and the key is saved only on this computer, readable by your user account alone.
framecompose login
framecompose whoamiFor CI or an agent sandbox, set FRAMECOMPOSE_API_KEY instead, or pipe the key in with
framecompose login --key-stdin. The key is never accepted as a command-line argument, so it
never lands in your shell history.
Your first video
framecompose validate recipe.json # free, no account needed: checks the recipe and files
framecompose build recipe.json --dry-run # free: uploads, plans and prints the credit estimate
framecompose build recipe.json --live # builds it; watch it assemble in the open editor
framecompose render <projectId> --wait --out video.mp4 # Pro or any credit packOn the free plan, open the project link the build prints and export it free from the browser
editor instead of render.
A minimal recipe.json:
{
"schema": "framecompose.recipe/v1",
"title": "My first FrameCompose video",
"aspectRatio": "9:16",
"transitions": "CROSSFADE",
"clips": [
{ "asset": "./clips/intro.mp4", "trimEnd": 5, "motion": "ken_burns" },
{ "asset": "./clips/main.mp4", "trimStart": 2, "trimEnd": 12 }
],
"captions": { "mode": "synced", "preset": "hormozi" },
"music": { "query": "upbeat", "volume": 0.35, "duck": true },
"endCard": { "text": "Made with FrameCompose" }
}Full recipe reference: https://www.framecompose.com/json-to-video.
Edit without rebuilding
framecompose inspect <projectId>
framecompose edit <projectId> --scene 1 --trim-end 4.5 --transition CROSSFADE
framecompose edit <projectId> --captions --font-family Montserrat --animation pop
framecompose checkpoint save <projectId> before-recut
framecompose undo <projectId>Free tools: highlights, cut-silence, auto-reframe, score, analyze-beats,
analyze-shots, montage and cut-on-beat.
Catalogs: transitions, effects, motions, caption-styles, voices, music, sfx.
Run framecompose --help or framecompose <command> --help for every option.
For AI agents
- Add
--jsonto any command for one JSON document on stdout. - Exit codes: 0 ok, 1 error, 2 usage, 3 auth, 4 not found, 5 invalid input, 6 conflict, 7 credits or plan, 8 network or server, 9 render failed, 10 timed out.
- Always dry-run first and pass
--max-creditsto cap spending. - Never ask the person for their API key in chat: they run
framecompose loginthemselves.
Pricing
The CLI and API keys are free. Dry runs, edits and the analysis tools cost no credits. AI narration uses credits, shown in the dry run before anything is spent. Server renders currently cost no credits with Pro or any credit pack (packs from $5.99 once), and exporting from the browser editor is free on every plan. See https://www.framecompose.com/pricing.
Security
- Keys reach only the features this CLI uses. They can build, edit and render your projects, but cannot delete projects, run the AI editor chat, touch billing, manage keys or delete your account.
- Revoke a key at any time on the API keys page; it stops working at once.
- The CLI sends your key only to the FrameCompose API over HTTPS and refuses to follow a redirect to any other host.
- It refuses to upload files that are not media (for example private keys,
.envfiles or web pages saved under a video name). - No install scripts and no runtime dependencies.
Found a security problem? Email [email protected].
Links
- Guide: https://www.framecompose.com/cli
- AI agents: https://www.framecompose.com/ai-agent-video-editor
- JSON to video: https://www.framecompose.com/json-to-video
- Terms: https://www.framecompose.com/terms
