> ## Documentation Index
> Fetch the complete documentation index at: https://docs.comfy.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Comfy CLI

> 从终端驱动 Comfy：本地 ComfyUI、合作伙伴生成调用以及 Comfy Cloud 上的完整工作流。与 MCP 互补，适用于脚本、CI 和自动化。

[comfy-cli](https://github.com/Comfy-Org/comfy-cli) 是 Comfy 的命令行工具。与 [MCP 服务器](/zh/agent-tools) 一起，它为代理和开发者提供了另一种从 UI 外部驱动 Comfy 的方式。

用于**终端或脚本访问**：批处理任务、CI 流水线、工作流自动化，以及通过捆绑的 CLI 技能与编码代理配对。

<Info>
  **代理快速参考。** 本页是精简概览：足以与 MCP 配合使用并运行常见的 `comfy generate` 调用。如需**完整的 CLI 文档**（本地安装、`comfy setup`、`comfy run`、模板、工作流编辑、节点/模型发现等），请参阅 [Comfy CLI 入门](/zh/comfy-cli/getting-started)。
</Info>

<Info>
  **`comfy generate` 处于测试阶段。** 标志名称、模型别名和输出格式可能会更改。底层的合作伙伴端点保持稳定。请在 [comfy-cli GitHub 仓库](https://github.com/Comfy-Org/comfy-cli/issues) 提交反馈。
</Info>

## 如何与 MCP 配合使用

|          | Comfy Cloud MCP                           | Comfy CLI                              |
| -------- | ----------------------------------------- | -------------------------------------- |
| **接口**   | 与 MCP 客户端（Claude Code、Claude Desktop 等）对话 | 终端命令和脚本                                |
| **适用场景** | 聊天中的交互式代理工作流                              | 自动化、批量运行、CI、Shell 管道                   |
| **认证**   | MCP 客户端中的 OAuth，或 API 密钥（无头模式）            | `comfy cloud login`（OAuth）或 API 密钥（CI） |
| **输出**   | 返回至聊天会话                                   | 保存到磁盘（`--download`）或 JSON（`--json`）    |

有关 MCP 设置、安装、工具列表和认证方法，请参阅 [Comfy Cloud MCP](/zh/agent-tools/cloud)。

## CLI 能做什么

1. **本地 ComfyUI** — 安装、启动、更新和管理自定义节点
2. **合作伙伴生成** — `comfy generate` 用于一次性图像/视频/音频/3D 合作伙伴 API 调用
3. **云端工作流** — `comfy run`、模板、插槽编辑和 Comfy Cloud 上的任务监控

<Note>
  **两个环境，一个 CLI。** 每条指令会自动检测运行位置。如果您已登录 Comfy Cloud，指令将路由到**云端**；否则在**本地**服务器上执行。每次调用可通过 `--where local|cloud` 覆盖，或使用 `COMFY_WHERE` 环境变量，或用 `comfy set-default --where cloud` 持久化设置。
</Note>

## 安装和设置

<CodeGroup>
  ```bash pip theme={null}
  pip install comfy-cli
  ```

  ```bash homebrew theme={null}
  brew tap Comfy-Org/comfy-cli
  brew install comfy-org/comfy-cli/comfy-cli
  ```
</CodeGroup>

获取 shell 自动补全提示：

```bash theme={null}
comfy --install-completion
```

```bash theme={null}
comfy setup
```

在 CI 或脚本中传递 `-y` 以进行非交互式安装。有关完整的 `comfy setup` 标志表，请参阅 [Comfy CLI 入门](/zh/comfy-cli/getting-started#quick-setup-recommended)。

登录 Comfy Cloud：

```bash theme={null}
comfy cloud login
comfy cloud whoami
```

## `comfy generate` 的前提条件

* 通过 `comfy cloud login`（浏览器 OAuth）获得活跃的 Comfy Cloud 会话，**或** 对于无头或 CI 使用，需要一个 [Comfy API 密钥](/zh/development/api-development/getting-an-api-key)（`--api-key` / `COMFY_API_KEY`）
* 您账户上的[积分](/zh/interface/credits)
* *可选：* [浏览合作节点与按次调用定价](/zh/tutorials/partner-nodes/pricing)

## 首次生成

```bash theme={null}
comfy generate flux-pro \
    --prompt "a cat on the moon, cinematic lighting" \
    --width 1024 --height 1024 \
    --download cat.png
```

CLI 会上传本地文件，提交任务，轮询完成状态，并保存结果。

## 可用模型

`comfy generate` 涵盖图像和视频合作伙伴模型。发现你的 CLI 版本中可用的模型：

```bash theme={null}
comfy generate list                            # 全部模型
comfy generate list --category text-to-video   # 筛选方式：文生视频
comfy generate list --partner kling            # 筛选方式：合作伙伴
comfy generate schema flux-kontext             # 某个模型的参数
```

常用别名包括：

| 类别     | 示例                                                                                                                             |
| ------ | ------------------------------------------------------------------------------------------------------------------------------ |
| **图像** | `flux-pro`, `flux-ultra`, `flux-kontext`, `nano-banana`, `grok`, `grok-edit`, `ideogram-edit`, `dalle`, `recraft`, `stability` |
| **视频** | `seedance`, `kling`, `luma`, `runway`, `pika`, `vidu`, `hailuo`, `moonvalley`, `grok-video`                                    |

运行 `comfy generate list` 获取你环境中的完整列表。

## 使用示例

### 文生图

```bash theme={null}
comfy generate nano-banana \
    --prompt "a watercolor of a sleeping fox" \
    --download fox.png
```

### 图像编辑（参考图像）

传递本地文件路径。CLI 通过 Comfy 的存储端点上传或按需进行 base64 编码：

```bash theme={null}
comfy generate nano-banana \
    --prompt "add a top hat" \
    --image ./cat.png \
    --download edited.png

comfy generate flux-kontext \
    --prompt "add a top hat and a monocle" \
    --input_image ./photo.jpg \
    --download out.png

comfy generate ideogram-edit \
    --image cat.png --mask mask.png \
    --prompt "add sunglasses" \
    --rendering_speed TURBO \
    --download edited.png
```

要上传一次并在多次调用中重复使用：

```bash theme={null}
comfy generate upload ./photo.jpg     # 打印一个已签名的 URL
```

<Note>
  上传的参考资产将在**24小时**后自动删除。它们存储在Comfy管理的GCS中，并使用带签名的URL。对于长期运行的pipeline，请在每次任务之前重新上传。详情请参阅[reference](/zh/comfy-cli/reference#upload)。
</Note>

### 文生视频

视频任务是异步的。CLI 默认会阻塞并轮询：

```bash theme={null}
comfy generate seedance \
    --prompt "a hummingbird hovering over a flower" \
    --resolution 1080p --duration 5 \
    --download hummingbird.mp4

comfy generate kling \
    --prompt "a paper boat drifting on a river at dusk" \
    --duration 5 \
    --download boat.mp4
```

使用 `--async` 立即返回，稍后恢复：

```bash theme={null}
comfy generate luma --prompt "neon koi swimming through clouds" --aspect_ratio 16:9 --async
# prints a job id; resume with:
comfy generate resume luma <job_id> --download out.mp4
```

### 使用 JSON 编写脚本

```bash theme={null}
comfy generate dalle --prompt "a watercolor whale" --json | jq '.data[0].url'
```

## 超越 `comfy generate`

以上是对代理功能的总结。完整指南深入介绍了每个命令：

* `comfy run`、`comfy jobs` 和 `comfy validate` 用于完整工作流
* `comfy templates` 和 `comfy workflow` 插槽编辑
* `comfy nodes` / `comfy models` 发现
* `--json` 输出包以及用于代理的 `comfy --json discover`

→ [Comfy CLI 入门](/zh/comfy-cli/getting-started)（完整文档）

## 代理技能

将捆绑的Comfy代理技能安装到Claude Code、Cursor以及任何支持`AGENTS.md`的工具中，让你的编码代理可以直接驱动CLI：

```bash theme={null}
comfy skills install
comfy skills list      # comfy, comfy-fragments, comfy-debug, comfy-relay, comfy-director
comfy skills status    # 查看各工具中已安装的技能
```

<Note>
  这些是通过 `comfy skills install` 安装的**捆绑版CLI技能**。它们与 [Comfy Skills](https://github.com/Comfy-Org/comfy-skills/) 仓库是分开的，后者托管了 **comfy-cloud** Claude Code 插件，用于 [Comfy Cloud MCP](/zh/agent-tools/cloud)。
</Note>

## 相关资源

| 资源                                                            | 用途                    |
| ------------------------------------------------------------- | --------------------- |
| [Comfy CLI 入门](/zh/comfy-cli/getting-started)                 | **完整**安装指南和命令演练       |
| [Comfy CLI 参考](/zh/comfy-cli/reference)                       | 命令、标志和模型别名            |
| [Comfy Cloud MCP](/zh/agent-tools/cloud)                      | 通过 MCP 连接代理，实现聊天驱动的生成 |
| [GitHub 上的 comfy-cli](https://github.com/Comfy-Org/comfy-cli) | 源码仓库、问题反馈及最新行为        |

## 反馈

* **GitHub**：[comfy-cli 问题](https://github.com/Comfy-Org/comfy-cli/issues)
* **Discord**：[#comfy-mcp-and-cli](https://discord.gg/xWJn6nhE3R)