⚙️ 主要功能：一个二进制文件，打通RunComfy全部AI模型

RunComfy-CLI的核心价值可以用一句话概括：把RunComfy平台上数百个AI媒体模型端点，收敛成一条统一的命令行调用入口。

它支持的能力范围很广，覆盖了当前主流的AI媒体生成与编辑场景：

  • 图像生成与编辑：文本生图、图生图、图像修复（inpainting）、图像外绘（outpainting）、图像扩展、超分辨率放大
  • 视频生成与处理：文本生视频、图生视频、视频编辑、视频延长、唇形同步（lip-sync）
  • 人脸与风格控制：换脸、ControlNet姿态控制、重新打光（relight）
  • 模型训练：LoRA训练，从数据集创建到提交训练任务、下载模型权重的完整链路

它的工作模式很直接。以一次图像生成为例：

runcomfy run openai/gpt-image-2/text-to-image \
  --input '{"prompt": "a small purple cat at sunset, photorealistic"}' \
  --output-dir ./out

一条命令完成提交请求、轮询状态、下载结果的完整流程。如果不想等待，可以加--no-wait让请求在后台跑，之后再用runcomfy status <request_id>和runcomfy result <request_id>取回结果。

除了模型调用，它还管理Serverless API（ComfyUI）部署——列出部署、查看节点ID、通过--overrides参数覆盖工作流中的特定节点输入后运行。以及LoRA训练的完整工具链：创建数据集、上传文件、提交训练任务、监控状态、下载训练好的权重。

所有命令都支持--output json输出机器可读的结果，方便嵌入自动化脚本或AI Agent工作流。

🚀 首次安装：四种方式，按需选择

RunComfy-CLI是一个静态链接的Rust二进制文件，提供了四种安装路径，覆盖不同的使用环境。

方式一：npx零安装（最快试用）

npx -y @runcomfy/cli --version

适合只想先试一下、不打算长期使用的场景。npx会自动下载并缓存，不需要改动系统PATH，也不需要管理员权限。

方式二：npm全局安装（推荐日常使用）

npm i -g @runcomfy/cli

安装后runcomfy命令会永久加入PATH。后续用npm i -g @runcomfy/cli@latest更新。

方式三：curl脚本安装（不依赖Node环境）

curl -fsSL https://runcomfy.com/install.sh | sh

安装脚本会自动识别操作系统和CPU架构，从GitHub Releases下载匹配的二进制文件，验证SHA-256校验和后安装到~/.local/bin/（或/usr/local/bin/），必要时自动配置PATH。

方式四：从源码构建（适合开发者）

需要Rust 1.75+环境，克隆仓库后执行cargo build --release即可。

支持平台：macOS（Apple Silicon和Intel）、Linux（x86_64和ARM64）均可使用npm或curl安装。Windows用户目前需要WSL2环境。

安装完成后，执行runcomfy login完成认证。交互式登录会打开浏览器进行OAuth授权，终端会显示一个验证码让你粘贴到浏览器页面；CI/容器环境中则通过export RUNCOMFY_TOKEN=<token>设置环境变量完成认证。

🎯 主要应用场景：谁在用它？

场景一：内容创作者的批量素材生产

需要为营销活动生成一批产品图或社交媒体配图时，可以用脚本循环调用runcomfy run，每次传入不同的prompt，自动下载到指定目录。相比在网页端逐个操作，命令行方式的批量效率高出几个量级。

场景二：AI Agent的媒体生成能力接入

这是RunComfy-CLI被使用得最广泛的场景。它本身就是RunComfy MCP server的CLI对应版本，拥有相同的接口面。当Claude Code、Cursor等AI编程助手需要生成或编辑图像、视频时，可以通过这个CLI作为“执行后端”完成任务。社区中已经有一系列以它为基础的兄弟技能——AI图像生成、AI视频生成、换脸、ControlNet姿态控制等，全都通过同一个CLI分发。

场景三：ComfyUI Serverless部署管理

如果你在RunComfy上部署了Serverless ComfyUI工作流，可以通过runcomfy deployments系列命令在终端里管理部署、查看节点结构、覆盖参数运行推理，不需要打开浏览器。

场景四：LoRA模型的训练与迭代

从数据集上传到训练任务提交、状态监控、权重下载，整条LoRA训练流水线都可以在终端中完成，适合需要频繁迭代模型风格的用户。

💡 使用帮助：几个值得记住的要点

模型发现与Schema查询

不确定该用哪个模型时，先用runcomfy models list --search <关键词>搜索模型目录。找到候选后，用runcomfy models get <model_id>查看它的输入Schema——也就是你需要传哪些参数、每个参数的格式是什么。这一步在写脚本时尤其重要。

JSON输出模式

所有命令都支持--output json，输出结构化的JSON而不是人类可读的文本。这让CLI可以无缝嵌入到Shell脚本、Python程序或AI Agent的工具调用中。比如：

runcomfy --output json run openai/gpt-image-2/text-to-image \
  --input '{"prompt": "ukiyo-e mountain"}' --no-wait | jq -r .request_id

这样可以拿到request_id，后续再异步获取结果。

退出码规范

CLI的退出码遵循sysexits(3)标准，脚本中可以根据不同的退出码判断失败原因（认证失败、模型不存在、请求超时等）。

Shell自动补全

安装后可以生成补全脚本，让runcomfy命令的子命令和参数支持Tab补全：

runcomfy completion zsh > "${fpath[1]}/_runcomfy"

支持bash、zsh和fish三种Shell。

认证的两种方式

交互式场景用runcomfy login，CI/容器场景用RUNCOMFY_TOKEN环境变量。两种方式产生的token是等价的，都存储在~/.config/runcomfy/token.json（权限0600）中。

🤖 适合哪些AI工具？

RunComfy-CLI的设计初衷之一就是成为AI Agent的媒体生成执行层。它兼容所有支持Bash命令调用的AI编程助手和智能体平台。

  • Claude Code：社区已有专门的RunComfy-CLI Skill，安装后Claude Code可以在对话中自动识别“生成一张图”、“做个视频”等意图，调用runcomfy run完成操作。
  • Cursor：同样支持通过Skills机制加载RunComfy-CLI技能，在编码过程中随时调用AI媒体模型。
  • Codex CLI：作为OpenAI的命令行AI工具，也可以通过Skill集成使用。
  • RunComfy MCP Server：如果你偏好MCP协议而非CLI，RunComfy官方提供了远程MCP Server，功能面对标CLI，可以直接接入支持MCP的AI助手。

值得注意的是，RunComfy生态中还有一系列兄弟技能——AI图像生成、AI视频生成、换脸、ControlNet姿态控制、重打光等——它们都通过同一个runcomfy CLI分发请求，只是根据用户意图自动路由到最合适的模型端点。

📝 总结

RunComfy-CLI的定位很清晰：它是RunComfy平台在终端世界的统一入口。

如果你需要经常使用RunComfy上的AI媒体模型——无论是图像生成、视频制作、换脸还是LoRA训练——这个CLI能省去反复切换浏览器、手动上传下载的麻烦。一条命令完成提交、等待、下载的完整流程，加上JSON输出和退出码规范，让它天然适合脚本化和AI Agent集成。

对于已经在用Claude Code、Cursor等AI编程助手的人来说，RunComfy-CLI Skill让AI助手具备了“直接生成媒体内容”的手和脚。装上它，你的AI助手就不只能写代码了，还能出图、出片。