> ## Documentation Index
> Fetch the complete documentation index at: https://dripart-mintlify-b90d3c69.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 快速入门

### 概述

`comfy-cli` 是一个 [命令行工具](https://github.com/Comfy-Org/comfy-cli)，可以帮助更轻松地安装和管理 Comfy。

它提供两大功能：

1. **管理本地 ComfyUI 安装** — 安装、启动、更新、快照和二分调试 ComfyUI 及其自定义节点。
2. **直接调用托管的合作节点** — 使用一条命令即可从 Seedance、Nano Banana（Gemini）、Grok、Flux、Ideogram、DALL·E、Recraft、Stability、Kling、Luma、Runway、Pika、Vidu、Hailuo、Moonvalley 等合作伙伴生成图片和视频。无需本地 ComfyUI 或工作流 JSON。

### 安装 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
```

### 安装 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
```

## 使用 `comfy generate` 直接调用合作节点（Beta）

<Info>
  **`comfy generate` 目前处于 Beta 阶段。** 参数名称、模型别名及输出格式可能会根据反馈进行调整。底层合作节点接口是稳定的——仍在演进的是 CLI 的使用体验。如有反馈或问题，请提交至 [comfy-cli GitHub 仓库](https://github.com/Comfy-Org/comfy-cli/issues)。
</Info>

<Tip>
  `comfy generate` 是在终端或脚本中调用 Comfy [合作节点](/zh/tutorials/partner-nodes/overview) 的最快方式。它调用的是同一个托管端点——只不过以一次性 CLI 调用的方式——非常适合批量任务、快速实验和自动化管线，而无需搭建完整的 ComfyUI 工作流。
</Tip>

### 前置条件

* [创建 Comfy API 密钥](/zh/development/comfyui-server/api-key-integration)
* [为账户充值积分](/zh/interface/credits)
* 可选：[浏览合作节点及按次定价](/zh/tutorials/partner-nodes/overview)

设置密钥一次，然后即可开始：

```bash theme={null}
export COMFY_API_KEY=comfyui-...   # 或在每次调用时传入 --api-key
```

### 您的首次生成

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

搞定——CLI 会自动上传本地文件、提交任务、轮询至完成，并将结果保存到 `cat.png`。

### 热门模型

以下是一些最常用的合作模型，一行命令即可调用：

```bash theme={null}
# Nano Banana（Google Gemini Flash Image）— 文生图和提示词驱动的编辑
comfy generate nano-banana \
    --prompt "a watercolor of a sleeping fox" \
    --download fox.png

# 同一别名，现在进行图片编辑——传入 --image（可重复使用）作为参考图：
comfy generate nano-banana \
    --prompt "add a top hat" \
    --image ./cat.png \
    --download edited.png

# 选择 Gemini 变体：
comfy generate nano-banana \
    --prompt "neon city skyline" \
    --model gemini-3-pro-image-preview \
    --download city.png

# Seedance（字节跳动）— 文生视频，最高 1080p / 12 秒
comfy generate seedance \
    --prompt "a hummingbird hovering over a flower" \
    --resolution 1080p --duration 5 \
    --download hummingbird.mp4

# Seedance 图生视频——选择 lite/i2v 变体并传入首帧
comfy generate seedance \
    --model seedance-1-0-lite-i2v-250428 \
    --prompt "the wave crests and crashes" \
    --image ./still.jpg \
    --download wave.mp4

# Grok（xAI）— 图片生成和编辑
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

# Grok 视频
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 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
```

如果您希望上传一次后多次复用签名 URL：

```bash theme={null}
comfy generate upload ./photo.jpg
# → 打印一个签名 URL，可作为 --input_image 传入
```

<Note>
  上传的参考资源会在 **24 小时** 后自动删除。它们存储在 Comfy 管理的 GCS 存储桶中，通过签名 URL 提供服务。对于大多数工作流（上传 → 使用 → 完成），这个过程是透明的；对于长时间运行的管线，请在每次任务前重新上传。详情请参见[参考文档](/zh/comfy-cli/reference#upload)。
</Note>

### 视频生成（异步任务）

视频任务是异步的——CLI 默认会阻塞等待，轮询至完成：

```bash theme={null}
comfy generate kling \
    --prompt "a paper boat drifting on a river at dusk" \
    --duration 5 \
    --download boat.mp4
```

传入 `--async` 可立即返回任务 ID，稍后继续：

```bash theme={null}
comfy generate luma --prompt "neon koi swimming through clouds" --aspect_ratio 16:9 --async
# → 打印任务 ID；稍后继续：
comfy generate resume luma <job_id> --download out.mp4
```

### 通过 JSON 输出编写脚本

对于管线，`--json` 可以输出原始 API 响应：

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

完整命令、参数和模型别名列表请参见[参考文档](/zh/comfy-cli/reference)。

## 管理自定义节点

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

我们使用 `cm-cli` 来安装自定义节点。更多信息请参阅 [文档](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/docs/en/cm-cli.md)。

## 管理模型

使用 `comfy-cli` 下载模型非常简单。只需运行以下命令：

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

## 贡献

我们鼓励对 comfy-cli 做出贡献！如果您有建议、想法或错误报告，请在我们的 [GitHub 仓库](https://github.com/Comfy-Org/comfy-cli/issues) 上提交问题。如果您想贡献代码，请 fork 仓库并提交 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
```