완전한 Comfy CLI 사용자 가이드

Comfy CLI는 ComfyUI의 공식 명령줄 도구입니다. 터미널에서 ComfyUI를 설치하고, 노드와 모델을 관리하고, 워크플로를 실행하며, 파트너 이미지/비디오 모델을 호출할 수 있습니다.

ℹ️ 업데이트 관련 정보: 최신 CLI 참조 문서는 공식 README 또는 docs.comfy.org에서 확인하세요.

요구 사항

Python 3.10+

설치

권장: pip 사용하기

pip install comfy-cli

pipx 사용 (격리된 환경)

pipx install comfy-cli

uv 사용 (빠른 Python 패키지 설치 도구)

uv tool install comfy-cli

셸 자동 완성

comfy --install-completion

이제 comfy <TAB>을 누르면 명령어와 옵션이 자동 완성됩니다.

빠른 시작

# 대화형 설정 마법사 실행
comfy setup

comfy setup은 로컬 또는 클라우드 라우팅, 인증, 에이전트 스킬 설치 등 모든 과정을 하나의 대화형 마법사로 안내합니다. 비대화형(CI/스크립트) 설치를 위해 -y를 전달하세요.

또는 명시적으로 설치할 수 있습니다:

comfy install

그런 다음 실행하세요:

comfy launch

## 워크스페이스 관리

Comfy CLI는 여러 ComfyUI 워크스페이스 관리를 지원하여, 서로 다른 ComfyUI 환경을 동시에 유지할 수 있습니다.

### 기본 워크스페이스 연산

```bash
# Check current workspace path
comfy which

# Set default workspace
comfy set-default /path/to/your/workspace

# Set default workspace with launch parameters
comfy set-default /path/to/your/workspace --launch-extras="--listen 0.0.0.0 --port 8080"

다른 워크스페이스에서 명령 실행

옵션	사용 사례
`--workspace=<path>`	지정된 워크스페이스에 설치된 ComfyUI에서 실행
`--recent`	가장 최근에 사용된 ComfyUI에서 실행
`--here`	현재 디렉토리의 ComfyUI에서 실행

# Launch ComfyUI in specified workspace
comfy --workspace=~/projects/project-a launch

# Install nodes in recent workspace
comfy --recent node install ComfyUI-Impact-Pack

# Check if current directory has ComfyUI
comfy --here which

참고: --workspace, --recent, --here는 함께 사용할 수 없습니다.

워크스페이스 우선순위 규칙

워크스페이스가 지정되지 않은 경우:

comfy set-default <path>로 설정된 기본 경로
가장 최근에 실행되거나 설치된 ComfyUI
현재 디렉토리의 ComfyUI

실행 옵션

기본 실행

# 기본 실행
comfy launch

# 배경에서 실행
comfy launch --background

# 배경 인스턴스 중지
comfy stop

# 추가 인수로 실행
comfy launch -- --cpu --listen 0.0.0.0

네트워크 구성

comfy launch -- --listen 0.0.0.0 --port 8080

성능 옵션

comfy launch -- --cpu       # CPU 전용 모드
comfy launch -- --lowvram   # 낮은 VRAM 모드
comfy launch -- --novram     # 초저 VRAM 모드

풀 리퀘스트 테스트

# 특정 ComfyUI PR 설치
comfy install --pr "#1234"
comfy install --pr "https://github.com/comfyanonymous/ComfyUI/pull/1234"

# 프런트엔드 PR 테스트
comfy launch --frontend-pr "#456"
comfy launch --frontend-pr "username:branch-name"

프런트엔드 PR 빌드는 빠른 전환을 위해 캐시됩니다. 캐시 관리:

comfy pr-cache list              # 캐시된 PR 빌드 목록
comfy pr-cache clean             # 모든 캐시된 빌드 정리
comfy pr-cache clean 456         # 특정 PR 캐시 정리

## 커스텀 노드 관리

### 노드 정보 보기

```bash
comfy node show all                               # 사용 가능한 모든 노드
comfy node simple-show installed                  # 설치된 노드 간단 목록
comfy node show enabled                           # 활성화된 노드만
comfy node show not-installed                     # 설치되지 않은 노드
comfy node show disabled                          # 비활성화된 노드
comfy node show all --channel recent              # 최근 채널의 노드
comfy node show snapshot                          # 현재 스냅샷 정보 보기
comfy node show snapshot-list                     # 저장된 스냅샷 목록

노드 설치 및 업데이트

comfy node install ComfyUI-Impact-Pack            # 커스텀 노드 설치
comfy node update all                             # 모든 노드 업데이트
comfy node update ComfyUI-Impact-Pack             # 특정 노드 업데이트

빠른 의존성 해결

Comfy CLI는 uv를 활용한 빠른 의존성 해결을 위해 두 가지 방식을 제공합니다:

기능	`--fast-deps`	`--uv-compile`
적용 범위	`comfy install`, 노드 설치/재설치	커스텀 노드 명령어에만
해결 도구	comfy-cli 내장	ComfyUI-Manager v4.1+ 통합 해결 도구
충돌 처리	대화형 프롬프트	노드 귀속 자동 처리

# 빠른 초기 설치
comfy install --fast-deps

# 커스텀 노드 관리를 위한 uv-compile (ComfyUI-Manager v4.1+ 필요)
comfy node install comfyui-impact-pack --uv-compile

# 독립 실행 (기존 모든 커스텀 노드 의존성 해결)
comfy node uv-sync

# --uv-compile을 기본값으로 설정
comfy manager uv-compile-default true

노드 스냅샷 관리

comfy node save-snapshot                           # 현재 스냅샷 저장
comfy node restore-snapshot <snapshot_name>        # 저장된 스냅샷 복원

의존성 관리

comfy node install-deps --workflow=workflow.json   # 워크플로 JSON에서
comfy node install-deps --workflow=workflow.png    # 워크플로 PNG에서
comfy node install-deps --deps=dependencies.json   # 의존성 JSON 파일에서
comfy node deps-in-workflow --workflow=workflow.json --output=deps.json

노드 문제 해결 (Bisect)

버그를 유발하는 커스텀 노드를 찾습니다:

comfy node bisect start                            # Bisect 세션 시작
comfy node bisect good                             # 현재 상태를 정상으로 표시
comfy node bisect bad                              # 현재 상태를 비정상으로 표시
comfy node bisect reset                            # 세션 초기화

## 워크플로 JSON 없이 이미지 생성하기

Comfy CLI는 파트너 이미지 및 비디오 모델을 직접 호출할 수 있습니다 — 워크플로 그래프가 필요 없습니다:

```bash
comfy generate --prompt "a cat on a beach" --model flux/schnell
comfy generate --prompt "anime girl" --model stability/stable-diffusion-3.5
comfy generate --prompt "city street" --model ideogram/ideogram-v2

지원 공급자: FLUX, Ideogram, DALL·E, Recraft, Stability, Gemini, Kling, Luma, Runway, Pika, Vidu, Hailuo, Seedance 등.

클라우드로 라우팅

Comfy Cloud에서 모든 워크플로 실행 (로컬 GPU 불필요):

comfy launch -- --where cloud
# 또는
comfy generate --model recraft/recraft-v3 --where cloud

에이전트를 위한 구조화된 출력

모든 명령은 --json을 지원하여 기계가 읽을 수 있는 출력을 제공합니다 — CI/CD 및 AI 에이전트 통합에 이상적:

comfy generate --prompt "a cat" --model flux/schnell --json

## 모델 관리

### 모델 다운로드

```bash
# Hugging Face에서
comfy model download --url https://huggingface.co/runwayml/stable-diffusion-v1-5/resolve/main/v1-5-pruned.safetensors --relative-path models/checkpoints

# CivitAI에서
comfy model download --url https://civitai.com/api/download/models/123456 --relative-path models/checkpoints

# API 토큰 사용
comfy model download --url https://civitai.com/api/download/models/123456 --set-civitai-api-token YOUR_TOKEN

API 토큰은 환경 변수(CIVITAI_API_TOKEN, HF_API_TOKEN)로 설정할 수도 있으며, CI/CD 환경에서 더 안전합니다.

모델 관리 명령

comfy model list                                  # 기본 경로에서 모델 목록 보기
comfy model list --relative-path models/loras     # 하위 폴더에서 목록 보기
comfy model remove --model-names "model.safetensors"  # 모델 제거

## ComfyUI-매니저 관리

```bash
comfy manager disable-gui                         # 매니저 GUI 비활성화
comfy manager enable-gui                          # 매니저 GUI 활성화
comfy manager clear                               # 예약된 시작 작업 지우기

## 환경 정보

```bash
comfy env                                         # 자세한 환경 정보 표시
comfy tracking status                             # 추적 설정 확인
comfy tracking disable                            # 사용 추적 비활성화
comfy tracking enable                             # 사용 추적 활성화

## 고급 기능

### comfy-lock.yaml (베타)

`comfy-lock.yaml` 파일을 사용하여 프로젝트 의존성을 관리하세요:

```yaml
basic:

models:
  - model: SD1.5 Base
    url: https://huggingface.co/...
    paths:
      - path: models/checkpoints
    hashes:
      - hash: abc123...
        type: SHA256
    type: checkpoint

custom_nodes:
  git_custom_nodes:
    https://github.com/user/ComfyUI-Node:
      disabled: false
      hash: a1b2c3d...

## 일반적인 사용 시나리오

### 개발 환경 관리

```bash
# 안정적인 개발을 위한 워크스페이스 생성
comfy --workspace=~/dev/comfyui-stable install

# 실험적 기능을 위한 워크스페이스 생성
comfy --workspace=~/dev/comfyui-experimental install

# 실험적 노드 설치
comfy --workspace=~/dev/comfyui-experimental node install ComfyUI-AnimateDiff-Evolved

프로젝트 의존성 관리

# 프로젝트 스냅샷 생성
comfy node save-snapshot my-project-v1

# 프로젝트 의존성 복원
comfy node restore-snapshot my-project-v1

# 워크플로 의존성 설치
comfy node install-deps --workflow=project.json

## 문제 해결

### 일반적인 문제

1. **워크스페이스 경로 문제**
   ```bash
   comfy which              # 현재 워크스페이스 확인
   comfy set-default /path  # 올바른 경로로 재설정

노드 충돌

comfy node bisect start  # bisect를 사용하여 문제 노드 찾기

권한 문제

ls -la ~/comfy           # 디렉토리 권한 확인