# ComfyUI CLI

![ComfyUI CLI Banner](./docs/images/banner.png)

面向 [ComfyUI](https://github.com/comfyanonymous/ComfyUI) 的命令行工具，专为 AI Agent 设计，特别适配 Claude Code。

## 特性

- 🚀 **简单易用**：所有 ComfyUI 操作的简单命令
- 🤖 **AI 友好**：默认 JSON 输出，优化 LLM 解析，减少 50%+ token
- 📊 **实时监控**：WebSocket 支持实时进度更新
- 🎨 **图像处理**：无缝上传和下载图像
- 📦 **模型管理**：列出和查询可用模型
- ⚡ **队列控制**：管理工作流执行队列
- 🎯 **双输出模式**：JSON（AI 友好）和 Pretty（人类可读）

## 安装

```bash
npm install -g @optima-chat/comfy-cli@latest
```

## 快速开始

```bash
# 首次使用：配置 ComfyUI 服务器地址
comfy config set server http://localhost:8188

# 检查 ComfyUI 是否运行
comfy system stats

# 生成图像
comfy generate "a beautiful sunset"

# 查看队列状态
comfy queue status

# 列出可用模型
comfy model list --type checkpoints
```

## Claude Code 集成

ComfyUI CLI 支持 Claude Code Skills 自动发现，让 Claude 能够直接通过自然语言调用命令。

### 初始化 Skill

在你的项目中运行：

```bash
comfy init
```

这会在项目中创建 `.claude/skills/comfy-cli/` 目录和 Skill 配置文件。

### 使用示例

打开 Claude Code 后，直接对话：

- **"帮我生成一张猫的图片"** → Claude 自动调用 `comfy generate "a cat"`
- **"把这张图片改成动漫风格"** → Claude 调用 `comfy edit <file> "anime style"`
- **"用这张图片生成视频"** → Claude 调用 `comfy video <file>`

### Skill 管理

```bash
# 查看已安装的 Skill
ls .claude/skills/

# 重新初始化（覆盖）
comfy init --force

# 删除 Skill
rm -rf .claude/skills/comfy-cli/
```

## 输出格式

默认输出 **JSON 格式**（AI 友好），支持两种模式：

- **JSON 模式（默认）**：机器可读，AI 友好，减少 50%+ token
  ```bash
  comfy queue status
  # {"success":true,"data":{"running":[],"pending":[]}}
  ```

- **Pretty 模式**：人类可读，带颜色和表格
  ```bash
  comfy queue status --pretty
  # 📊 队列状态
  # ✓ 当前无正在执行的任务
  ```

全局使用：`comfy --pretty <command>`
单命令使用：`comfy <command> --pretty`

## 命令

### ✨ 快捷功能命令

#### 图像生成（文生图）

```bash
comfy generate "a beautiful sunset over mountains"
comfy generate "cyberpunk city" --width 1024 --height 768
comfy generate "a cat"  # 默认等待完成并显示实时进度
comfy generate "a cat" --no-wait  # 提交后立即返回
```

**选项**：
- `--width <number>`: 图像宽度（默认：1024）
- `--height <number>`: 图像高度（默认：1024）
- `--no-wait`: 提交后立即返回（默认等待完成并显示实时进度）
- `--pretty`: 人类可读的表格格式输出（默认 JSON）

#### 图像编辑（图生图）

```bash
comfy edit input.png "add more details"
comfy edit photo.jpg "make it anime style"
comfy edit image.png "stylize"  # 默认等待完成并显示实时进度
comfy edit image.png "stylize" --no-wait  # 提交后立即返回
```

**选项**：
- `--no-wait`: 提交后立即返回（默认等待完成并显示实时进度）
- `--pretty`: 人类可读的表格格式输出（默认 JSON）

#### 视频生成（图生视频）

```bash
comfy video portrait.png --prompt "smooth motion"
comfy video scene.jpg --width 512 --height 512
comfy video image.png --prompt "dancing"  # 默认等待完成并显示实时进度
comfy video image.png --prompt "dancing" --no-wait  # 提交后立即返回
```

**选项**：
- `-p, --prompt <text>`: 运动描述提示词
- `-n, --negative <text>`: 负向提示词
- `--width <number>`: 视频宽度（默认：512）
- `--height <number>`: 视频高度（默认：512）
- `--no-wait`: 提交后立即返回（默认等待完成并显示实时进度）
- `--pretty`: 人类可读的表格格式输出（默认 JSON）

---

### 🔧 核心命令

#### 工作流管理

```bash
# 提交自定义工作流
comfy workflow submit workflow.json

# 查看历史记录
comfy workflow list --limit 10

# 获取执行结果
comfy workflow get <prompt_id>
```

#### 队列管理

```bash
# 查看队列状态
comfy queue status

# 清空队列
comfy queue clear --confirm

# 删除指定任务
comfy queue delete <item_id>

# 中断当前执行
comfy interrupt
```

#### 模型管理

```bash
# 列出所有模型
comfy model list

# 列出特定类型模型
comfy model list --type checkpoints
comfy model list --type loras --pretty
```

#### 节点信息

```bash
# 列出所有节点类型
comfy node list

# 过滤节点
comfy node list --filter sampler

# 查看节点详情
comfy node info KSampler --pretty
```

#### 系统信息

```bash
# 查看系统状态（默认 JSON）
comfy system stats

# 人类可读的表格格式
comfy system stats --pretty
```

#### 配置管理

```bash
# 设置服务器地址
comfy config set server http://localhost:8188

# 查看当前配置
comfy config list

# 重置配置
comfy config reset --confirm
```

## 配置

默认配置存储在 `~/.comfy-cli/config.json`：

```json
{
  "server": "http://localhost:8188",
  "timeout": 30000,
  "autoConnect": true,
  "outputDir": "./output"
}
```

**配置项说明**：
- `server`: ComfyUI 服务器地址（必需，首次使用前需配置）
- `timeout`: 请求超时时间（毫秒）
- `autoConnect`: 自动连接到服务器
- `outputDir`: 下载文件的默认输出目录

## 在 Claude Code 中使用

### 方式一：使用 Skills（推荐）

在项目中运行 `comfy init` 创建 Skill 配置，Claude 会自动发现并使用。详见 [Claude Code 集成](#claude-code-集成) 章节。

### 方式二：全局配置

在你的 `~/.claude/CLAUDE.md` 中添加：

```markdown
## ComfyUI CLI

ComfyUI CLI 是一个专为 AI Agent 设计的 ComfyUI 命令行工具。

**常见需求映射**：
- "生成图像 XX" → `comfy generate "XX"`
- "编辑图像" → `comfy edit <image> "描述"`
- "生成视频" → `comfy video <image> --prompt "描述"`
- "提交工作流 XX" → `comfy workflow submit XX`
- "查看队列" → `comfy queue status`
- "列出所有 checkpoint 模型" → `comfy model list --type checkpoints`
- "下载生成结果" → `comfy download <prompt_id>`
- "中断当前任务" → `comfy interrupt`

**输出格式**：
- 默认输出 JSON（AI 友好，减少 token）
- 使用 `--pretty` 可切换到人类可读的表格格式
```

## 系统要求

- Node.js >= 18.0.0
- ComfyUI 实例运行中（默认：http://localhost:8188）

## 开发

```bash
# 安装依赖
npm install

# 开发模式运行
npm run dev

# 构建
npm run build

# 本地测试
npm link
comfy --help
```

## 文档

- [技术设计](./docs/technical-design.md) - 架构和实现细节
- [API 参考](./docs/api.md) - API 文档（即将推出）
- [使用示例](./docs/examples.md) - 使用示例（即将推出）

## 许可证

MIT

## 贡献

欢迎贡献！请随时提交 Pull Request。

## 相关链接

- [ComfyUI](https://github.com/comfyanonymous/ComfyUI)
- [Optima CLI](https://github.com/Optima-Chat/optima-cli) - 本项目的灵感来源