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

Can cutcli render drafts in the cloud?

Yes. Since cutcli v1.3.9, run "cutcli auth set --api-key " once, then "cutcli cloud render " to zip, upload, and submit a local draft to the cloud render queue. Use "cutcli cloud jobs", "cutcli cloud job", or "cutcli cloud result" to inspect status and output URLs. "cutcli timer render" can run the same flow on an interval for automation checks.

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

不同安装方式可能提供 cut 或 cutcli 命令，二者指向同一个 CLI。本文沿用 cut 展示本地草稿命令，新版云端命令示例使用 cutcli。

auth — 云端认证

云渲染、草稿上传和任务查询需要云端 V3 API Key（sk-...）。认证信息默认保存到 ~/.cut_cli/config.json；也可以临时设置 CUTCLI_API_KEY 和 CUTCLI_API_BASE。默认 API 地址为 https://api.apiz.ai，一般不需要手动覆盖；如果设置 CUTCLI_API_BASE，只能写 origin，不能包含 /api 或 /api/cutcli。

`cutcli auth set`

保存云端 API Key。

bash

cutcli auth set --api-key <key> [选项]

选项	类型	必填	说明
`--api-key <key>`	string	是	共享登录系统 V3 API Key，格式 `sk-...`
`--api-base <url>`	string	否	API 地址，默认 `https://api.apiz.ai`

使用示例：

bash

cutcli auth set --api-key sk-xxxxxxxx
cutcli auth set --api-key sk-xxxxxxxx --api-base http://localhost:8787

`cutcli auth whoami`

查看当前 API Key 对应的用户。

bash

cutcli auth whoami --pretty

`cutcli auth clear`

清除本机保存的 API Key。

bash

cutcli auth clear

draft — 草稿管理

`cutcli draft create`

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

bash

cutcli draft create [选项]

选项	类型	默认值	说明
`--width <n>`	number	`1080`	画布宽度（像素）
`--height <n>`	number	`1920`	画布高度（像素）
`--name <name>`	string	自动生成	草稿名称

输出示例：

json

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

`cutcli draft list`

列出当前草稿目录下的所有剪映草稿。

bash

cutcli draft list

输出字段：

字段	说明
`draftId`	草稿 ID 或草稿目录名
`filePath`	草稿文件夹路径
`name`	草稿名称
`duration`	草稿总时长（μs）
`canvasWidth` / `canvasHeight`	画布尺寸
`createdAt` / `modifiedAt`	创建和修改时间戳

`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	否	文字内容

`cutcli draft zip`

将本地草稿文件夹打包为 zip，供上传、归档或转移到渲染机器使用。

bash

cutcli draft zip <draftId> [选项]

参数/选项	类型	必填	说明
`draftId`	string	是	草稿 ID 或草稿名称
`--output <path>`	string	否	输出 zip 路径；默认写到草稿目录同级

输出示例：

json

{
  "message": "ok",
  "zipPath": "/Users/you/Movies/JianyingPro Drafts/demo.zip",
  "size": 123456
}

`cutcli draft upload`

打包并上传草稿 zip，返回云端下载链接。需要先完成云端认证。

bash

cutcli draft upload <draftId> [选项]

参数/选项	类型	必填	说明
`draftId`	string	是	草稿 ID 或草稿名称
`--zip <path>`	string	否	指定已有 zip 文件；不传则自动打包

输出字段：

字段	说明
`draftUploadId`	云端草稿上传记录 ID
`downloadUrl`	云端草稿下载链接
`zipPath`	本地 zip 路径
`size`	zip 文件大小（字节）

cloud — 云渲染任务

`cutcli cloud render`

上传草稿并创建云渲染任务。未传 --zip 时会自动执行本地打包。 Agent 或自动化脚本应调用 cutcli cloud render，不要用 curl、Python 或 fetch 直接拼 https://api.apiz.ai/api/cutcli/...。

bash

cutcli cloud render <draftId> [选项]

参数/选项	类型	必填	说明
`draftId`	string	是	草稿 ID 或草稿名称
`--zip <path>`	string	否	使用已有 zip 创建渲染任务
`--wait`	boolean	否	提交后持续轮询，直到任务完成、失败或超时
`--poll-interval <seconds>`	number	否	`--wait` 轮询间隔，默认 `15`
`--timeout <seconds>`	number	否	`--wait` 最长等待时间，默认 `1800`

输出字段：

字段	说明
`draftUploadId`	云端草稿上传记录 ID
`downloadUrl`	草稿 zip 下载链接
`jobId`	云渲染任务 ID
`status`	当前任务状态
`videoUrl`	`--wait` 等到完成后的视频链接
`failureReason`	失败原因
`renderJob`	云渲染任务对象，包含 `id`、`status`、`video_url` 等
`resultCommand`	查询该任务结果的下一条命令

使用示例：

bash

cutcli cloud render 0413_0922 --pretty
cutcli cloud render 0413_0922 --zip ~/Desktop/draft.zip --pretty
cutcli cloud render 0413_0922 --wait --pretty

`cutcli cloud jobs`

查看云渲染任务列表。

bash

cutcli cloud jobs [选项]

选项	类型	必填	说明
`--status <status>`	string	否	按状态筛选，如 `queued`、`rendering`、`completed`、`failed`

`cutcli cloud job`

查看单个云渲染任务详情，返回任务信息和事件记录。

bash

cutcli cloud job <id>

参数	类型	必填	说明
`id`	string	是	云渲染任务 ID

`cutcli cloud result`

cloud job 的别名，用于按任务 ID 查看渲染结果。

bash

cutcli cloud result <id>

`cutcli cloud publish`

发布当前账号下已完成且已有 video_url 的云渲染任务到 CutCLI square。

bash

cutcli cloud publish <id> [选项]

参数/选项	类型	必填	说明
`id`	string	是	云渲染任务 ID
`--title <title>`	string	否	广场标题，默认使用草稿文件名
`--description <text>`	string	否	广场描述
`--tags <tags>`	string	否	标签，多个用逗号分隔
`--cover-url <url>`	string	否	封面图 URL

使用示例：

bash

cutcli cloud publish job_xxx --title "My render" --tags demo,cutcli --pretty

timer — 定时云渲染

`cutcli timer render`

按固定间隔创建新草稿、添加默认字幕、上传云端并提交云渲染任务。默认会立即执行一次，之后每 5 分钟继续执行。

bash

cutcli timer render [选项]

选项	类型	默认值	说明
`--interval <minutes>`	number	`5`	执行间隔分钟数
`--count <n>`	number	无限	执行次数
`--no-immediate`	boolean	`false`	等待一个间隔后再执行第一次
`--width <n>`	number	`1080`	画布宽度
`--height <n>`	number	`1920`	画布高度
`--name-prefix <prefix>`	string	`auto_render`	草稿名称前缀
`--duration <seconds>`	number	`5`	默认字幕时长
`--text <text>`	string	`Auto render #{count}\n{time}`	默认字幕模板，支持 `{count}`、`{run}`、`{time}`、`{iso}`、`{draftId}`
`--font-size <n>`	number	`12`	默认字幕字号
`--text-color <hex>`	string	`#ffffff`	默认字幕颜色
`--no-caption`	boolean	`false`	创建空草稿，不添加默认字幕

使用示例：

bash

# 只执行一次，适合验证 API Key、上传和队列是否连通
cutcli timer render --count 1 --pretty

# 每 5 分钟提交一次，草稿名前缀为 daily_render
cutcli timer render --interval 5 --name-prefix daily_render

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,
    "mask": "圆形",
    "maskWidth": 720,
    "maskHeight": 720,
    "maskFeather": 12
  }
]

图片条目字段参考：

字段	类型	必填	说明
`imageUrl`	string	是	图片 URL（自动下载）
`width`	number	否	图片宽度（像素，省略时自动识别）
`height`	number	否	图片高度（像素，省略时自动识别）
`start`	number	是	开始时间（μs）
`end`	number	是	结束时间（μs）
`mask`	string/object	否	图片蒙版，支持 `线性`/`镜面`/`圆形`/`矩形`/`星形`/`爱心`，默认 `圆形`
`maskX` / `maskY`	number	否	蒙版中心偏移（像素，基于图片中心）
`maskWidth` / `maskHeight`	number	否	蒙版宽高（像素）
`maskFeather`	number	否	蒙版羽化（0-100）
`maskExpansion`	number	否	蒙版扩展（0-100）
`maskRotation`	number	否	蒙版旋转角度
`maskInvert`	boolean	否	反转蒙版
`maskRoundCorner`	number	否	矩形蒙版圆角（0-100）
`maskAspectRatio`	number	否	形状宽高比（默认使用 CapCut 对应蒙版的原始值）
`inAnimation`	string	否	入场动画名
`outAnimation`	string	否	出场动画名
`loopAnimation`	string	否	循环动画名
`inAnimationDuration`	number	否	入场动画时长（μs）
`outAnimationDuration`	number	否	出场动画时长（μs）
`loopAnimationDuration`	number	否	循环动画时长（μs）
`transition`	string	否	转场效果名
`transitionDuration`	number	否	转场时长（μs）

mask 也可以写成对象，例如：

json

{
  "mask": {
    "name": "圆形",
    "width": 800,
    "height": 520,
    "feather": 8,
    "roundCorner": 20
  }
}

`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": "position_x",
    "keyframes": [
      { "time": 0, "value": -0.5, "easing": "ease_in_out" },
      { "time": 3000000, "value": 0.5, "easing": "linear" }
    ]
  }
]

扁平写法：

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` / `time`	number	是	在片段内的时间偏移（μs）；分组写法中使用 `time` 或 `offset`
`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	否	遮罩类型名称，支持 `线性`/`镜面`/`圆形`/`矩形`/`星形`/`爱心`（默认 `圆形`）
`--x <n>` / `--y <n>`	number	否	蒙版中心偏移
`--width <n>`	number	否	遮罩宽度
`--height <n>`	number	否	遮罩高度
`--feather <n>`	number	否	羽化值
`--expansion <n>`	number	否	扩展值
`--rotation <n>`	number	否	旋转角度
`--round-corner <n>`	number	否	圆角值
`--aspect-ratio <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 命令参考 ​

auth — 云端认证 ​

cutcli auth set ​

cutcli auth whoami ​

cutcli auth clear ​

draft — 草稿管理 ​

cutcli draft create ​

cutcli draft list ​

cutcli draft info ​

cutcli draft easy ​

cutcli draft zip ​

cutcli draft upload ​

cloud — 云渲染任务 ​

cutcli cloud render ​

cutcli cloud jobs ​

cutcli cloud job ​

cutcli cloud result ​

cutcli cloud publish ​

timer — 定时云渲染 ​

cutcli timer render ​

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 命令参考

auth — 云端认证

`cutcli auth set`

`cutcli auth whoami`

`cutcli auth clear`

draft — 草稿管理

`cutcli draft create`

`cutcli draft list`

`cutcli draft info`

`cutcli draft easy`

`cutcli draft zip`

`cutcli draft upload`

cloud — 云渲染任务

`cutcli cloud render`

`cutcli cloud jobs`

`cutcli cloud job`

`cutcli cloud result`

`cutcli cloud publish`

timer — 定时云渲染

`cutcli timer render`

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`