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

# 시작하기

> comfy-cli 설치, 로컬 또는 클라우드 라우팅 설정, 파트너 노드를 사용한 생성, 터미널에서 워크플로 실행.

## 개요

`comfy-cli`는 Comfy의 설치 및 관리를 간소화하고 로컬 또는 클라우드에서 전체 ComfyUI 생태계에 대해 스크립트 가능한 단일 명령 액세스를 제공하는 [명령줄 도구](https://github.com/Comfy-Org/comfy-cli)입니다.

세 가지 주요 기능을 제공합니다:

1. **로컬 ComfyUI 설치 관리**: ComfyUI 및 커스텀 노드 설치, 실행, 업데이트, 스냅샷, bisect.
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>

셸 자동완성 힌트를 얻으려면:

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

## 빠른 설정 (권장)

최근 버전의 새로운 기능: 한 번에 라우팅, 인증 및 에이전트 기술을 처리하는 단일 대화형 마법사입니다.

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

라우팅 대상(로컬 또는 클라우드) 선택, **브라우저를 통한 로그인(OAuth)**, 프로젝트 디렉터리 선택, 그리고 선택적으로 에이전트 기술 설치 과정을 안내합니다. 이것이 **권장**되는 경로입니다. 복사할 키 없이 브라우저 로그인 창을 열어줍니다.

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

<Note>
  **비대화형(CI 전용).** 브라우저 OAuth는 대화형 세션이 필요합니다. CI, devcontainer 및 브라우저를 사용할 수 없는 스크립트 설치의 경우 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 설치 (로컬)

Python 버전 3.9보다 높은 버전을 사용하여 가상 환경을 생성하세요.

<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>
  **세션 수명.** 클라우드 세션 토큰은 수명이 짧습니다(\~1시간). CLI는 필요에 따라 자동으로 새로 고칩니다. 명령에서 `cloud_unauthorized`를 보고하면 `comfy cloud login`을 다시 실행하세요.
</Note>

## 파트너 노드로 생성하기

<Info>
  **`comfy generate`는 베타 버전입니다.** 플래그명, 모델 별칭 및 출력 형식은 변경될 수 있습니다. 기본 파트너 엔드포인트는 안정적입니다. 피드백은 [comfy-cli GitHub 저장소](https://github.com/Comfy-Org/comfy-cli/issues)에 제출해 주세요.
</Info>

터미널이나 스크립트에서 Comfy의 [파트너 노드](/ko/tutorials/partner-nodes/overview)를 호출하는 가장 빠른 방법입니다. ComfyUI 워크플로와 동일한 호스팅 엔드포인트를 사용하지만, 단일 CLI 호출로 실행됩니다. 전체 ComfyUI 그래프가 필요 없는 배치 작업, 빠른 실험 및 자동화에 이상적입니다.

### 사전 준비 사항

* 활성 Comfy Cloud 세션. `comfy cloud login` 실행 (브라우저 OAuth)
* 계정에 [크레딧](/ko/interface/credits) 보유
* *선택 사항:* 세션 대신 [Comfy API 키](/ko/development/api-development/getting-an-api-key) (`--api-key` / `COMFY_API_KEY`). 헤드리스 또는 CI 환경용
* *선택 사항:* [파트너 노드 및 호출당 가격 찾아보기](/ko/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 (ByteDance): 텍스트 기반 비디오 생성 및 이미지 기반 비디오 생성, 최대 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     # prints a signed URL
```

<Note>
  업로드된 참조 에셋은 **24시간** 이후 자동으로 삭제됩니다. Comfy 관리 GCS에 서명된 URL로 저장됩니다. 오래 실행되는 파이프라인의 경우 각 작업 이전에 다시 업로드하세요. 자세한 내용은 [참조](/ko/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'
```

전체 명령어, 플래그 및 모델 별칭 목록은 [참조](/ko/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>   # ALL이 터미널 상태에 도달할 때까지 차단
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` 명령어는 프론트엔드 형식의 모든 워크플로에서 에이전트가 조정 가능한 슬롯을 노출하고 덮어쓸 수 있게 해줍니다. 수동으로 JSON을 수정할 필요가 없습니다.

```bash theme={null}
comfy workflow slots my.json                 # list addressable slots
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                     # fan out N variants
```

Comfy Cloud에 저장된 워크플로:

```bash theme={null}
comfy workflow list                          # your saved workflows
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             # inverse: project a workflow into a fragment
```

## 노드 및 모델 발견

해결된 백엔드에서 사용할 수 있는 모든 것을 검사하세요.

**노드:**

```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             # → server input directory
comfy download <prompt_id>                   # → ./outputs/
```

<Tip>
  **관용적인 파이프 사용법:**

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

  `comfy download`는 파이프로 연결된 stdin에서 prompt\_id와 출력 URL을 자동으로 읽습니다. 수동으로 키를 추출하거나 `jq`를 사용할 필요가 없습니다.
</Tip>

## 커스텀 노드 관리

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

이 도구는 커스텀 노드 설치를 위해 `cm-cli`를 사용합니다. 자세한 내용은 [ComfyUI Manager 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 Cloud MCP](/ko/agent-tools/cloud)용 **comfy-cloud** Claude Code 플러그인을 호스팅하는 [Comfy Skills](https://github.com/Comfy-Org/comfy-skills/) 저장소와는 별개입니다.
</Note>

## 기여하기

기여를 환영합니다. [comfy-cli GitHub 저장소](https://github.com/Comfy-Org/comfy-cli/issues)에서 이슈를 열거나 풀 리퀘스트를 제출해 주세요. 자세한 세부 정보는 [개발 전용 가이드](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` 환경 변수를 통해 완전히 비활성화할 수도 있습니다.