cutcli is a single-binary command-line tool that turns shell commands or JSON into a standard CapCut / Jianying (剪映) draft folder. Open CapCut on desktop and the draft is already in your draft list — fully editable, with captions, animations, transitions, audio and keyframes intact. Install with: curl -s https://cutcli.com/cli | bash

How do I use cutcli with Cursor, Claude Code or an MCP agent?

Run "cutcli setup cursor" (or claude / openclaw / all) to install the cutcli SKILL into your AI tool. The assistant can then call cutcli commands directly. For ChatGPT / Gemini and other models, copy prompts/system/cutcli-expert.md into the model's system prompt. Full guide: https://docs.cutcli.com/guide/ai-integration

Does cutcli work with both CapCut (international) and Jianying (剪映 Chinese)?

Yes. The draft format is the same on both apps; cutcli writes drafts that either client can open directly from its draft folder.

How is cutcli different from manually editing CapCut JSON?

Hand-writing CapCut draft JSON means dealing with microsecond timestamps, undocumented enums, normalized 0–1 coordinates and a half-dozen sibling files that must stay in sync. cutcli handles all of that and exposes a stable CLI surface (cutcli draft create, cutcli captions add, cutcli draft easy, …) that survives CapCut version bumps.

Where can I find runnable examples?

The cutcli-cookbook repository at https://github.com/xuliang2024/cutcli-cookbook ships 8 ready-to-run examples under examples/ — one caption with fade-in, image slideshow with BGM, TikTok-style keyword highlighting, audio-driven layout, keyframe zoom, 30-second product promo, knowledge science card, and vlog template.

CLI 命令参考

Name: cutcli
Author: cutcli

draft — 草稿管理

`cutcli draft create`

创建一个新的剪映草稿。会创建完整的剪映标准草稿文件夹（包含模板文件和 resources/ 媒体目录），可直接被剪映桌面端打开。

bash

cutcli draft create [选项]

选项	类型	默认值	说明
`--width <n>`	number	`1080`	画布宽度（像素）
`--height <n>`	number	`1920`	画布高度（像素）

输出示例：

json

{
  "draftId": "a1b2c3d4-e5f6-7890-abcd-1234567890ab",
  "filePath": "/Users/you/Movies/JianyingPro Drafts/a1b2c3d4-e5f6-7890-abcd-1234567890ab"
}

`cutcli draft info`

获取草稿的基本信息，包括画布尺寸、时长、轨道和素材概要。

bash

cutcli draft info <draftId>

参数	类型	必填	说明
`draftId`	string	是	草稿 ID

输出示例：

json

{
  "draftId": "abc123",
  "canvasWidth": 1080,
  "canvasHeight": 1920,
  "duration": 10000000,
  "fps": 30,
  "trackSummary": [
    { "id": "track_1", "type": "video", "segmentCount": 2 }
  ],
  "materialSummary": {
    "videos": 2,
    "audios": 1,
    "texts": 3,
    "stickers": 0,
    "effects": 0
  }
}

`cutcli draft easy`

按音频时长快速铺素材，自动将图片/视频/文字铺满整个音频时长。传入的媒体 URL 会自动下载到草稿的 resources/ 目录。

bash

cutcli draft easy <draftId> [选项]

参数/选项	类型	必填	说明
`draftId`	string	是	草稿 ID
`--audio-url <url>`	string	是	音频 URL
`--img-url <url>`	string	否	图片 URL
`--video-url <url>`	string	否	视频 URL
`--text <text>`	string	否	文字内容

captions — 字幕管理

`cutcli captions add`

向草稿中批量添加字幕轨道。

bash

cutcli captions add <draftId> [选项]

参数/选项	类型	必填	说明
`draftId`	string	是	草稿 ID
`--captions <json>`	JSON/文件	是	字幕数据，JSON 字面量或 `@file.json`
`--font <name>`	string	否	字体名称
`--alignment <n>`	number	否	对齐方式
`--alpha <n>`	number	否	透明度（0-1）
`--text-color <hex>`	string	否	文字颜色（如 `#FFFFFF`）
`--font-size <n>`	number	否	字号
`--bold`	boolean	否	加粗
`--italic`	boolean	否	斜体
`--underline`	boolean	否	下划线

字幕 JSON 格式：

json

[
  {
    "text": "你好世界",
    "start": 0,
    "end": 3000000,
    "keyword": "世界",
    "keywordColor": "#FF0000"
  }
]

字幕条目字段参考：

字段	类型	必填	说明
`text`	string	是	字幕文本
`start`	number	是	开始时间（μs）
`end`	number	是	结束时间（μs）
`keyword`	string	否	关键词高亮
`keywordColor`	string	否	关键词颜色
`fontSize`	number	否	单条字号
`keywordFontSize`	number	否	关键词字号
`inAnimation`	string	否	入场动画名
`outAnimation`	string	否	出场动画名
`loopAnimation`	string	否	循环动画名
`inAnimationDuration`	number	否	入场动画时长（μs）
`outAnimationDuration`	number	否	出场动画时长（μs）
`loopAnimationDuration`	number	否	循环动画时长（μs）

`cutcli captions list`

列出草稿中所有字幕片段。

bash

cutcli captions list <draftId>

参数	类型	必填	说明
`draftId`	string	是	草稿 ID

images — 图片管理

`cutcli images add`

向草稿添加图片素材。传入的图片 URL 会自动下载到草稿的 resources/ 目录。

bash

cutcli images add <draftId> [选项]

参数/选项	类型	必填	说明
`draftId`	string	是	草稿 ID
`--image-infos <json>`	JSON/文件	是	图片数据
`--alpha <n>`	number	否	透明度（0-1）

图片 JSON 格式：

json

[
  {
    "imageUrl": "https://example.com/photo.jpg",
    "width": 1920,
    "height": 1080,
    "start": 0,
    "end": 5000000
  }
]

图片条目字段参考：

字段	类型	必填	说明
`imageUrl`	string	是	图片 URL（自动下载）
`width`	number	是	图片宽度（像素）
`height`	number	是	图片高度（像素）
`start`	number	是	开始时间（μs）
`end`	number	是	结束时间（μs）
`inAnimation`	string	否	入场动画名
`outAnimation`	string	否	出场动画名
`loopAnimation`	string	否	循环动画名
`inAnimationDuration`	number	否	入场动画时长（μs）
`outAnimationDuration`	number	否	出场动画时长（μs）
`loopAnimationDuration`	number	否	循环动画时长（μs）
`transition`	string	否	转场效果名
`transitionDuration`	number	否	转场时长（μs）

`cutcli images list`

列出草稿中所有图片素材。

bash

cutcli images list <draftId>

参数	类型	必填	说明
`draftId`	string	是	草稿 ID

videos — 视频管理

`cutcli videos add`

向草稿添加视频素材。传入的视频 URL 会自动下载到草稿的 resources/ 目录。

bash

cutcli videos add <draftId> [选项]

参数/选项	类型	必填	说明
`draftId`	string	是	草稿 ID
`--video-infos <json>`	JSON/文件	是	视频数据
`--alpha <n>`	number	否	透明度（0-1）

视频 JSON 格式：

json

[
  {
    "videoUrl": "https://example.com/video.mp4",
    "width": 1920,
    "height": 1080,
    "duration": 10000000,
    "start": 0,
    "end": 10000000
  }
]

视频条目字段参考：

字段	类型	必填	说明
`videoUrl`	string	是	视频 URL（自动下载）
`width`	number	是	视频宽度（像素）
`height`	number	是	视频高度（像素）
`duration`	number	是	视频原始时长（μs）
`start`	number	是	在时间线的开始时间（μs）
`end`	number	是	在时间线的结束时间（μs）
`mask`	string	否	遮罩
`transition`	string	否	转场效果名
`transitionDuration`	number	否	转场时长（μs）
`volume`	number	否	音量

`cutcli videos list`

列出草稿中所有视频片段。

bash

cutcli videos list <draftId>

参数	类型	必填	说明
`draftId`	string	是	草稿 ID

audios — 音频管理

`cutcli audios add`

向草稿添加音频素材。传入的音频 URL 会自动下载到草稿的 resources/ 目录。

bash

cutcli audios add <draftId> [选项]

参数/选项	类型	必填	说明
`draftId`	string	是	草稿 ID
`--audio-infos <json>`	JSON/文件	是	音频数据

音频 JSON 格式：

json

[
  {
    "audioUrl": "https://example.com/audio.mp3",
    "duration": 30000000,
    "start": 0,
    "end": 30000000
  }
]

音频条目字段参考：

字段	类型	必填	说明
`audioUrl`	string	是	音频 URL（自动下载）
`duration`	number	是	音频时长（μs）
`start`	number	是	开始时间（μs）
`end`	number	是	结束时间（μs）
`audioEffect`	string	否	音效名称
`volume`	number	否	音量

`cutcli audios list`

列出草稿中所有音频片段。

bash

cutcli audios list <draftId>

参数	类型	必填	说明
`draftId`	string	是	草稿 ID

effects — 特效管理

`cutcli effects add`

向草稿添加视频特效。

bash

cutcli effects add <draftId> [选项]

参数/选项	类型	必填	说明
`draftId`	string	是	草稿 ID
`--effect-infos <json>`	JSON/文件	是	特效数据

特效 JSON 格式：

json

[
  {
    "effectTitle": "模糊",
    "start": 0,
    "end": 5000000
  }
]

特效条目字段参考：

字段	类型	必填	说明
`effectTitle`	string	是	特效名称
`start`	number	是	开始时间（μs）
`end`	number	是	结束时间（μs）

`cutcli effects list`

列出草稿中所有特效片段。

bash

cutcli effects list <draftId>

参数	类型	必填	说明
`draftId`	string	是	草稿 ID

sticker — 贴纸管理

`cutcli sticker add`

向草稿添加贴纸。

bash

cutcli sticker add <draftId> [选项]

参数/选项	类型	必填	说明
`draftId`	string	是	草稿 ID
`--sticker-id <id>`	string	是	贴纸 ID
`--start <n>`	number	是	开始时间（μs）
`--end <n>`	number	是	结束时间（μs）
`--scale <n>`	number	否	缩放比例

`cutcli sticker list`

列出草稿中所有贴纸。

bash

cutcli sticker list <draftId>

参数	类型	必填	说明
`draftId`	string	是	草稿 ID

keyframes — 关键帧管理

`cutcli keyframes add`

为草稿中的片段添加关键帧。

bash

cutcli keyframes add <draftId> [选项]

参数/选项	类型	必填	说明
`draftId`	string	是	草稿 ID
`--keyframes <json>`	JSON/文件	是	关键帧数据

关键帧 JSON 格式：

json

[
  {
    "segmentId": "seg_001",
    "property": "scale_x",
    "offset": 0,
    "value": 1.0
  },
  {
    "segmentId": "seg_001",
    "property": "scale_x",
    "offset": 3000000,
    "value": 1.5
  }
]

关键帧条目字段参考：

字段	类型	必填	说明
`segmentId`	string	是	所属片段 ID
`property`	string	是	属性名（如 `scale_x`、`position_x` 等）
`offset`	number	是	在片段内的时间偏移（μs）
`value`	number	是	属性值

`cutcli keyframes list`

查看指定片段的关键帧列表。

bash

cutcli keyframes list <draftId> [选项]

参数/选项	类型	必填	说明
`draftId`	string	是	草稿 ID
`--segment-id <id>`	string	是	片段 ID

masks — 遮罩管理

`cutcli masks add`

为草稿中的片段批量添加遮罩。

bash

cutcli masks add <draftId> [选项]

参数/选项	类型	必填	说明
`draftId`	string	是	草稿 ID
`--segment-ids <ids>`	string	是	片段 ID 列表（逗号分隔）
`--name <name>`	string	否	遮罩类型名称（默认 `线性`）
`--width <n>`	number	否	遮罩宽度
`--height <n>`	number	否	遮罩高度
`--feather <n>`	number	否	羽化值
`--rotation <n>`	number	否	旋转角度
`--invert`	boolean	否	反转遮罩

`cutcli masks list`

列出草稿中的遮罩。

bash

cutcli masks list <draftId> [选项]

参数/选项	类型	必填	说明
`draftId`	string	是	草稿 ID
`--segment-id <id>`	string	否	片段 ID（过滤指定片段）

text-style — 文字样式

`cutcli text-style`

生成文字样式 JSON（不写入草稿，仅返回样式数据）。

bash

cutcli text-style [选项]

选项	类型	必填	说明
`--text <text>`	string	是	文字内容
`--keyword <keywords>`	string	是	关键词（多个用 `\|` 分隔）
`--keyword-color <hex>`	string	否	关键词颜色
`--font-size <n>`	number	否	默认字号
`--keyword-font-size <n>`	number	否	关键词字号

使用示例：

bash

cutcli text-style --text "欢迎来到我的世界" --keyword "世界" --keyword-color "#FF0000"

query — 工具查询

`cutcli query audio-duration`

获取远程音频文件的时长。

bash

cutcli query audio-duration [选项]

选项	类型	必填	说明
`--url <url>`	string	是	音频 URL

输出示例：

json

{
  "message": "ok",
  "duration": 15000000
}

`cutcli query image-animations`

查询可用的图片动画效果列表。

bash

cutcli query image-animations [选项]

选项	类型	默认值	说明
`--mode <n>`	number	`0`	模式
`--type <type>`	string	`in`	动画类型：`in`（入场）/ `out`（出场）/ `loop`（循环）

CLI 命令参考 ​

draft — 草稿管理 ​

cutcli draft create ​

cutcli draft info ​

cutcli draft easy ​

captions — 字幕管理 ​

cutcli captions add ​

cutcli captions list ​

images — 图片管理 ​

cutcli images add ​

cutcli images list ​

videos — 视频管理 ​

cutcli videos add ​

cutcli videos list ​

audios — 音频管理 ​

cutcli audios add ​

cutcli audios list ​

effects — 特效管理 ​

cutcli effects add ​

cutcli effects list ​

sticker — 贴纸管理 ​

cutcli sticker add ​

cutcli sticker list ​

keyframes — 关键帧管理 ​

cutcli keyframes add ​

cutcli keyframes list ​

masks — 遮罩管理 ​

cutcli masks add ​

cutcli masks list ​

text-style — 文字样式 ​

cutcli text-style ​

query — 工具查询 ​

cutcli query audio-duration ​

cutcli query image-animations ​

CLI 命令参考

draft — 草稿管理

`cutcli draft create`

`cutcli draft info`

`cutcli draft easy`

captions — 字幕管理

`cutcli captions add`

`cutcli captions list`

images — 图片管理

`cutcli images add`

`cutcli images list`

videos — 视频管理

`cutcli videos add`

`cutcli videos list`

audios — 音频管理

`cutcli audios add`

`cutcli audios list`

effects — 特效管理

`cutcli effects add`

`cutcli effects list`

sticker — 贴纸管理

`cutcli sticker add`

`cutcli sticker list`

keyframes — 关键帧管理

`cutcli keyframes add`

`cutcli keyframes list`

masks — 遮罩管理

`cutcli masks add`

`cutcli masks list`

text-style — 文字样式

`cutcli text-style`

query — 工具查询

`cutcli query audio-duration`

`cutcli query image-animations`