# cutcli CLI 示例

当用户希望使用命令行而不是 SDK 代码时，参考这些示例。

## 创建草稿

```bash
cutcli draft create --width 1080 --height 1920 --pretty
```

输出中会包含 `draftId`，后续命令都使用这个草稿 ID。

## 使用 Draft Spec 创建完整草稿

```bash
cutcli spec validate --file draft.json --pretty
cutcli spec create --file draft.json --pretty
```

需要云渲染时：

```bash
cutcli spec render --file draft.json --cloud --wait --pretty
```

## 便捷添加单个素材

便捷命令支持 `1.5s`、`500ms`、`300000us` 这类时间字符串。

```bash
cutcli query text-effects --keyword 火焰 --limit 5 --pretty
cutcli text add <draftId> --text "主标题" --start 0s --duration 3s --font-size 10 \
  --text-effect "红黄火焰综艺花字" --border-color "#000000" --shadow --shadow-color "#000000" --pretty
cutcli image add <draftId> --src ./素材/bg.png --start 0s --duration 5s --width 1080 --height 1920 \
  --in-animation 渐显 --in-animation-duration 500ms --transition 叠化 --transition-duration 500ms --pretty
cutcli audio add <draftId> --src ./素材/bgm.mp3 --start 0s --duration 20s --pretty
cutcli video add <draftId> --src ./素材/clip.mp4 --start 5s --duration 3s --width 1080 --height 1920 \
  --mask 圆形 --scale-x 0.9 --scale-y 0.9 --pretty
```

## 批量 JSON 命令

单素材命令是本地拼接主路径。下面的 `captions/images/audios` 批量 JSON 命令用于一次添加多段素材，或需要更细字段时使用。

### 添加字幕

```bash
cutcli captions add <draftId> --captions '[
  {
    "text": "CLI 字幕示例",
    "start": 0,
    "end": 3000000,
    "keyword": "CLI",
    "keywordColor": "#00ffaa",
    "inAnimation": "渐显",
    "outAnimation": "渐隐",
    "inAnimationDuration": 500000,
    "outAnimationDuration": 500000
  }
]' --font-size 8 --text-color "#ffffff" --bold --text-effect "红黄火焰综艺花字" --shadow --pretty
```

### 添加图片

```bash
cutcli images add <draftId> --image-infos '[
  {
    "imageUrl": "/absolute/path/to/background.png",
    "width": 1080,
    "height": 1920,
    "start": 0,
    "end": 5000000
  }
]' --scale-x 0.9 --scale-y 0.9 --transform-y 0.05 --pretty
```

### 添加音频

```bash
cutcli audios add <draftId> --audio-infos '[
  {
    "audioUrl": "/absolute/path/to/music.mp3",
    "duration": 5000000,
    "start": 0,
    "end": 5000000,
    "volume": 0.7
  }
]' --pretty
```

## 渲染

首次使用云渲染前保存 Token：

```bash
cutcli login <apiToken>
```

```bash
cutcli cloud render <draftId> --wait --pretty
```

## JSON 文件输入

大多数 JSON 参数也支持 `@file.json`：

```bash
cutcli captions add <draftId> --captions @captions.json --pretty
```