framlit

framlit is the command-line + MCP server for the Framlit AI video ad platform (web app at https://framlit.app). Same naming convention as aws / gh / vercel — the brand IS the CLI tool. The web app is a separate, closed product; this npm package only talks to its public /api/mcp/* endpoints. MIT licensed, PRs welcome.

CLI for Framlit — AI-powered video generation. Generate Remotion videos from your terminal, edit them as JSON scenes, and render via AWS Lambda. Ships an MCP server for Claude / Cursor / VS Code on the side.

npm install -g framlit
framlit login
framlit generate "Logo animation with rotating text"

Why a CLI

The CLI is the canonical surface for everything programmatic: CI pipelines, cron jobs, scripted renders, and coding agents that design videos as JSON. The web app handles visual editing; the CLI handles everything you want to automate.

• Composable: every command supports --output json (auto when piped) + --json '<payload>' for raw JSON-RPC-style input.
• Streamable: long-running calls (render status --poll) emit NDJSON status frames you can pipe through jq.
• Safe to script: every mutating command supports --dry-run. Strict input validation rejects path traversal, control chars, ID injection.
• Self-describing: framlit schema returns JSON Schema for every tool — no man pages to scrape.
• One binary, two protocols: same install (npm i -g framlit) ships both the framlit CLI and the framlit-mcp server.

Install

# Prerequisites: Node 18+

npm install -g framlit
framlit login                  # opens browser, saves ~/.framlit/config
framlit whoami                 # email · plan · credits

Or set an env var (precedence over framlit login — handy for CI / containers):

export FRAMLIT_API_KEY=fml_xxx  # create at https://framlit.app/developers

Commands

# Generate / modify
framlit generate "Product demo with fade-in text" --format portrait
framlit modify --code ./video.tsx --instruction "Change background to blue"

# Projects
framlit projects list
framlit projects get <id>
framlit projects create "My Video" --code ./video.tsx
framlit projects update <id> --name "New Name"

# Render (single video)
framlit render <projectId>
framlit render status <renderId> --poll          # NDJSON until done

# Narrated ads — script + voiceover + word-synced visuals (Pro, v0.7+)
framlit narration generate "Built for runners who hate stiff shoes"
framlit narration cap                        # current month usage / cap
framlit narration stages <projectId> --format md > narration.md

# Scenes — design the video as JSON, edit it in Framlit (v0.11+, 0 credits)
framlit scene create --file scene.json --name "Launch"
framlit scene get <projectId> > scene.json        # includes edits made in the editor
framlit scene create --file scene.json --project <projectId>

# Brand DNA (v0.7+)
framlit brand get
framlit brand set --json-file brand.json     # Free: name + 3 colors only

# Discovery
framlit templates --category social
framlit credits
framlit schema                                    # all tools
framlit schema framlit_generate_code              # JSON Schema for one tool

Run framlit help for the full reference.

Agent-friendly conventions

Flag	Behavior
--output json|text	Force output mode. Auto-JSON when stdout is piped.
--json '<payload>' or --json - (stdin)	Raw JSON-RPC-style input — bypasses bespoke flags, maps 1:1 to tool schema.
--json-file <path>	Read the same JSON payload from disk. Path-traversal validated.
--fields "data.id,data.name"	Client-side projection. Shrinks the JSON response to just these dot-paths so big list/get responses don't blow up your context. Supports items[].id array projection.
--sanitize	Strip known prompt-injection markers from text inputs (brief, prompt, instruction) before dispatching. Reports stripped lines on stderr. Opt-in.
--image-gen (generate only)	Force AI product image generation. Adds 3 cr (default flux-schnell) or 12 cr (--image-gen-model gpt-image-2). Use when prompt mentions a product but no image is attached — prevents hallucinated URLs / CSS-painted placeholders. v0.9.0+.
--dry-run	Validate + preview a mutating call without executing. Works without an API key.
--poll	NDJSON status stream until terminal state. On render status.
framlit schema [tool]	Runtime JSON Schema introspection for agents.

For agents loading the CLI as a tool, ship these alongside your harness:

• SKILL.md — invariants and happy-path patterns
• CONTEXT.md — vocabulary, services, security model
• AGENTS.md — README-for-AI entry point

The MCP server can be subset to keep tool count small:

# Only load narration + scene + brand tools (7/18) to save prompt tokens
npx framlit-mcp --services narration,scene,brand
# or via env:
FRAMLIT_MCP_SERVICES=scene,brand npx framlit-mcp

Errors go to stderr as JSON when output is JSON:

{ "error": { "code": "VALIDATION_ERROR", "message": "..." } }

Exit codes: 0 success · 1 general · 2 invalid args / validation · 3 auth required · 4 API error.

MCP server (for IDE integration)

The same package ships an MCP server. Add to your IDE's config:

{
  "mcpServers": {
    "framlit": {
      "command": "npx",
      "args": ["framlit-mcp"],
      "env": { "FRAMLIT_API_KEY": "fml_your_api_key_here" }
    }
  }
}

Works with Cursor (.cursor/mcp.json), Claude Desktop (claude_desktop_config.json), VS Code, Windsurf. Every CLI command above is also exposed as an MCP tool — same handlers, same auth, same credits.

Back-compat note: This package was renamed framlit-mcp → framlit in v0.5.0. Existing configs invoking npx framlit-mcp keep working — the framlit package still ships the framlit-mcp binary as an alias.

Tools

All tools below are available as both CLI commands and MCP tools.

Tool	CLI	Credits
framlit_generate_code	framlit generate	1
framlit_modify_code	framlit modify	1
framlit_list_projects	framlit projects list	0
framlit_get_project	framlit projects get	0
framlit_create_project	framlit projects create	0
framlit_update_project	framlit projects update	0
framlit_render_video	framlit render	0
framlit_get_render_status	framlit render status	0
framlit_list_templates	framlit templates	0
framlit_get_credits	framlit credits	0
framlit_preview_code	framlit preview	0
framlit_create_scene	framlit scene create	0
framlit_get_scene	framlit scene get	0
framlit_generate_narrated_ad	framlit narration generate	3 (Pro)
framlit_get_narration_cap	framlit narration cap	0
framlit_get_narrated_ad_stages	framlit narration stages	0
framlit_get_brand	framlit brand get	0
framlit_set_brand	framlit brand set	0

Pricing

CLI and MCP use the same credit system as the Framlit web app — see framlit.app/docs/pricing for current limits and prices. Free plan videos include a watermark; Editor Pro and Studio don't.

Development

npm install
npm run dev:cli -- generate "test"        # CLI in watch mode
npm run dev                               # MCP server in watch mode
npm run build
npm test

Environment

Variable	Description
FRAMLIT_API_KEY	Your API key. Overrides framlit login config.
FRAMLIT_API_URL	Custom API URL (for local development).

Links

• framlit.app · Developers · Pricing · API Keys

License

MIT