capcut-edit

capcut-cli

English | 中文

Create and edit real CapCut / JianYing projects from the terminal — or any LLM agent.

Open the result in CapCut with every track still editable. capcut-cli works directly on the local draft store: JSON in, JSON out, with no upload, API, MCP server, or HTTP daemon.

Also from the maintainer: 500 Years Frozen in Time: The Inca Children Mystery, a 14:49 documentary from Bronze Age Banter.

raw recording → silence-aware cuts + styled captions → editable CapCut / JianYing draft

▶ Captioned output example (60 seconds)

https://github.com/user-attachments/assets/4e6ee99c-0745-4cfb-8e9b-ad873fb1259b

Install and open your first editable draft

Prerequisites: Node ≥ 18 (built-ins only — no native modules). Optional tools unlock specific commands: Whisper for caption, FFmpeg for render, ffprobe for automatic media metadata, and ANTHROPIC_API_KEY for translate.

npm install -g capcut-cli

From Python: pip install capcut wraps the same binary — capcut.run("quickstart", "my-short", video="clip.mp4", ratio="9:16") — see python/README.md.

capcut doctor
capcut quickstart my-first --video clip.mp4 --srt captions.srt
capcut info ./my-first/ -H

Result: a real local project with video and captions on editable tracks — not a flattened export. Open it in CapCut or JianYing to review, adjust, and render. The publish click stays human.

Useful? Star capcut-cli to help other editors and agent builders find it.

For more practical tools for AI agents, from video automation to checks before they ship, follow René on GitHub.

Build from source instead: git clone https://github.com/renezander030/capcut-cli && cd capcut-cli && npm install && npm run build (then npm link to expose capcut). Or run any command without installing: npx capcut-cli <command>.

[!IMPORTANT] Upgrade before using older versions. Fixture bundles made with versions up to 0.17.2 may contain stable device identifiers and must be treated as unsanitised (#59). Versions up to 0.17.0 also contain local command/filter injection paths and unsafe temporary-file or credential-output behaviour. These issues are fixed in 0.18.0 and 0.17.1 respectively. Run npm install -g capcut-cli@latest and see the changelog for full details.

Disclaimer: This is an independent, community-maintained project. It is not affiliated with, sponsored by, or endorsed by CapCut, JianYing, or ByteDance Ltd. "CapCut" and "JianYing" (剪映) are trademarks of ByteDance Ltd. All product names, logos, and brands are the property of their respective owners and are used here only for identification (nominative) purposes.

An independent CLI for CapCut / JianYing that any LLM agent can drive — zero dependencies, no server, both namespaces in one binary.

JSON in, JSON out: every command reads and writes the local draft store directly, with no MCP server or HTTP daemon. On newer CapCut versions it detects and synchronizes every readable timeline target instead of assuming draft_content.json is the only source of truth. That gives any model (Claude, DeepSeek, GLM, Kimi) a deterministic boundary for inspection, building, subtitles, captions, translation, and long-form cuts.

Use it four ways:

• CLI — npm install -g capcut-cli, then capcut <command> <project>
• Library — import { loadDraft, lintDraft, saveDraft } from "capcut-cli" (typed, zero-dep)
• Queue runner — capcut serve reads JSONL jobs from stdin, for n8n / Make / Coze
• Agent sandbox (experimental) — build capcut-core.wasm for three read-only MCP tools with zero filesystem, network, environment, clock, random, stdio, or process imports

Give your agent the skill

One command installs the capcut-edit skill into Claude Code, Codex, Cursor, OpenCode and the other agents the skills installer supports:

npx skills add renezander030/capcut-cli

Claude Code can also load it as a plugin:

/plugin marketplace add renezander030/capcut-cli
/plugin install capcut-cli@capcut-cli

The skill teaches the agent every command, the progressive-disclosure habit (inspect first, never dump a whole draft), where the draft store lives on macOS and Windows, and the deterministic scripts for fades, Ken Burns and long-to-short cuts. It triggers on English and Chinese requests alike (剪映, 字幕, 草稿).

Capability-free Wasm tools for agents

Using an AI assistant with capcut-cli? Give it a safer “look, don’t touch” mode.

The optional Wasm tool lets an AI:

• describe what is inside a CapCut project;
• show what changed between two versions; and
• spot common timeline and caption problems.

It can examine only the project information you hand to it. It cannot browse your files, go online, read passwords or API keys, open other apps, or change the project.

Use it when you want an AI to review a draft with the least possible access. Skip it when you are using capcut-cli yourself or want the AI to edit or render—the normal CLI still does those jobs. This feature is experimental, optional, and changes nothing unless you set it up. Technical details and setup →

The experimental wasm/capcut-core source package moves the deterministic, JSON-in/JSON-out boundary into a WebAssembly Component:

• inspect matches capcut info for valid drafts.
• diff matches capcut diff for structural changes.
• lint-portable runs an explicit, parity-tested subset of capcut lint that needs no host files or media probing.

The host reads a draft and passes its JSON as tool input. The component itself has no ambient capabilities, and CI proves the built world has zero imports before exercising all three functions through Wassette over MCP. From a source checkout, build it with npm --prefix wasm/capcut-core ci && npm run wasm:verify; setup and security details are in the component README.

Release notes

Unreleased: repeated cuts of the same video or audio reuse content hashes within a process, avoiding full-file reads for every segment. Changed files are checked again, and filename collisions still compare content. See #155.

New in v0.30.0: per-command help (capcut <command> --help, capcut help <command>); undo that survives an app save, with every restore checked against the write journal (restore, restore --list integrity); and real word timings from whisper.c