CapCutCLI

CapCut Desktop project automation for humans, scripts, and AI agents.

CapCutCLI creates and edits local CapCut draft folders through a JSON-first command line and Python API. It gives an agent structured operations for media, tracks, clips, audio, text, transitions, filters, keyframes, motion, and project installation without requiring the agent to understand CapCut's internal JSON.

It edits project files. It does not render/export video, control the CapCut editor UI, or guarantee live refresh while a draft is open. Close CapCut before mutating a project, then install it and select it from CapCut's project list.

Capabilities

Area	What an agent can do
Projects	Create, inspect, validate integrity, install, and launch CapCut Desktop
Assets	Import and probe image/video/audio files; list reusable asset IDs
Timeline	Create tracks; add, query, move, trim, update, and delete segments
Audio	Place TTS/BGM/local SFX, set volume/fades/mute, and duck music under voice
Text	Add titles/subtitles, style emphasis ranges, and apply intro/outro/loop animations
Visuals	Set transitions and filters; add keyframes; apply camera-motion presets
Storyboards	Validate, plan, and transactionally compile a high-level storyboard
Quality	Detect structural problems and viewer-visible timeline defects before opening CapCut
Automation	Apply atomic batches, stream newline-delimited JSON, or use guarded raw patches

Install

Requires Python 3.11–3.14 and pipx.

pipx install capcut-cli
capcut --help

Upgrade or uninstall:

pipx upgrade capcut-cli
pipx uninstall capcut-cli

Native wheels are published for CPython 3.11–3.14 on Apple Silicon and Intel macOS, x64 Windows, and x64 Linux.

AI Agent Quick Reference

Recommended workflow

1. Inspect first with project.inspect, asset.list, or timeline.summary.
2. Discover exact arguments with capcut schema --op <operation>.
3. Import assets before referencing their asset_id from clips or audio.
4. Prefer structured operations. Group related writes with batch.apply.
5. Re-inspect, then run project.integrity and quality.lint.
6. Run project.install-launch; the user selects the installed draft in CapCut.

Use raw.patch only when no structured operation can express the edit. batch.apply is transactional by default, so a failed operation rolls back the group instead of leaving a partially edited timeline.

Operation map

• project.*: create, inspect, integrity-check, install, and launch projects
• asset.*: import, list, and probe media
• track.*: ensure and list video, audio, or text tracks
• clip.*: add image/video clips; move, trim, update, or delete segments
• audio.*: add TTS/BGM/local SFX; update audio; generate ducking envelopes
• storyboard.*: validate, plan, and compile high-level storyboard JSON
• timeline.*: summarize, query, move, or delete any segment; delete managed output
• text.*: add/update titles and subtitles; list/apply animations
• transition.*, filter.*, sfx.*: use CapCut's built-in effect catalogs
• keyframe.*, motion.*: edit animation values or apply camera presets
• quality.*: lint black gaps, overlaps, text layout, caption pacing, audio mix, invisible clips, transition errors, and long motionless stills
• batch.*: execute grouped operations, atomically by default
• raw.*: patch low-level project JSON as a last-resort escape hatch
• session.*: process one JSON request per input line for long-lived agents

List CLI commands or inspect the machine-readable schema for one operation:

capcut --help
capcut schema --op clip.add-video
capcut schema --op storyboard.compile

Data and response contract

• Public operation times are milliseconds. Stored CapCut timeranges and keyframe offsets are microseconds.
• Segments on the same track may not overlap.
• draft_info.json and draft_content.json are saved together through guarded, normalized writes.
• IDs should be discovered from read operations, not guessed.
• Every CLI/session response is JSON. Success uses {"ok": true, "command": "...", "result": {...}, "warnings": []}. Failure uses {"ok": false, "error": {"code": "...", "message": "...", "details": {...}}}.
• Error details include suggested_fix and, when relevant, conflicting IDs, invalid fields, paths, or recovery artifacts.

Important recovery rule: CLEANUP_RECOVERY_REQUIRED means the mutation was already committed. Resolve the listed artifacts and do not retry the original operation, or it may duplicate timeline state. PROJECT_BUSY means another writer holds the lock; wait instead of deleting .lock.

JSON session example

session.serve keeps one process alive and accepts one operation object per line:

printf '%s\n' \
  '{"op":"project.inspect","project_dir":"./workspace/demo"}' \
  '{"op":"timeline.summary","project_dir":"./workspace/demo"}' \
  '{"op":"quality.lint","project_dir":"./workspace/demo"}' \
  | capcut session serve

The same operation names and fields are accepted by modules.capcut.operations.apply_operation(op, args) in Python.

Development

python -m venv .venv
.venv/bin/pip install -e .[dev]
.venv/bin/pytest

Example:

capcut project create --project-dir ./workspace/demo --title "Demo Project"
capcut project inspect --project-dir ./workspace/demo
capcut timeline summary --project-dir ./workspace/demo

Place a CapCut library sound effect (auto-downloads the mp3 on first use):

capcut sfx list                                                # catalog size
capcut sfx add --project-dir ./workspace/demo \
               --effect-id 6817667030158706690 --start-ms 0    # Poi-n jumping sound

The catalog at modules/capcut/_draft/metadata/capcut_sfx_meta.py is generated from your local CapCut rp.db cache. Rebuild it after browsing new categories in the "사운드 효과" panel:

python3 scripts/sync_sfx.py

Reference Points

• tests/test_capcut_cli.py: compact behavior coverage for the public CLI and apply_operation()
• docs/operation-contract.json: current public operation contract, required fields, and error surface
• docs/compatibility.md: package/runtime compatibility targets and smoke-test guidance
• docs/publishing.md: private-source PyPI/pipx release procedure
• docs/motion-api-spec.md: planned shared camera motion API for builder and CLI

Demo Scripts

Full feature demo with real local media:

python3 demo_specs/build_full_feature_demo.py --clean --install

This creates reusable demo assets under demo_assets/full_feature_demo/, builds a sample project in workspace/full_feature_demo_project/, and writes an execution report to demo_reports/full_feature_demo_report.json.

Focused demo for the newer list/update/trim operations:

python3 demo_specs/build_new_ops_demo.py --clean

This verifies asset.list, clip.trim, clip.update, audio.update, and text.update, then writes a report to demo_reports/new_ops_demo_report.json.