---
name: comfy-cli
description: "ComfyUI CLI tool for AI agents. ALWAYS use when user wants to: generate images (生成图片/画图/图像/生成画), edit images (编辑图片/修改图片/图生图/改图), create videos (生成视频/图生视频/制作视频), virtual try-on (虚拟试穿/试穿/换装/试衣), text-to-speech (TTS/语音合成/朗读/文字转语音), speech recognition (ASR/语音识别/语音转文字/转录), manage ComfyUI workflows (工作流/ComfyUI). Uses 'comfy image', 'comfy generate', 'comfy edit', 'comfy video', 'comfy tryon', 'comfy tts', 'comfy asr' commands."
---

# ComfyUI CLI

## 典型场景

### 场景 1：快速生成单张图片
**用户需求**："帮我生成一张猫的图片"
**执行步骤**：
1. `comfy image "a cute cat sitting on a couch"`
2. 等待完成（默认行为，显示进度）
3. 使用返回的 prompt_id 下载：`comfy download <prompt_id>`

### 场景 2：图片迭代优化
**用户需求**："这张图片不够好，帮我优化"
**执行步骤**：
1. 分析用户不满意的点（光线、风格、细节）
2. 使用 `comfy image "优化描述" -i 原图.png` 添加优化
3. 如需多次尝试，生成多个变体供用户选择

### 场景 3：图片生成视频
**用户需求**："把这张人物照片做成动态视频"
**执行步骤**：
1. `comfy video portrait.png --prompt "natural head movement"`
2. DashScope 后端支持 720P/1080P 高分辨率
3. 下载后检查效果

## 质量标准

### 好的生成结果
- **图像清晰**：无模糊、无伪影
- **主体突出**：构图合理，主体居中或符合构图原则
- **光影自然**：避免过曝、过暗、不自然的阴影
- **提示词匹配**：生成内容符合用户描述

### 何时需要重新生成
- 用户明确表示不满意
- 生成结果与提示词严重不符
- 图像质量问题（模糊、伪影、扭曲）
- 需要尝试不同风格或角度

### 提示词建议
- **具体清晰**：`a golden retriever puppy` 优于 `a dog`
- **风格描述**：加入 `photorealistic`, `anime style`, `oil painting` 等
- **细节描述**：材质、光线、背景、氛围
- **英文提示词**：FLUX 模型对英文效果最好

## 常见问题

### 问题 1：生成任务提交后无法立即使用
**原因**：生成需要时间，默认会等待完成
**解决**：
- 默认行为会等待并显示进度
- 如使用 `--no-wait`，需用 `comfy workflow get <prompt_id>` 检查状态
- status 为 "completed" 后才能下载

### 问题 2：视频生成失败或超时
**原因**：分辨率过大或提示词复杂
**解决**：
- 视频推荐使用 512x512 分辨率
- 避免过长或复杂的提示词
- 检查服务器状态：`comfy system stats`

### 问题 3：生成结果不符合预期
**原因**：提示词不够具体或缺少细节
**解决**：
- 增加具体描述（颜色、材质、风格、光线）
- 使用参考风格词（如 "product photography", "cinematic"）
- 尝试生成多个变体（调整提示词细节）

### 问题 4：无法连接到 ComfyUI 服务器
**原因**：服务器未启动或地址配置错误
**解决**：
- 检查服务器状态：`comfy system stats`
- 查看配置：`comfy config list`
- 如使用本地服务器：`comfy config set server http://localhost:8188`

### 问题 5：下载的文件找不到
**原因**：未指定输出目录或忘记下载路径
**解决**：
- 默认保存到 `./output` 目录
- 使用 `-o` 指定输出路径
- 检查命令输出的文件路径

## Instructions

### 核心命令

**图像生成/编辑（推荐）：**
```bash
comfy image "提示词" [-i 输入图像] [-W 宽度] [-H 高度] [--backend auto|bfl|comfyui] [--no-wait]
```
- **推荐使用**：统一的图像命令，自动选择最佳后端
- 无 `-i` 参数时为文生图，有 `-i` 参数时为图生图
- 支持多图参考：`-i img1.png -i img2.png`（仅 BFL 后端）
- 自动选择后端：有 BFL API Key 用 BFL 云端，否则用 ComfyUI 本地

**生成图像（别名）：**
```bash
comfy generate "提示词" [--width 1024] [--height 1024] [--no-wait] [--pretty]
```
- 等同于 `comfy image "提示词"`
- 默认等待完成并显示实时进度，返回 JSON

**编辑图像（别名）：**
```bash
comfy edit <图像路径> "提示词" [--no-wait] [--pretty]
```
- 等同于 `comfy image "提示词" -i <图像路径>`
- 支持风格转换、细节增强等

**虚拟试穿 (Virtual Try-On)：**
```bash
comfy tryon <人物照片> <服装照片> [-o 输出路径] [-c auto|tops|bottoms|one-pieces] [-m performance|balanced|quality] [-n 1-4] [--pretty]
```
- 使用 FASHN AI tryon-v1.6 模型
- 支持本地图片路径和 URL
- 服装类别自动检测，也可手动指定
- 三种模式价格相同（1 credit/张），默认 quality

**文本转语音 (TTS)：**
```bash
comfy tts "文本内容" [-o 输出路径] [--voice Cherry] [--play] [--pretty]
```
- 使用 DashScope qwen3-tts-flash 模型
- 支持 50+ 种声音（女声：Cherry, Serena, Chelsie 等；男声：Ethan, Aiden, Brandon 等）
- 自动检测语言（中、英、日、韩、法、德等）
- `--voices` 列出所有可用声音

**语音识别 (ASR)：**
```bash
comfy asr <音频文件> [--language zh|en|ja|ko] [--pretty]
```
- 使用 Groq Whisper (whisper-large-v3-turbo)
- 支持 mp3, wav, m4a, ogg, webm 格式
- 文件大小限制 25MB

**生成视频：**
```bash
comfy video <图像路径> [-p "运动描述"] [-b auto|dashscope|comfyui] [-r 720P|1080P] [-d 5|10|15]
```
- 从图像生成视频（图生视频）
- DashScope 后端（wan2.6）：支持 720P/1080P，5/10/15 秒
- ComfyUI 后端（wan2.1）：本地部署，自定义参数

**下载结果：**
```bash
comfy download <PROMPT_ID> [-o ./output] [--pretty]
```
- 下载生成的图像/视频到本地目录（默认：./output）

### 工作流管理

```bash
comfy workflow list [--limit 10] [--pretty]          # 列出历史
comfy workflow get <PROMPT_ID> [--pretty]            # 获取结果
comfy workflow submit <工作流文件> [--pretty]         # 提交自定义工作流
```

### 队列管理

```bash
comfy queue status [--pretty]                        # 查看队列状态
comfy queue clear --confirm [--pretty]               # 清空队列
comfy queue delete <项目ID> [--pretty]               # 删除队列项
comfy interrupt [--pretty]                           # 中断当前执行
```

### 模型管理

```bash
comfy model list [--type checkpoints|loras|vae|controlnet|upscale_models] [--pretty]
```

### 系统信息

```bash
comfy system stats [--pretty]                        # GPU/CPU/内存状态
```

### 配置

```bash
comfy config list [--pretty]                         # 查看当前配置
comfy config set server http://localhost:8188        # 更改服务器地址（可选，默认 http://dev.optima.chat:8188）
```

### 输出格式

- **默认**：JSON 格式（AI 友好，减少 token）
- **--pretty**：带颜色的表格格式（人类可读）

## Examples

### 示例 1：生成图像（推荐）
```bash
comfy image "a cute cat"
```
返回包含 `id` 和状态的 JSON，等待完成后使用 `comfy download <id>` 下载

### 示例 2：高分辨率图像
```bash
comfy image "beautiful landscape with mountains" -W 1920 -H 1080
```

### 示例 3：图像风格转换
```bash
comfy image "anime style" -i photo.jpg
```

### 示例 4：多图风格融合（BFL 后端）
```bash
comfy image "combine the styles" -i style.png -i content.png --backend bfl
```

### 示例 5：视频生成（DashScope 高清）
```bash
comfy video portrait.png --prompt "smooth motion" --backend dashscope --resolution 1080P --duration 10
```

### 示例 6：视频生成（ComfyUI 本地）
```bash
comfy video portrait.png --prompt "natural movement" --backend comfyui
```

### 示例 7：批量生成（非阻塞）
```bash
comfy image "a cat sitting" --no-wait
comfy image "a cat playing" --no-wait
comfy image "a cat sleeping" --no-wait
comfy queue status
```

### 示例 8：完整工作流
```bash
# 1. 生成图像
comfy image "a portrait of a woman"
# 返回 id，等待完成后使用 comfy download 下载

# 2. 下载第一张图像
comfy download <id_1>
# 输出：./output/comfy-cli_00001_.png

# 3. 编辑图像
comfy image "add cinematic lighting" -i ./output/comfy-cli_00001_.png
# 返回 id，等待完成后下载

# 4. 下载编辑后的图像
comfy download <id_2>
# 输出：./output/comfy-cli_00002_.png

# 5. 生成视频
comfy video ./output/comfy-cli_00002_.png --prompt "slow motion"
# 返回 id，等待完成后下载
```

### 示例 9：检查状态和下载
```bash
# 非阻塞提交
comfy image "sunset" --no-wait
# 返回：{ "id": "abc123" }

# 稍后检查状态
comfy workflow get abc123

# 下载结果
comfy download abc123
```

### 示例 10：虚拟试穿
```bash
# 基本试穿
comfy tryon person.jpg garment.jpg

# 指定服装类别和快速模式
comfy tryon person.jpg top.jpg -c tops -m performance

# 生成多张结果
comfy tryon person.jpg dress.jpg -n 4 -c one-pieces

# 使用 URL 图片
comfy tryon https://example.com/model.jpg https://example.com/dress.jpg
```

### 示例 11：文本转语音
```bash
# 中文语音合成
comfy tts "你好，欢迎使用语音合成功能" -o greeting.wav

# 使用男声
comfy tts "Hello, welcome!" --voice Ethan -o hello.wav

# 生成后自动播放
comfy tts "测试语音" --play
```

### 示例 12：语音识别
```bash
# 自动检测语言
comfy asr recording.mp3

# 指定语言提示
comfy asr meeting.wav --language zh
```

## 重要提示

- **推荐使用 `comfy image`**：统一入口，自动选择最佳后端
- 图像后端：BFL 云端（高质量）或 ComfyUI 本地（免费）
- 视频后端：DashScope 云端（720P/1080P）或 ComfyUI 本地
- 默认连接到 `http://dev.optima.chat:8188`（ComfyUI）
- 默认输出 JSON 格式，适合 AI 解析
- 使用 `--pretty` 获取人类可读输出
- 默认等待完成并显示实时进度