Two commands that close the two biggest gaps in a headless CapCut workflow: seeing the result of an edit, and authoring a whole draft in one shot. No breaking changes; still zero npm-dep and JSON-by-default. ffmpeg is an opt-in shell-out (only when actually rendering), the same pattern caption uses for whisper.

Preview

• render — a low-res ffmpeg proxy preview of a draft, so you can watch an edit without opening CapCut. Flattens the main video track (per-segment source trim + speed), scales to a proxy size (--scale, default 0.5), mixes every audio-track segment, and optionally burns text in with --burn-captions. It is a preview, not CapCut's final render (no multi-track compositing/effects). The ffmpeg command is built by a pure, deterministic buildRenderPlan that is unit-tested without invoking ffmpeg; --dry-run prints that plan and needs no ffmpeg. Read-only.

  capcut render ./my-short --burn-captions # -> ./my-short/preview.mp4
  capcut render ./my-short --dry-run # print the ffmpeg plan, run nothing

Build

• compile — builds a whole draft from a declarative JSON spec (the inverse of describe): instead of chaining dozens of mutating add-* commands, emit one spec and compile constructs the draft atomically via the same factory functions the imperative commands use. Times in seconds; media paths resolve relative to the spec. The full spec is validated — and every media file checked to exist — before anything is written, so a bad spec fails clean. Writes both draft_content.json and draft_info.json so every downstream command reads the same data.

  capcut compile ./short.json --out ./my-short

12 new tests; full suite 171/171. Merged in #29.

Install: npm install -g capcut-cli@0.10.0

Ten new commands/capabilities across inspection, maintenance, composition, and agent integration. No breaking changes; still zero-dep, JSON-by-default, pipeable.

Inspect & agents

• describe — full command surface as JSON, so LLM/agent callers get a tool spec instead of scraping --help.
• timeline — track/segment layout in the terminal (JSON, or -H ASCII bars).
• projects — list CapCut/JianYing draft folders on disk by name (no more UUID paths).

Maintain & compose

• prune — remove unreferenced materials (unions material_id + extra_material_refs[], so indirect refs survive).
• relink — repair broken media paths (--dir basename match or --from/--to prefix).
• diff — compare two drafts (segments + materials added/removed/changed).
• concat — append one draft onto another's timeline, id-collision-safe.

Safety & config

• Multi-step undo — rolling snapshot history; restore --step N / --list.
• config — .capcutrc defaults (drafts/jianying/cols); capcut config shows resolved values.
• Windows export --batch — PowerShell + SendKeys (Ctrl+E) path now ships.

Closes #17. 30 new tests; full suite 159/159.

Install: npm install -g capcut-cli@0.9.0
Full changelog: https://github.com/renezander030/capcut-cli/blob/master/CHANGELOG.md

Safety, discoverability, and a long-overdue track-order fix. No breaking changes; still zero-dep, JSON-by-default, pipeable.

Added

• Global --dry-run (#15) — every draft-mutating command can now preview: prints the normal JSON result with "dryRun":true, but leaves the draft and its .bak untouched.
• restore (#16) — capcut restore <project> undoes the last write from .bak (single-step). Honors --dry-run.
• Shell completions (#18–#20) — capcut completions <bash|zsh|fish>.

Fixed

• Track order scrambled on import (#21) — saveDraft now normalizes the tracks array to CapCut's canonical layer order (video → audio → overlays → text) on every save.

Docs / Internal

• README: from-source install, Prerequisites, v0.4/v0.5 command examples, Troubleshooting table; new CONTRIBUTING.md.
• Pre-commit hook rebuilds dist/ before tests (#23).

Install: npm install -g capcut-cli@0.8.0

Full changelog: https://github.com/renezander030/capcut-cli/blob/master/CHANGELOG.md

Distribution and integration release. No breaking changes; everything stays zero-dep, JSON-by-default, pipeable.

Added

• capcut doctor — environment preflight (Node, whisper, ANTHROPIC_API_KEY, draft dir)
• Importable Node library — import { loadDraft, lintDraft, saveDraft, detectVersion, runDoctor } from "capcut-cli"
• Dockerfile (zero-dep multi-stage image) + GitHub Action (uses: renezander030/capcut-cli@v0.6 to lint drafts in CI)
• 3 new templates: caption-pop, lower-third, hook-question (6 total)

CI / Quality

• CI matrix across Node 18/20/22 + Biome lint on push/PR
• Fuzz/injection suite for malformed draft_content.json; 113 tests pass

Thanks to @Wladefant for the plugin-install fix (#2).

Full changelog: CHANGELOG.md

Contributors

• @Wladefant

Six new commands voted in from Discussion #1, shipped as a single release. All keep the zero-dep, JSON-by-default, pipeable design.

What's new

• capcut mix-mode <segment-id> <mode> — blend mode on a video segment (12 modes: multiply, screen, overlay, soft-light, hard-light, color-dodge, color-burn, darken, lighten, difference, exclusion, normal). Writes mix_mode on the video material.
• capcut audio-fade <segment-id> [--in <sec>] [--fade-out <sec>] — real materials.audio_fades[] entry on an audio segment (not volume keyframes). Re-applying replaces; stacking is refused.
• capcut add-cover <image-path> [--time <ms>] — set the draft's cover frame (thumbnail) to a local image. Populates the cover object on the draft root (was null in every template).
• capcut add-filter <slug> <start> <duration> + capcut enums --filters — colour filter on a dedicated filter track. 10-slug starter catalogue (capcut) or 468 slugs via --jianying.
• capcut bubble-text <text-segment-id> --bubble <slug> + capcut enums --bubbles — speech-bubble shape on a text segment. 7-slug starter catalogue plus --effect-id / --resource-id passthrough.
• capcut import-ass <ass-path-or--> — ASS / SSA subtitle import alongside import-srt. Zero-dep parser; shares all import-srt flags.

Fixed

• Piped stdin (spawn(...).stdin) now works for keyframe --batch, import-srt, serve queue — was throwing ENXIO: no such device or address. Switched readFileSync("/dev/stdin", ...) → readFileSync(0, ...).
• capcut init falls back to a bundled minimal template at templates/_init/ when the upstream ../CapCutAPI/template directory isn't present.

Test suite

60 → 91 passing tests across 53 suites (one new test file per command). Husky pre-commit gate stayed green throughout the v0.5 cycle.

Install

```bash
npm install -g capcut-cli@0.5.0
```

Full diff: v0.4.0...v0.5.0

What's new

Hero claim: the CapCut/JianYing toolkit that survives the next ByteDance update — and auto-captions with real caption objects.

Version resilience (the niche bend)

• version — detect CapCut/JianYing version + schema flags (mask_field, text_ranges, audio_fades) + support status
• lint — schema-aware checks: caption overlaps (error), line length, cue duration, missing material refs, missing local files. Exit codes 0/1/2 for CI
• migrate — apply known schema migrations (mask ↔ common_masks across the JianYing 5.9 / CapCut 9.6 boundary)
• decrypt — JianYing 6.0+ encryption detection + clear workaround UX (decryption algorithm intentionally not bundled)

Caption factory

• caption — whisper shell-out → real caption-track segments with sub_type + caption_template_info (addresses pyJianYingDraft #148 — no more text-segment mimics)
• translate — Anthropic-API multi-language draft clone, zero runtime deps (uses built-in fetch). --dry-run for safe inspection; original draft stays untouched

Ecosystem unlocks

• add-sfx — first-class sound effects on a dedicated track (audio_effects enum)
• chroma — green-screen / chroma key on video segments (--color + --intensity, or --off)
• serve — stateless JSONL queue runner. No daemon, no port, no shared state — unlocks n8n / Coze / Make / cron without becoming a service
• export --batch — EXPERIMENTAL UI-automated render queue (macOS AppleScript; Windows path sketched). --dry-run works on any OS

Quality

• 69 tests / 67 pass / 2 pre-existing failures (unrelated to v0.4)
• TypeScript strict + Biome clean on all 21 new/edited files
• Round-trip verified: every command that mutates a draft produces JSON that re-parses via capcut info
• Version support matrix documenting tested CapCut/JianYing versions

Known integration paths to verify in your environment

• Caption material schema is conservative (type: "text" + caption marker fields). The fields are correct per pyJianYingDraft #148 discussion but field-verified, not visually verified in CapCut's subtitle UI yet.
• Whisper variant: targeted at openai-whisper CLI flag shape. whisper.cpp and faster-whisper use different flags — pass --whisper-cmd <path> if you hit "no SRT found" errors.
• Translate API: defensively strips markdown fences from model output; if the whole batch fails to parse, the error includes raw output for debugging.

Install

npm install -g capcut-cli@0.4.0

Full audit + niche-bend rationale

See the parent project notes (TickTick subtask 6a0e8c628f08462347d33ff1) for the pain-point-driven analysis behind these 10 picks.

README polish only — no code changes, CLI behaviour bit-for-bit identical to v0.3.1.

Mirrors the README structure that drove pyJianYingDraft to 3,266 stars, while keeping our zero-dep / Node / cross-namespace positioning sharp.

What's new in the README

1. Workflow diagram (Mermaid)

Inline Mermaid flowchart at the top of both README.md and README.zh-CN.md showing how capcut-cli fits into a viral-shorts pipeline:

Long video → capcut cut → LLM hook + script → capcut-cli edits → CapCut render → publish

CN version uses 小红书 / 抖音 / 视频号 labels (since YouTube is GFW-blocked for the CN audience).

2. Comparison table

Four-column comparison vs the other CapCut / JianYing tooling: pyJianYingDraft (Python, JianYing-only), CapCutAPI (Python, HTTP server), cutcli (Go, closed-source), and capcut-cli. Highlights what capcut-cli is alone in shipping:

• Zero runtime deps (pure Node ≥ 18 built-ins)
• Both CapCut and JianYing namespaces in one binary (--jianying switch)
• Full 7-file schema reference (docs/draft-schema/)
• Built-in templates (templates/{gold-title,end-card,subscribe-cta}.json)
• Wikimedia Commons URL input with license classifier + attribution

3. Feature checklist

10-category list with ✅ / ⬜ / 🚫 status markers and anchor links into per-command docs. Covers every shipped command across:

• Project I/O · Add content · Edit · Decorators · Templates · Import & discovery · Source materials · Cross-platform · Output · Quality · Roadmap

Gives GitHub a real TOC, gives Google / ChatGPT search a structured surface to recommend, and gives any visitor a sub-15-second answer to "is the feature I need here?"

CLI surface unchanged from v0.3.1. Just install / upgrade for the README:

npm install -g capcut-cli@0.3.2

Diff: v0.3.1...v0.3.2

Three additions on top of v0.3.0. No behavioural changes to the CLI surface — pure developer-experience improvements.

Upgrade

npm install -g capcut-cli@0.3.1

What's new

1. docs/draft-schema/ — 7-file reference for the CapCut JSON format

The most-asked question for anyone writing tooling against CapCut is "what's the JSON shape?" — now answered:

• 00-overview.md — top-level draft structure (id, name, duration, fps, canvas, tracks, materials, platform). Includes the 30-second mental model and common gotchas (close-project-first, clip: null on audio, microsecond invariant).
• 01-tracks-and-segments.md — track types, segment shape (material_id, target_timerange, source_timerange, clip, render_index, extra_material_refs), how the speed field interacts with source_timerange.
• 02-materials.md — every material category and shape. Includes the JSON-in-JSON text content field (with UTF-16 byte offsets in range — the thing that trips up everyone the first time) and the companion-materials pattern.
• 03-keyframes-and-animations.md — common_keyframes for direct property keyframing vs sticker_animation for preset library animations. Explicitly documents the "alpha keyframes don't render on video/text" trap.
• 04-effects-filters-stickers.md — video_effects with apply_target_type semantics, common_mask geometry per shape, canvas_blur levels, transitions, sticker resource_ids.
• 05-version-differences.md — CapCut vs JianYing: filename, platform.app_source, enum-id divergence, the --jianying namespace flag.

Practical, field-level, derived from real drafts and the upstream Python work in pyJianYingDraft.

2. node:test fixture-backed test suite

36 tests across 5 files — inspect, edit, create, template, decorators — running against the canonical test/draft_content.json fixture via spawnSync. ~1-second total runtime. Cross-platform, parallel-safe, CI-friendly.

npm test # build + run all tests
npm run test:fast # tests only (skip build)

The existing shell-based skills/capcut-edit/scripts/_test.sh remains for skill-wrapper smoke tests; the canonical CLI test suite is now test/*.test.mjs.

3. Husky pre-commit gate + Biome lint

Every commit runs lint-staged (Biome check/format on staged files only) followed by the full node:test suite. Cheap (<10s on a clean tree), catches regressions before they hit npm.

.husky/pre-commit:
 1. lint-staged — biome check --write on staged src/test files
 2. npm run test:fast — full node:test against the built CLI

Skipping with git commit --no-verify should be rare.

Also: source files received a Biome auto-format pass (whitespace, import sort). No CLI behaviour changed; the v0.3.0 surface is bit-for-bit identical.

Full CHANGELOG: CHANGELOG.md
Diff: v0.3.0...v0.3.1

Five-phase port from sun-guannan/VectCutAPI (Python) to capcut-cli (zero-dep TypeScript). Every recipe stays JSON-by-default, pipeable, local-only — no new runtime, no network beyond the Wikimedia gate, no Python at runtime.

Upgrade

npm install -g capcut-cli@0.3.0

New commands

Decorators on existing segments

• capcut keyframe <project> <id> <prop> <time> <value> — and --batch JSONL on stdin; properties: position_x/y, rotation, scale_x/y, uniform_scale, alpha, saturation, contrast, brightness, volume
• capcut transition <project> <id> <slug> — 8 starter slugs (dissolve, rgb-glitch, radial-blur, ...)
• capcut mask <project> <id> <slug> — linear / mirror / circle / rectangle / heart / star + geometry flags; --off to remove
• capcut bg-blur <project> <id> <1-4> — background blur level
• capcut text-style <project> <id> [flags] — alpha, shadow, border, bg box (26 flags)
• capcut text-anim <project> <id> --intro <slug> --outro <slug> — fade-in, typewriter, pop-up, throw-out, blur-text-in, zoom-in-text

New track types

• capcut add-sticker <project> <resource-id> <start> <duration> — sticker track + transform
• capcut add-effect <project> <slug> <start> <duration> — 7 starter scene effects (shake, vhs, cinematic, light-leak, film-grain, chromatic, vignette)
• capcut image-anim <project> <id> --intro <slug> --outro <slug> --combo <slug> — for video / image segments

Import + enum discovery

• capcut import-srt <project> <srt-or--> — zero-dep parser; --style-ref, --time-offset, stdin support
• capcut enums --<category> — 13 categories ×ばつ 2 namespaces from a committed enums.json. JSON by default or -H table.

Multi-style text + JianYing namespace

• capcut text-ranges <project> <id> --styles @file.json — different styling per character range in one text segment. Unlocks word-level highlight captions.
• --jianying global flag — threaded through transition, mask, text-anim, image-anim, add-effect, enums

Wikimedia Commons input

• add-video / add-audio accept commons.wikimedia.org / wikipedia.org / upload.wikimedia.org URLs
• License classifier + refusal gate: permissive auto-downloads, fair-use warns, restrictive/unknown requires --force-license
• JSON output carries wikimedia block with attribution (artist / credit / description_url / license / dimensions / mime)

Packaging

• 3 ready-made templates ship in templates/: gold-title.json, end-card.json, subscribe-cta.json. Use via capcut apply-template ./project ./node_modules/capcut-cli/templates/<name>.json <start> <duration>.
• GitHub Sponsors enabled via .github/FUNDING.yml
• --help footer with the viral-shorts pipeline / 中文版 / Sponsors links

Skill (Claude Code plugin)

skills/capcut-edit/ reorganised into references/ + scripts/ + assets/. Six wrapper scripts (fade-in, fade-out, anim, ken-burns, long-to-short, stamp-cta) with end-to-end tests (scripts/_test.sh — 7/7 passing).

Out of scope (intentionally)

HTTP server, MCP server, ffprobe-based duration, FFmpeg letterboxing, cloud rendering — per the project's zero-dep design (PLAN.md).

Full CHANGELOG: CHANGELOG.md
Changelog diff: v0.2.2...v0.3.0

Packaging-only follow-up to v0.2.0. No functional changes.

• Adds examples/ (8 copy-paste recipes + 3 Python helper scripts) to the npm tarball
• Adds README.zh-CN.md (中文) to the npm tarball

npm install -g capcut-cli@0.2.1

For what's actually new in 0.2.x, see v0.2.0 release notes.