# capcut-cli: build CapCut and JianYing drafts from the terminal, JSON in and JSON out > capcut-cli is an unofficial JavaScript CLI that creates and edits CapCut and JianYing draft projects by reading and writing the local draft store directly, with no API and no server. It produces real editable timelines rather than flattened exports, and it can be driven by an LLM agent through a skill or a queue runner. **renezander030/capcut-cli** — Independent, unofficial CLI to edit CapCut and JianYing (剪映) projects — subtitles, timing, speed, volume, templates, cut long-form to shorts. No API needed, reads draft_content.json and draft_info.json (剪映草稿) directly. Not affiliated with ByteDance. - Repository: https://github.com/renezander030/capcut-cli - Website: https://renezander.com/projects/capcut-cli - Stars: 944 · Forks: 98 - Language: JavaScript - License: MIT - Published: 2026-10-20 · Updated: 2026-10-20 · Language: en - Canonical page: https://hysenlabs.com/projects/renezander030-capcut-cli ## What it is for: drafts that stay editable instead of flattened exports capcut-cli is an independent, unofficial command line tool for CapCut and JianYing, the Chinese editor known as JianYing. Its stated purpose is to create and edit real projects from the terminal, or from an LLM agent, and to leave every track editable when you open the result. That distinction is the whole product. A rendering tool takes media and gives you a video file. This tool takes media and gives you a draft project, the same object CapCut itself opens, with video, audio and text on separate tracks. The documentation is blunt about where the line sits: the result is a real local project with video and captions on editable tracks, not a flattened export, you open it in CapCut or JianYing to review, adjust and render, and the publish click stays human. The commands follow the production pipeline. There is a `caption` command that produces styled captions, a `render` command that calls FFmpeg, a `translate` command, a `lint` command that checks a draft for problems, a `diff` command that shows what changed between two versions, and commands for cutting long-form footage into shorts. The description also mentions subtitles, timing, speed, volume and templates. The second audience is agent builders. The repository topics list agent skills, AI agents and a Claude Code plugin, and the tool is designed so a model has a deterministic boundary for inspecting and building drafts rather than free rein over the file system. ## The mechanism: the local draft store, read and written as JSON The architecture is defined by one decision: no API, no MCP server, no HTTP daemon, no upload. Every command reads and writes the local draft store directly. The project reads the CapCut and JianYing draft files, `draft_content.json` and `draft_info.json`, as its source of truth. The framing is JSON in, JSON out. One detail in the documentation is worth pulling out, because it is where a naive implementation would break: on newer CapCut versions the tool detects and synchronizes every readable timeline target instead of assuming `draft_content.json` is the only source of truth. The draft format is not a single file in current CapCut versions, and a tool that only reads one of them will silently miss content. The package manifest confirms the shape. The published entry points are `capcut` and `capcut-cli`, both pointing at `dist/index.js`, and the library entry is `./dist/lib.js` with type declarations alongside it. The `exports` map is minimal: the package root and `./package.json`. The `files` array ships `dist`, `docs`, `examples`, `templates` and both language versions of the README, and it lists the individual declaration files explicitly, which is what keeps the type surface of `loadDraft`, `lintDraft` and `saveDraft` intact for library users. The build step itself is a TypeScript compile followed by a small Node script that copies `src/enums.json` into the distribution as `dist/enums.json`, because the enum tables have to be available at runtime rather than baked into the compiled modules. There is also a Dockerfile in the repository, and its comments explain the packaging logic better than any marketing would: the final image is just Node plus the built output, because the package declares zero runtime dependencies. The build stage installs with `npm ci`, the runtime stage copies only `dist` and `templates`, and there is deliberately no `npm install` in the final stage. ## Installing it and producing a first draft in three commands The prerequisite is Node 18 or later, and the project states that it uses built-ins only, with no native modules. Optional tools unlock specific commands: Whisper for `caption`, FFmpeg for `render`, ffprobe for automatic media metadata, and an API key for `translate`. ```bash npm install -g capcut-cli ``` Then three commands make a first project, check the environment, and inspect the result. ```bash capcut doctor capcut quickstart my-first --video clip.mp4 --srt captions.srt capcut info ./my-first/ -H ``` `capcut doctor` is the diagnostic that reports on the optional tooling and the environment, so it is the sensible first thing to run. `quickstart` builds a project from a video file and a subtitle file, and `info` with the `-H` flag prints the details of the project you just built. If you would rather not install globally, the same binary runs through npx: ```bash npx capcut-cli ``` Building from source is documented in one line: clone the repository, install, build, then link so the `capcut` command is on your path. ```bash git clone https://github.com/renezander030/capcut-cli && cd capcut-cli && npm install && npm run build ``` There is also a Python wrapper published as `pip install capcut`, which wraps the same binary rather than reimplementing it, so a Python workflow ends up calling the same code rather than a parallel port. ## The version warning is the first thing to read, not the last The project documentation carries an important notice above the install instructions, and it is unusual enough to be worth quoting in substance rather than repeating in full. Fixture bundles made with versions up to 0.17.2 may contain stable device identifiers and must be treated as unsanitised. Versions up to 0.17.0 also contain local command and filter injection paths and unsafe temporary-file or credential-output behaviour. The documentation states that these issues are fixed in 0.18.0 and 0.17.1 respectively, and instructs upgrading with the latest tag and reading the changelog. That is a security notice about the tool's own history, and it has two practical consequences. The first is that an older install on a machine should be treated as untrusted, particularly if you have shared fixture bundles with colleagues, since those bundles may carry identifiers that tie back to the machine that made them. The second is that the tool writes files and shells out to external programs, so credential output and temporary file handling are not theoretical surfaces. A related design choice is visible in the optional Wasm package. The experimental `wasm/capcut-core` moves part of the JSON-in, JSON-out boundary into a WebAssembly Component with zero filesystem, network, environment, clock, random, stdio or process imports. Three read-only tools are exposed: `inspect`, which matches `capcut info` for valid drafts, `diff`, which matches `capcut diff` for structural changes, and `lint-portable`, which runs a parity-tested subset of `capcut lint` needing no host files or media probing. The stated purpose is a look-don't-touch mode for an assistant that needs to review a draft with the least possible access. The documentation also says plainly when to skip it, when you are driving the CLI yourself or want the AI to edit or render. ## Four ways in: CLI, library, queue runner and agent skill The tool can be consumed four ways, and the choice matters for how you would put it into a pipeline. The CLI is the obvious one, installed globally and invoked as `capcut `. The library route is the typed one: `import { loadDraft, lintDraft, saveDraft } from "capcut-cli"`, which the documentation describes as typed and zero-dependency. For a pipeline, the queue runner is `capcut serve`, which reads JSONL jobs from stdin and is aimed at automation platforms such as n8n, Make and Coze. The example directory confirms the shape with a file on serve automation and others on cutting to shorts, batch subtitle fixes, translating subtitles, keyframe pans and zooms, building a short from scratch, and verifying voice alignment. The agent route is the `capcut-edit` skill, installed with a single command that works across Claude Code, Codex, Cursor, OpenCode and the other agents the skills installer supports. ```bash npx skills add renezander030/capcut-cli ``` Claude Code can also load it as a plugin, using two slash commands. What the skill actually teaches is worth noting, because it is a design opinion about how agents should work. It covers every command, it teaches the progressive disclosure habit of inspecting first and never dumping a whole draft into a context window, it explains where the draft store lives on macOS and Windows, and it carries deterministic scripts for fades, Ken Burns effects and long-to-short cuts. It triggers on English and Chinese requests alike, including the Chinese terms for the editor, subtitles and drafts. The Docker image in the repository supports the queue route directly, with the draft directory mounted at runtime and a comment in the Dockerfile noting that `/work` is the conventional mount point. ## Where capcut-cli is the wrong tool The boundaries are clear once you understand the design. The first is that it does not publish. The documentation is explicit that the publish click stays human, and that the tool's job ends at producing a draft you can open, adjust and render. Anyone looking for an end-to-end automated posting pipeline will find the last step missing. The second is the unofficial status. The project states in its disclaimer that it is independent and community maintained, and not affiliated with, sponsored by or endorsed by CapCut, JianYing or ByteDance. CapCut and JianYing are trademarks of ByteDance. This matters in practice because the tool parses an undocumented internal format of someone else's application. The draft schema is not a published interface with a stability promise, so a CapCut release that changes the draft structure can break the tool, and the tool cannot ask the vendor to keep it stable. The third is the dependency on external tools for the heavier work. Whisper is needed for `caption`, FFmpeg for `render`, ffprobe for automatic media metadata and an API key for `translate`. The core tool has zero runtime dependencies, but a pipeline that assumes automatic captioning is really assuming a local Whisper install or a transcription step you run yourself. The fourth is platform shape. Node 18 or later is required, and the tool is installed globally or run through npx. There is no packaged binary for a machine without Node, and no documented behaviour on a machine where a global npm install is not permitted. The fifth is the Wasm tool's own limit. It is read-only and can examine only the project information handed to it, and the documentation says so directly: it cannot browse files, go online, read passwords or API keys, open other apps, or change the project. ## MIT licensed, released every week, and split across two languages The licence is MIT, and the disclaimer about trademark usage sits alongside it. Since CapCut and JianYing are trademarks of ByteDance and all product names and logos belong to their respective owners, being used only for identification, an MIT licence on this code does not grant any right over the editor itself or its format. That is a licensing reading rather than legal advice, and anyone planning a commercial deployment should confirm it themselves. Release cadence is fast and clearly stated in the tag names. v0.30.0 on 2026-10-16 brought per-command help, journal-checked undo and whisper.cpp word timings. v0.29.0 on 2026-10-09 added aligner word timings, reviewed batch plans and render fidelity and lint checks. v0.28.0 on 2026-10-04 added active timelines, app-created projects and client fixes. The last push was on 2026-10-19. Three minor releases in three weeks is a project moving quickly, and it is also a project whose changelog you should skim before each upgrade, since the security notice above is a reminder that behaviour has changed across those boundaries. The engineering setup backs the pace. The test script runs the build first and then the Node test runner with a spec reporter, there is a fast variant that skips the build, a package smoke test script for releases, and linting through Biome with separate check and fix targets. Formatting and linting are scoped to `src/` and `test/`. There is a Husky setup and a `.dockerignore`, and the root carries `CONTRIBUTING.md`, `CHANGELOG.md`, a `PLAN.md`, a `docs/` directory and a `skills/` directory. The Python wrapper is the notable structural choice. Rather than keeping one implementation, the project ships `pip install capcut` as a thin wrapper around the same binary, so Python users get the Node tool's behaviour with Python ergonomics and no duplicated logic to drift. ## Conclusion capcut-cli suits an editor or an automation pipeline that already has footage and captions and needs a real CapCut draft rather than a rendered file, and it suits agent builders who want a deterministic boundary for draft work. It does not suit someone who wants to publish without opening CapCut, since the publish step stays human, and it does not suit a workstation that cannot install a global npm package. Before adopting it, run `capcut doctor`, upgrade any install older than 0.18.0 because the project flags injection paths and unsanitised device identifiers in earlier fixture bundles, and confirm that the draft store location on your OS is what the tool expects. ## FAQ ### How do I install capcut-cli? Install it globally with `npm install -g capcut-cli` on Node 18 or later, or run it without installing using `npx capcut-cli `. Building from source means cloning the repository, running `npm install` and `npm run build`, then `npm link` to expose the `capcut` command. ### Does capcut-cli need an API to work with CapCut? No. Every command reads and writes the local draft store directly, so there is no API, no MCP server, no HTTP daemon and no upload. It works on the `draft_content.json` and `draft_info.json` files in the local draft store. ### What external tools does capcut-cli need? The core tool uses only Node built-ins, but optional tools unlock specific commands: Whisper for `caption`, FFmpeg for `render`, ffprobe for automatic media metadata, and an API key for `translate`. The `capcut doctor` command reports on the environment. ### Can an LLM agent drive capcut-cli safely? Yes, in two ways. The `capcut-edit` skill, installed with `npx skills add renezander030/capcut-cli`, teaches an agent every command with the habit of inspecting before acting. The optional experimental `wasm/capcut-core` package offers three read-only tools, `inspect`, `diff` and `lint-portable`, in a WebAssembly Component with no filesystem, network or environment access. ### Is capcut-cli affiliated with ByteDance or CapCut? No. The project states that it is independent and community maintained, and not affiliated with, sponsored by or endorsed by CapCut, JianYing or ByteDance. CapCut and JianYing are trademarks of ByteDance Ltd, used here only for identification. ## Sources - [License: MIT](https://github.com/renezander030/capcut-cli/blob/master/LICENSE) - [Project website](https://renezander.com/projects/capcut-cli) - [README](https://github.com/renezander030/capcut-cli/blob/master/README.md) - [Releases](https://github.com/renezander030/capcut-cli/releases) - [renezander030/capcut-cli on GitHub](https://github.com/renezander030/capcut-cli) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/renezander030-capcut-cli