> ## 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-cli` 是一个[命令行工具](https://github.com/Comfy-Org/comfy-cli)，可简化 Comfy 的安装与管理，并通过脚本化的单条指令在本地或云端访问整个 ComfyUI 生态系统。

它主要提供三种功能：

1. **管理本地 ComfyUI 安装** —— 安装、启动、更新、快照和二分查找 ComfyUI 及自定义节点。
2. **访问托管合作节点** —— 通过单条指令从 Seedance、Nano Banana (Gemini)、Grok、Flux、Ideogram、DALL·E、Recraft、Stability、Kling、Luma、Runway、Pika、Vidu、Hailuo、Moonvalley 等提供商生成图像、视频、音频和 3D 内容。
3. **在 Comfy Cloud 上运行完整工作流** —— 提交工作流图、浏览精心策划的模板图库、槽位编辑工作流，并监控任务直至完成，无需本地 GPU。

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

## 安装 CLI

<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
```

它将引导您选择路由目标（本地或云端），**通过浏览器登录（OAuth）**，选择项目目录，并可选择安装代理技能。这是推荐路径。它会自动打开浏览器登录页面，无需复制密钥。

```bash theme={null}
comfy setup --where cloud
```

<Note>
  **非交互模式（仅限CI）。** 浏览器OAuth需要交互式会话。对于CI、开发容器以及无法使用浏览器的脚本化安装，请改用API密钥：

  ```bash theme={null}
  comfy setup --where cloud --api-key comfyui-... --non-interactive
  ```
</Note>

| 标志                      | 用途                                                     |
| ----------------------- | ------------------------------------------------------ |
| `--where local\|cloud`  | 路由目标；跳过提示                                              |
| `--project-dir`         | 工作流、输入和输出的目录                                           |
| `--api-key`             | *（可选）* 用于无头/CI环境的Comfy Cloud API密钥；隐式指定`--where cloud` |
| `-y, --non-interactive` | 无提示。所有配置均由标志驱动                                         |
| `--skip-skills`         | 不安装代理技能                                                |
| `--skip-verify`         | 跳过连通性检查                                                |

## 安装 ComfyUI (本地)

使用任意高于 3.9 的 Python 版本创建一个虚拟环境。

<CodeGroup>
  ```bash conda theme={null}
  conda create -n comfy-env python=3.11
  conda activate comfy-env
  ```

  ```bash venv theme={null}
  python3 -m venv comfy-env
  source comfy-env/bin/activate
  ```
</CodeGroup>

安装 ComfyUI

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

<Warning>您仍然需要根据您的 GPU 安装 CUDA 或 ROCm。</Warning>

## 运行 ComfyUI（本地）

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

在后台运行，稍后停止：

```bash theme={null}
comfy launch --background
comfy stop
```

检查当前选择的工作区以及已安装的内容：

```bash theme={null}
comfy which
comfy env
```

## Comfy Cloud

在 Comfy 托管的 GPU 上运行工作流和合作节点，无需本地安装。

```bash theme={null}
comfy cloud login          # 浏览器 OAuth + PKCE
comfy cloud whoami         # 显示登录状态、认证方法、基础 URL
comfy cloud logout         # 清除本地会话
```

登录后，指令将自动路由至云端。\*\*浏览器 OAuth 是推荐的路径。\*\*无需管理密钥，CLI 会自动为您刷新令牌。要在登录前指向自定义环境（例如 PR 预览），请执行：

```bash theme={null}
comfy cloud set-base-url https://my-preview.comfy.org
```

<Note>
  \*\*API 密钥是可选的。\*\*仅当在无头环境或 CI 中使用，且无法通过浏览器登录时，才需要 API 密钥。它作为备用方案，并非默认方式：

  ```bash theme={null}
  export COMFY_API_KEY=comfyui-...   # 或在每次调用时传递 --api-key
  ```
</Note>

<Note>
  \*\*会话生命周期。\*\*Cloud 会话令牌有效期较短（约1小时）。CLI 会根据需要自动刷新。如果某个指令报告 `cloud_unauthorized`，请重新运行 `comfy cloud login`。
</Note>

## 使用合作节点生成

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

从终端或脚本调用 Comfy 的[合作节点](/zh/tutorials/partner-nodes/overview)的最快方式。它访问与 ComfyUI 工作流相同的托管端点，但作为单个 CLI 调用。非常适合批处理任务、快速实验和自动化场景，无需完整的 ComfyUI 画面图。

### 前置条件

* 通过 `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 会上传本地文件，提交任务，轮询完成状态，并保存结果。

<Tip>
  先了解模型的实际参数。不同模型的标志名不同（例如 `flux-ultra` 使用 `--width`/`--height`；`seedance` 使用 `--ratio`/`--resolution`/`--duration`）。在编写脚本前务必检查：

  ```bash theme={null}
  comfy generate schema flux-ultra
  ```
</Tip>

### 常用模型

**Nano Banana (Google Gemini)：文生图与编辑：**

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

# Image editing:
comfy generate nano-banana \
    --prompt "add a top hat" \
    --image ./cat.png \
    --download edited.png

# Specify a model variant:
comfy generate nano-banana \
    --prompt "neon city skyline" \
    --model gemini-3-pro-image-preview \
    --download city.png
```

**Flux 1.1 Pro Ultra：高分辨率文生图：**

```bash theme={null}
comfy generate flux-ultra \
    --prompt "a purple Victorian house in San Francisco, golden hour" \
    --width 896 --height 1152 --seed 11 \
    --download house.png
```

**Seedance（字节跳动）：文生视频和图生视频，最高支持1080p/12秒：**

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

# Image-to-video (animate a local image, auto-uploaded):
comfy generate seedance \
    --model seedance-1-0-pro-250528 \
    --image ./painting.png \
    --ratio 3:4 --resolution 1080p --duration 5 \
    --prompt "the painting gently comes alive, a soft breeze stirs the trees" \
    --download animated.mp4
```

**Grok (xAI)：图像与视频：**

```bash theme={null}
comfy generate grok --prompt "a cyberpunk street market at night" --download street.png
comfy generate grok-edit --prompt "swap the umbrella for a parasol" --image ./photo.jpg --download out.png
comfy generate grok-video --prompt "a paper plane gliding through a cathedral" --download flight.mp4
```

### 探索模型

```bash theme={null}
comfy generate list                            # 全部模型
comfy generate list --category text-to-video   # 按类别筛选：文生视频
comfy generate list --partner kling            # 按合作伙伴筛选
comfy generate schema flux-kontext             # 查看模型参数
```

### 使用参考图像进行编辑

传递本地文件路径。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 输出

输出原始 API 响应以集成到管道中：

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

有关命令、标志和模型别名的完整列表，请参阅[参考](/zh/comfy-cli/reference)。

## 运行工作流（`comfy run`）

除了单个合作伙伴调用之外，`comfy run` 会提交一个完整的 ComfyUI 工作流图。它接受 API 格式和导出的 UI 格式 JSON（UI 工作流会在客户端转换为 API 格式），并像其他所有指令一样路由到本地或云端。它**默认异步运行**。它会在毫秒内返回一个 `prompt_id`，同时后台观察者会跟踪进度。使用 `--wait` 可以改为阻塞模式。

```bash theme={null}
# 提交，立即返回 prompt_id
RES=$(comfy --json run --workflow my_workflow.json)
PROMPT_ID=$(echo "$RES" | jq -r .data.prompt_id)

# 等待直到终端态，然后收集输出
comfy --json jobs watch "$PROMPT_ID" | comfy download
```

更喜欢单次阻塞调用？使用 `--wait`：

```bash theme={null}
comfy run --workflow my_workflow.json --wait | comfy download
```

跟踪和管理任务：

```bash theme={null}
comfy jobs ls                 # 本地异步提交 + 服务器队列/历史
comfy jobs status <prompt_id> # 单个任务
comfy jobs wait <id1> <id2>   # 阻塞直到所有任务达到终端态
comfy jobs cancel <prompt_id> # 幂等操作
```

<Tip>
  提交之前先验证。在消耗云端算力前，捕捉未知节点、缺失模型和错误连接：

  ```bash theme={null}
  comfy validate --workflow my_workflow.json
  ```
</Tip>

## 从模板开始

精心策划的 `Comfy-Org/workflow_templates` 图库是快速获取特定任务已知良好工作流的最快方式。无需从头构建。

```bash theme={null}
comfy templates ls --type image --tag "Text to Image"   # browse
comfy templates show <name>                              # full metadata
comfy templates fetch <name> --out my.json               # pull the workflow JSON
```

下载的 JSON 是前端格式。`comfy run --where cloud` 在提交时自动将其转换为 API 格式。

## 原地编辑工作流

`comfy workflow` 公开了任何前端格式工作流中可被 agent 调整的槽位，并允许您覆盖它们。无需手动处理 JSON。

```bash theme={null}
comfy workflow slots my.json                 # 列出可寻址的槽位
comfy workflow set-slot my.json 6.text="a fox in the snow"
comfy workflow vary my.json \
    --slot positive.text='["a cat","a dog","a fox"]' \
    --out-dir ./variants                     # 生成 N 个变体
```

Comfy Cloud 上已保存的工作流：

```bash theme={null}
comfy workflow list                          # 您已保存的工作流
comfy workflow get <id> --out my.json
comfy workflow save my.json --name "My Flow"
comfy workflow delete <id>
```

对于复杂的多步骤管道，可将小型可复用片段组合成一个画面：

```bash theme={null}
comfy workflow compose blueprints/my_pipeline.yaml -o workflows/my_pipeline.json
comfy workflow decompose my.json             # 反向操作：将工作流投影为片段
```

## 发现节点和模型

对解析的后端上的所有内容进行内省。

**节点：**

```bash theme={null}
comfy nodes search "checkpoint"              # fuzzy search
comfy nodes show KSampler                    # full schema: inputs, outputs, defaults
comfy nodes ls --produces IMAGE --limit 10   # filter by output type
comfy nodes ls --api-only                    # partner-API nodes only
```

**模型：**

```bash theme={null}
comfy models list-folders                    # every model folder
comfy models search --text "wan2.2" --type lora
comfy models show wan2.2_vae.safetensors     # full metadata
```

## 上传和下载文件

```bash theme={null}
comfy upload photo.png video.mp4             # → 服务器输入目录
comfy download <prompt_id>                   # → ./输出/
```

<Tip>
  **惯用管道：**

  ```bash theme={null}
  comfy run --workflow flux.json --wait | comfy download
  ```

  `comfy download` 会从管道标准输入中自动读取 prompt\_id 和输出 URLs，无需手动提取键值，也无需 `jq`。
</Tip>

## 管理自定义节点

```bash theme={null}
comfy node install <NODE_NAME>
```

该工具使用 `cm-cli` 来安装自定义节点。详情请参阅 [ComfyUI 管理器 cm-cli 文档](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/docs/en/cm-cli.md)。

## 管理模型（本地）

轻松下载模型：

```bash theme={null}
comfy model download --url <url> --relative-path models/checkpoints
```

## 脚本和代理的JSON输出

每条指令都接受 `--json` 并以相同的信封形状输出，使CLI完全可脚本化且对代理友好：

```json theme={null}
{
  "ok": true,
  "command": "...",
  "version": "1.11.1",
  "where": "local | cloud | null",
  "data": { },
  "error": null
}
```

当存在 `error` 时，读取 `hint` 并按提示操作：

```bash theme={null}
comfy --json run --workflow my.json | jq '.error.hint'
```

代理面向的接口完全自描述。转储整个指令树、输出模式和错误代码：

```bash theme={null}
comfy --json discover
```

## 代理技能

将捆绑的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 GitHub 仓库](https://github.com/Comfy-Org/comfy-cli/issues) 中创建 Issue 或提交 Pull Request。更多详情请参阅[开发指南](https://github.com/Comfy-Org/comfy-cli/blob/main/DEV_README.md)。

## 分析

使用跟踪有助于改进CLI。可通过以下命令禁用：

```bash theme={null}
comfy tracking disable
```

重新启用跟踪：

```bash theme={null}
comfy tracking enable
```

你也可以通过 `DO_NOT_TRACK` 或 `COMFY_NO_TELEMETRY` 环境变量硬性选择退出。