@optima-chat/comfy-cli

ComfyUI CLI

面向 ComfyUI 的命令行工具，专为 AI Agent 设计，特别适配 Claude Code。

特性

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

安装

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

快速开始

# 首次使用：配置 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

在你的项目中运行：

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 管理

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

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

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

输出格式

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

• JSON 模式（默认）：机器可读，AI 友好，减少 50%+ token

  comfy queue status
  # {"success":true,"data":{"running":[],"pending":[]}}
  

• Pretty 模式：人类可读，带颜色和表格

  comfy queue status --pretty
  # 📊 队列状态
  # ✓ 当前无正在执行的任务
  

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

命令

✨ 快捷功能命令

图像生成（文生图）

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）

图像编辑（图生图）

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）

视频生成（图生视频）

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）

🔧 核心命令

工作流管理

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

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

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

队列管理

# 查看队列状态
comfy queue status

# 清空队列
comfy queue clear --confirm

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

# 中断当前执行
comfy interrupt

模型管理

# 列出所有模型
comfy model list

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

节点信息

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

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

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

系统信息

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

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

配置管理

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

# 查看当前配置
comfy config list

# 重置配置
comfy config reset --confirm

配置

默认配置存储在 ~/.comfy-cli/config.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/CLAUDE.md 中添加：

## 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）

开发

# 安装依赖
npm install

# 开发模式运行
npm run dev

# 构建
npm run build

# 本地测试
npm link
comfy --help

文档

• 技术设计 - 架构和实现细节
• API 参考 - API 文档（即将推出）
• 使用示例 - 使用示例（即将推出）

许可证

MIT

贡献

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

相关链接

• ComfyUI
• Optima CLI - 本项目的灵感来源